Initiate Payout

https://sandboxapi.onbrails.com/api/v2/wallets/payout/initialize (opens in a new tab)

Initiate a payout to a bank account or mobile money wallet.

New Flow (recommended)

Call the Quote endpoint to retrieve the exchange rate, fee, and expiry for the transaction.
Create the payout using either:
- beneficiaryId — an already indexed beneficiary, or
- beneficiary — the beneficiary details directly, without creating a beneficiary first.

The beneficiary payload uses the same schema as the Beneficiary object.

Body Parameters

Parameter	Type	Required	Description
amount	`int64`	✅	Amount to send, in the lowest denomination (minor units) e.g. 1 USD = 100
sourceWalletCurrency Wallet from which payout is to be initiated	`string`	✅	Defaults to USD
customerEmail	`string`	✅	The email address of the customer associated with the transaction
description	`string`	✅	Provides context or explains the intent of the transaction
beneficiaryId	`string`	✅ (either)	ID of an existing indexed beneficiary. Mutually exclusive with `beneficiary`
beneficiary	`object`	✅ (either)	Beneficiary details, using the same schema as the Beneficiary object. Mutually exclusive with `beneficiaryId`

⚠️

Amounts are in minor units. The amount must always be provided in the lowest denomination of the sourceWalletCurrency — for example, 1 USD is sent as 100 (cents).

📘

Provide either beneficiaryId or beneficiary — not both. When providing the beneficiary object directly, only the fields required to identify the beneficiary are needed (the same fields used when creating a beneficiary).

Request

Wallets/Initiate Payout [POST]

curl --request POST \
     --url https://sandboxapi.onbrails.com/api/v2/wallets/payout/initialize \
     --header 'Authorization: Bearer YOUR_SECRET_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 11300,
  "customerEmail": "youknowwho@gmail.com",
  "description": "Try",
  "sourceWalletCurrency": "USD",
  "beneficiary": {
    "country": "NG",
    "currency": "NGN",
    "destination": {
      "type": "BANK",
      "bankCode": "110072",
      "bankName": "78 FINANCE COMPANY LIMITED",
      "accountName": "Joe Zen",
      "accountNumber": "0691110031"
    }
  }
}
'

Alternatively, pass an existing beneficiary using beneficiaryId:

Wallets/Initiate Payout with existing beneficiary [POST]

{
  "amount": 11300,
  "customerEmail": "youknowwho@gmail.com",
  "description": "Try",
  "sourceWalletCurrency": "USD",
  "beneficiaryId": "1be2b747-29e6-4fc9-88cd-0895f7e22165"
}

Legacy Flow (backward compatibility)

The legacy flow for backward compatibility is:

Initiate Payout
Finalize Payout — authorize and finalize the already initiated payout.

📘

The legacy flow is kept for backward compatibility. New integrations should use the new flow: retrieve a Quote, then initiate the payout.

Responses

🟢 200 - Result example

{
"status": true,
"message": "Payout Initialized Successfully",
"data": {
  "id": "e6d06d21-73c8-471b-9e5b-9171920ab4ea",
  "createdAt": "2023-08-17T16:13:30.635Z",
  "updatedAt": "2023-08-17T16:13:30.635Z",
  "companyId": "65f8ecbc-f7dd-4753-9cd4-dda9a3e396cb",
  "customerId": "4bf15cb3-97a6-4072-9683-aa3c6d7233df",
  "centFees": 0,
  "type": "debit",
  "reference": "HjdYJWumFMnNyUp",
  "channel": "payout",
  "description": "test payout",
  "status": "initiated",
  "action": "ngn_account_payout",
  "fees": 0,
  "amount": 1.13,
  "centAmount": 113,
  "spotPrice": 879
}
}

Initialize Collection [POST]Finalize Payout [POST]