Create a merchant

The canonical merchant-creation API for all products. Requires org:merchants:write. Sales App generates the id; clients cannot supply an id or organization. The verified token selects the tenant (Cowdi uses the organic book). Creates an opportunity with its initial activity and optional employee assignment in one transaction. Reuse idempotency_key with identical details to recover the same id after a timeout. A changed request or a phone/ID owned by another merchant returns 409. user_id links the merchant to an existing Cowdi user (a service onboarding one of its users); one merchant per user per organization, so naming a user already linked there returns that merchant with 200 instead of creating another. Core registration must use the returned id; it does not generate another identity. Product setup, invitations and activation remain separate lifecycle operations.

Authorization

oauth2

AuthorizationBearer <token>

Create a client with POST /v1/oauth/clients, then exchange its credentials for an access token. AUTHORIZATION_CODE clients act on behalf of a signed-in user and always use PKCE; CLIENT_CREDENTIALS clients act as themselves. A client may only be granted scopes its creator already holds — read the grantable list from GET /v1/oauth/clients/scopes.

In: header

Request Body

application/json

name?string

Length1 <= length <= 255

phone_number?string

email?|

Lengthlength <= 320

date_of_birth?|

Formatdate

gender?|

Value in

"FEMALE"
"MALE"
null

religion?|

Lengthlength <= 120

id_number?|

Length1 <= length <= 64

business_name?|

Lengthlength <= 255

business_type?|

Lengthlength <= 120

store_type?|

Value in

"BRICK_AND_MORTAR"
"KIOSK"
"SHENZY_STORE"
"NO_STORE"
null

merchant_category?|

Value in

"M_PESA"
"FISH"
"HOTEL_AND_RESTAURANT"
"SNACKS"
"GROCERIES"
"RETAIL_SHOP"
"CLOTHES"
"SALON"
"CHEMISTRY"
"CEREALS"
"FARMERS_AND_FEEDS"
"HARDWARE_AND_ELECTRONICS"
"LIQUOR_STORE"
"SPARE_PARTS"
"CONSTRUCTION_AND_MATERIALS"
"OTHER"
null

branch?|

Lengthlength <= 120

address?|

Lengthlength <= 500

is_business_registered?boolean|null

business_age_months?|

Range0 <= value

requested_amount?|null

approved_limit?|null

requested_tenure?|null

monthly_turnover?|

Value in

"LESS_THAN_KSH_50_000"
"BETWEEN_KSH_50_000_TO_KSH_75_000"
"BETWEEN_KSH_75_000_TO_KSH_150_000"
"BETWEEN_KSH_150_000_TO_KSH_300_000"
"MORE_THAN_KSH_300_000"
null

goods_turnover?|null

margin?|

Value in

"<5%"
"5-10%"
"10-15%"
"15-30%"
"30-50%"
"50-75%"
"75-100%"
">100%"
null

risk_level?|

Value in

"0"
"10"
"20"
"30"
"40"
"50"
"60"
"70"
"80"
"90"
"100"
"LOW"
"MEDIUM"
"HIGH"
"ERROR"
null

can_renew?boolean|null

source?|

Lengthlength <= 120

referred_by?|

Lengthlength <= 255

next_of_kin_name?|

Lengthlength <= 255

next_of_kin_relationship?|

Lengthlength <= 120

next_of_kin_phone_number?string|null

document_reviews?|null

idempotency_key?string

Formatuuid

customer_id?string

Length1 <= length <= 255

external_id?string

Length1 <= length <= 255

user_id?string

Length1 <= length <= 255

status?string

Value in

"LEAD"
"CONTACTED"
"PROSPECT"
"QUALIFIED"
"PENDING"
"REJECTED"
"OPPORTUNITY"
"PHONE_VERIFICATION"
"PHYSICAL_VERIFICATION"
"APPROVED"
"DOCUMENT_PENDING"
"HOLD"

assigned_employee_id?string

Formatuuid

latitude?number

Range-90 <= value <= 90

longitude?number

Range-180 <= value <= 180

location_accuracy?number

Range0 <= value

