Sub-merchants

Segment your own customers, branches, or tenants.

Sub-merchants let you segment your own customers, branches, or tenants inside Xental. They are internal records — not created on any external provider.

Reference unique per tenant

Two of your sub-merchants can't share a reference, but a reference you use is independent of what other Xental accounts use.

get/api/v1/sub-merchants

List the current tenant's sub-merchants.

Requires Bearer token

Responses

200OK

GET /api/v1/sub-merchants

curl -X GET "https://api.xental.online/api/v1/sub-merchants" \
  -H "Authorization: Bearer <API_TOKEN>"

post/api/v1/sub-merchants

Create a sub-merchant under the current account.

Requires Bearer token

Body parameters

namestringoptional

referencestringoptional

Responses

201Created409Conflict

POST /api/v1/sub-merchants

curl -X POST "https://api.xental.online/api/v1/sub-merchants" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace"
  }'

Example request body

{
  "name": "Ada Lovelace"
}

put/api/v1/sub-merchants/{id}/payout

Set the sub-merchant's payout account + platform fee. The account is bank-verified (NUBAN name-match) and the settlement worker routes this sub-merchant's collections here.

Requires Bearer token

Path parameters

idstringrequired

Body parameters

bankNamestringoptional

bankCodestringoptional

accountNumberstringoptional

platformFeeBpsintegeroptional

Responses

200OK400Payout account could not be verified.404Not Found

PUT /api/v1/sub-merchants/{id}/payout

curl -X PUT "https://api.xental.online/api/v1/sub-merchants/:id/payout" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "platformFeeBps": 8000
  }'

Example request body

{
  "platformFeeBps": 8000
}

get/api/v1/sub-merchants/{id}/balance

Collected / settled / pending balance for a sub-merchant (net kobo).

Requires Bearer token

Path parameters

idstringrequired

Responses

200OK404Not Found

GET /api/v1/sub-merchants/{id}/balance

curl -X GET "https://api.xental.online/api/v1/sub-merchants/:id/balance" \
  -H "Authorization: Bearer <API_TOKEN>"