Payouts

Pay out to the customer's own verified contact identifier

POST/api/v1/tenant/payouts

Scope payouts:write · Write — send Idempotency-Key and X-Request-Id

Sends money from a customer wallet through a payment provider, in two phases. Phase 1 is synchronous: the payment provider (railCode) must be active and able to send payouts, the destination a verified contact identifier of the wallet's customer, and the assertion bound to this request; the customer's KYC-level limits, the amount above which two-factor authentication is required, compliance checks and available ≥ amount + fee + tax are checked. The wallet is then debited for the total, with the charges itemized, and the amount is held until the payment provider answers. The response is the operation in state processing. Phase 2 is asynchronous: payout.confirmed, payout.failed (amount and refundable charges returned to the wallet) or payout.uncertain is delivered to your webhook as the payment provider reports back.

Request body

Field	Type	Required	Description
walletUid	string	yes	The wallet to pay out from, as returned by POST /tenant/customers.
destinationIdentifierUid	string	yes	A verified contact identifier of the wallet's customer (payoutEligible on GET /tenant/customers/{uid}/identifiers); anything else is refused.
amountMinor	number	yes	Positive integer minor units (e.g. 250000 = ETB 2,500.00); the amount the destination receives. Min 1.
currency	string	yes	ISO-4217; must equal the wallet's currency.
railCode	string	yes	The payment provider's code to pay out on; the provider must be active and support payouts. At most 64 characters.
clientReference	string	yes	Your own reference; stored and returned verbatim, never interpreted; unique within your account.
assertion	object	yes	The customer's authentication for this payout.
assertion.customerUid	string	yes	The customer who authenticated.
assertion.identifierUid	object	no	The customer identifier the customer authenticated with, if known.
assertion.assuranceLevel	enum	yes	How strongly your channel authenticated the customer. One of single_factor, two_factor, step_up.
assertion.factor1Type	string	yes	The first factor used, e.g. pin, password, biometric. At most 32 characters.
assertion.factor2Type	object	no	Required unless assuranceLevel is single_factor. At most 32 characters.
assertion.authenticatedAt	string	yes	ISO-8601 — when the customer authenticated.
assertion.expiresAt	string	yes	ISO-8601; by default at most 10 minutes after authenticatedAt. An expired assertion is refused (422).
assertion.channelCode	string	yes	Your channel the customer authenticated on. At most 40 characters.
assertion.deviceHash	object	no	SHA-256 hex of the device fingerprint, if your channel has one.
assertion.sourceReference	string	yes	Opaque channel evidence reference (a session or login id). Presenting one again while it is live is allowed only for the same customer, and is audited. At most 160 characters.
assertion.transactionBinding	object	no	Hash your channel computed over the request this assertion authorizes; a mismatch with the request received is refused.
assertion.transactionBinding.hash	string	yes	SHA-256 hex (64 characters) over the canonical string of this request.
assertion.transactionBinding.algorithm	enum	yes	One of sha256.
assertion.transactionBinding.canonical	enum	yes	The field template hashed: the six values joined with |, UTF-8. The fifth is the payout destination, the mandate for a debit, or empty; clientReference is empty when absent. One of `customerUid
feeQuoteId	object	no	A quoteId from POST /tenant/fees/quote to pin the charges to; while still valid the quoted amounts are used and must equal a fresh computation, otherwise the charges are computed fresh. At most 64 characters.

Example (generated from the schema)

{
  "walletUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "destinationIdentifierUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "amountMinor": 1,
  "currency": "ETB",
  "railCode": "string",
  "clientReference": "string",
  "assertion": {
    "customerUid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
    "assuranceLevel": "single_factor",
    "factor1Type": "string",
    "authenticatedAt": "2026-09-03T10:15:30.000Z",
    "expiresAt": "2026-09-03T10:15:30.000Z",
    "channelCode": "string",
    "sourceReference": "string"
  }
}

Response · 202

Field	Type	Description
uid	string
type	string	Operation type, e.g. wallet_credit, wallet_debit, payout_b2c or topup_c2b.
state	string	Operation state: created, awaiting_authorization, authorized, held, processing, pending_provider, confirmed, failed, reversed or completed.
amountMinor	number	Integer minor units (e.g. 250000 = ETB 2,500.00).
feeMinor	number	Minor units.
taxMinor	number	Minor units.
currency	string	ISO-4217.
clientReference	string | null	Your reference, exactly as you supplied it.
createdAt	string
completedAt	string | null	When the operation first reached a final state.
links	object
links.self	string	API-relative path of this operation (GET /tenant/operations/{uid}).
links.receipt	string	API-relative path of its receipt (GET /tenant/operations/{uid}/receipt).

Example (generated from the schema)

{
  "uid": "01J9Z3K5X8QW2R4T6V8Y0B1C3D",
  "type": "string",
  "state": "string",
  "amountMinor": 0,
  "feeMinor": 0,
  "taxMinor": 0,
  "currency": "ETB",
  "clientReference": "string",
  "createdAt": "2026-09-03T10:15:30.000Z",
  "completedAt": "2026-09-03T10:15:30.000Z",
  "links": {
    "self": "string",
    "receipt": "string"
  }
}

Errors

400 401 403 404 409 422 429 500 503 — one body shape for all of them, see Errors.