📣 New Region Unlocked: You can now send payouts directly to Malawi! 🇲🇼
Payouts
Create Payout Examples
NGN to NGN

NGN Payouts

This endpoint allows you to send payouts in NGN to recipients in Nigeria. The request must include the recipient's details, payment method, and a valid quoteId.

Endpoint

POST: {{baseURL}}/v1/payout

Request Details

Headers

Include these headers in your request:

HeaderValueRequired
Content-Typeapplication/json✅ Yes
x-api-keyYOUR_API_KEY✅ Yes

Request Examples

curl --location --request POST '{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "remark": "Testing",
  "reason": "Gift",
  "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Adeolu Adebayo",
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "country": "NG",
    "account": {
      "bankName": "GT Bank",
      "accountNumber": "001040XXXXX",
      "bankCode": "058"
    }
  }
}'

Request Body

The following fields are required when making an NGN payout request:

FieldTypeDescription
remarkStringAdditional note about the transaction.
reasonStringPurpose of the transfer (e.g., Gift).
quoteIdStringUnique Quote ID for the payout.
recipient.nameStringFull name of the recipient.
recipient.paymentChannelStringPayment method (BANK_TRANSFER).
recipient.currencyStringISO currency code (NGN).
recipient.countryStringISO country code (NG).
recipient.account.bankNameStringName of the recipient's bank.
recipient.account.accountNumberStringRecipient’s bank account number.
recipient.account.bankCodeStringThe 3-digit bank code (e.g., 058 for GTBank).

Success Response (200 OK)

If the payout is successfully created, the API returns the following response:

{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "remark": "Testing",
    "reason": "Gift",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
      "source": {
        "currency": "USD",
        "country": "US",
        "amount": 100
      },
      "target": {
        "currency": "NGN",
        "country": "NG",
        "amount": 147000
      },
      "rate": 1470,
      "fee": {
        "amount": 500
      }
    },
    "recipient": {
      "name": "Adeolu Adebayo",
      "firstName": "Adeolu",
      "lastName": "Adebayo",
      "relationship": "SELF",
      "type": "BANK",
      "account": {
        "accountNumber": "001040XXXXX",
        "bankCode": "058"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "NGN",
      "country": "NG"
    },
    "created": "2025-08-22T10:55:48.038044",
    "processed": "2025-08-22T10:58:49.712685"
  }
}

Error Handling

Status CodeMeaning                 Example Response                         
400       Bad Request             Invalid parameters   
401       Unauthorized             Invalid API key     
422       Unprocessable Entity     Invalid quote ID     
500       Internal Server Error   An internal error occurred

Best Practices

✅ Ensure quoteId is valid and linked to an existing quote.
✅ Confirm that the recipient’s bank account number and bank code are correct.
✅ Use a valid API key in the headers.
✅ Handle error responses correctly in your integration.