Response Body

`application/json`

curl -X POST "https://example.com/v1/merchants" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "date_of_birth": "2019-08-24",  "gender": "string",  "religion": "string",  "id_number": "string",  "personal_id_front": "string",  "personal_id_back": "string",  "business_name": "string",  "business_type": "string",  "store_type": "string",  "merchant_category": "string",  "address": "string",  "is_business_registered": true,  "business_age_months": 0,  "phone_number": "string",  "email": "string",  "monthly_turnover": "string",  "goods_turnover": {    "duration": 1,    "unit": "DAYS"  },  "margin": "string",  "risk_level": "string",  "can_renew": true,  "requested_amount": {    "value": 0,    "currency": "KES"  },  "requested_tenure": {    "duration": 1,    "unit": "DAYS"  },  "source": "string",  "referred_by": "string",  "branch": "string",  "latitude": 0,  "longitude": 0,  "location_accuracy": 0,  "next_of_kin_name": "string",  "next_of_kin_relationship": "string",  "next_of_kin_phone_number": "string",  "transunion_screenshot": "string",  "merchant_photo": "string",  "business_registration_permit": "string",  "proof_of_business": "string",  "picture_of_store_front": "string",  "picture_of_store_stocks": "string",  "document_reviews": {    "property1": null,    "property2": null  },  "approved_limit": {    "value": 0,    "currency": "KES"  },  "status": "string",  "local_id": "string",  "external_id": "string",  "organization_id": "string",  "onboarding_status": "string",  "migration_status": "NOT_MIGRATED",  "user_id": "string",  "account_id": "string",  "migration_error": "string",  "activated_at": "2019-08-24T14:15:22Z",  "assigned_employee": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "phone_number": "string",    "name": "string",    "role": "string",    "is_active": true  },  "onboarded_by_employee": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "phone_number": "string",    "name": "string",    "role": "string",    "is_active": true  },  "statements": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "type": "PERSONAL",      "document_key": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "date_of_birth": "2019-08-24",  "gender": "string",  "religion": "string",  "id_number": "string",  "personal_id_front": "string",  "personal_id_back": "string",  "business_name": "string",  "business_type": "string",  "store_type": "string",  "merchant_category": "string",  "address": "string",  "is_business_registered": true,  "business_age_months": 0,  "phone_number": "string",  "email": "string",  "monthly_turnover": "string",  "goods_turnover": {    "duration": 1,    "unit": "DAYS"  },  "margin": "string",  "risk_level": "string",  "can_renew": true,  "requested_amount": {    "value": 0,    "currency": "KES"  },  "requested_tenure": {    "duration": 1,    "unit": "DAYS"  },  "source": "string",  "referred_by": "string",  "branch": "string",  "latitude": 0,  "longitude": 0,  "location_accuracy": 0,  "next_of_kin_name": "string",  "next_of_kin_relationship": "string",  "next_of_kin_phone_number": "string",  "transunion_screenshot": "string",  "merchant_photo": "string",  "business_registration_permit": "string",  "proof_of_business": "string",  "picture_of_store_front": "string",  "picture_of_store_stocks": "string",  "document_reviews": {    "property1": null,    "property2": null  },  "approved_limit": {    "value": 0,    "currency": "KES"  },  "status": "string",  "local_id": "string",  "external_id": "string",  "organization_id": "string",  "onboarding_status": "string",  "migration_status": "NOT_MIGRATED",  "user_id": "string",  "account_id": "string",  "migration_error": "string",  "activated_at": "2019-08-24T14:15:22Z",  "assigned_employee": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "phone_number": "string",    "name": "string",    "role": "string",    "is_active": true  },  "onboarded_by_employee": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "email": "user@example.com",    "phone_number": "string",    "name": "string",    "role": "string",    "is_active": true  },  "statements": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "type": "PERSONAL",      "document_key": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

{  "code": "INVALID_PARAMS",  "description": "user_id must be a UUID",  "identifier": "string",  "invalid_params": [    {      "path": "user_id",      "reason": "must be a UUID",      "sub_code": "string"    }  ]}

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`