Skip to main content
POST
Create cash deposit
Creates a disposable cash deposit account for a single transaction.

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 deposit. The amount and currency must align with an existing quote.

quoteId
string<uuid>
required

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

accountId
string<uuid>
required

Account to credit for this deposit. Can be the main account ID or a sub-account ID.

reference
string
required

Alpha-numeric deposit reference, unique for this deposit.

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

"CTR123456"

amount
number
required
Required range: x > 0
unitCurrency
string

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

senderInfo
object

Identifies the party sending fiat for the deposit. When omitted on a deposit request, it is constructed from the business details.

narration
string

Notes to be included with the deposit.

Response

Cash deposit created

Details of a cash deposit transaction.

id
string<uuid>
required
reference
string
required

Reference for the cash deposit transaction at initiation.

currency
string
required

Currency in which the account was credited.

Example:

"USD"

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
payinCurrency
string
required

Currency the customer paid in.

Example:

"NGN"

amount
number
required

Amount credited to the account.

Example:

100

rate
number
required

Exchange rate applied for this deposit.

Example:

1450.75

payinAmount
number
required

Amount the customer paid in, in the pay-in currency.

Example:

145075

createdDate
string<date-time>
required
accountTransactionId
string

Identifier of the credit transaction on the account.

providerReference
string

Reference provided by the cash deposit provider.

Example:

"PROV123456"

paymentDetails
object

Destination account details the customer must pay into to fund the deposit. Mirrors a Beneficiary (without an id). Carries only the account details needed to make the payment; transaction context (amount, status, etc.) lives on the enclosing CashDepositTransaction.

details can be nullable when the account number provider is still generating it