Create an outlet
Creates an Outlet and provisions, in one atomic transaction:
- A collection wallet — receives customer payments via a permanent
virtual account that is also issued in this call. The
accountNumberis returned in the response so the partner can display it to customers. - A deposit wallet — empty on creation; funded later by
POST /transfer/internalfrom the partner’s main deposit wallet. Used by the Outlet to pay out to customers viaPOST /transfer. - The Outlet row that ties both wallets to a single
outletId.
Emits outlet.created to your registered webhook on success.
External reference uniqueness
Pass an externalReference to deduplicate create requests. The value is unique per Business; re-posting the same externalReference returns 422 EXTERNAL_REFERENCE_DUPLICATE instead of creating another outlet. To resolve a partner-side reference back to its existing outlet, use GET /outlets?search=<ref> rather than retrying the create.
Common 422 reasons
| Code / message | Why |
|---|---|
EXTERNAL_REFERENCE_DUPLICATE: an outlet already exists with externalReference=... | The reference already maps to an outlet under your Business. Either reuse via GET /outlets?search=<ref>, or pick a new reference |
accountName is required / accountName cannot exceed 200 characters | Validation; accountName is mandatory and capped at 200 chars (so the appended (deposit) suffix on the deposit wallet’s stub account does not overflow the underlying account_storages.account_name column) |
INVALID_TENANT | Your underlying User has no agent assignment. Internal Kele state — escalate to support; not something the partner can fix client-side |
Webhook on success
An outlet.created event is dispatched to your configured webhook URL after the outlet row commits. The payload mirrors the synchronous response. If your webhook receiver returns non-2xx, the dispatcher retries with exponential backoff per the standard outgoing-webhook policy.
Authorizations
Partner public key (pk_live_… or pk_test_…). Required on every request.
Partner secret. Used in the v1-static profile only.
Body
Capped at 200 so the appended ' (deposit)' suffix on the deposit wallet's stub account stays under the 225-char account_storages.account_name column.
Optional partner-side correlation id (your outlet id, etc.).
Response
Boolean success flag.
HTTP status code mirrored in the body for convenience.
A partner outlet. Owns exactly two wallets:
collectionWallet— fronts a permanent virtual account; receives customer payments.depositWallet— funded by the partner; used to pay customers.