Skip to main content
POST
Create cash payment
Initiates a cash payout to a fiat beneficiary.

Authorizations

x-api-key
string
header
required

Requires authentication via API key and HMAC signature.

  • x-api-key: Your API key generated from your Onboard Business dashboard.
  • x-timestamp: Unix epoch timestamp (seconds) used in signature, allowed skew is 30 seconds
  • x-signature: SHA256 HMAC HEX signature calculated over t={x-timestamp}&{requestBody} using your API Secret.

Body

application/json

Details required to create a cash payment. The amount and currency must align with an existing quote.

quoteId
string<uuid>
required

Identifier of an existing cash payment quote, retrieved from the cash payment quote endpoint.

accountId
string<uuid>
required

Account to debit for this payment. Can be the main account ID or a sub-account ID.

reference
string
required

Alpha-numeric transfer reference, unique for this transfer.

Required string length: 8 - 48
Pattern: ^[a-zA-Z0-9_-]{8,48}$
Example:

"CTR123456"

amount
number
required
Required range: x > 0
beneficiaryId
string<uuid>
required

Identifier of an existing beneficiary to whom the transfer will be made.

paymentReason
string
required

Reason for the payment, to be provided at the time of transfer creation.

unitCurrency
string

Should be same as one of payout or account currencies in the quote. Defaults to account currency if not provided.

narration
string

Notes to be included in the transfer.

Response

Cash payment created

The payment initiation response

id
string
required
Example:

"P12005E1DV"

status
enum<string>
required

Status of the transaction, indicating its current state in the processing lifecycle.

  • PENDING: The transaction has been created but not yet processed.
  • IN_PROGRESS: The transaction is currently being processed.
  • FAILED: The transaction processing has failed.
  • SUCCESS: The transaction has been successfully processed.
Available options:
PENDING,
IN_PROGRESS,
FAILED,
SUCCESS
awaiting2fA
boolean
default:false
required

Indicates if transfer is awaiting 2FA confirmation. This applies mostly to transaction initiated via dashboard

twoFaMethod
enum<string>[]

List of 2fa enabled

Available options:
AUTHENTICATOR_APP,
EMAIL,
SMS