​
Create a NGN Payout Example

This endpoint allows users to send payouts in NGN to recipients in Nigeria. The request must include recipient details, payment method, and payout amounts.

​
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

​
Sample cURL Request

curl --location --request POST '{{baseURL}}/v1/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--form '{
  "recipient": {
    "name": "Adeolu Adebayo",
    "firstName": "Adeolu",
    "lastName": "Adebayo",
    "type": "INDIVIDUAL",
    "account": {
      "accountNumber": "0123456789",
      "bankCode": "044"
    },
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "country": "NG"
  },
  "quoteId": "d19a64f9-5a47-4bda-b7c2-0e8de5aeb13f",
  "reason": "Invoice Payment"
}'

​
Request Body

The following fields are required when making an NGN payout request:
FieldTypeDescriptionRequired
recipient.nameStringFull name of the recipient✅ Yes
recipient.firstNameStringFirst name of the recipient✅ Yes
recipient.lastNameStringLast name of the recipient✅ Yes
recipient.typeStringRecipient type (e.g., INDIVIDUAL, BUSINESS)✅ Yes
recipient.account.accountNumberStringRecipient’s bank account number✅ Yes
recipient.account.bankCodeStringBank code of the recipient’s bank✅ Yes
recipient.paymentChannelStringPayment method (BANK_TRANSFER, MOBILE_WALLET)✅ Yes
recipient.currencyStringNGN (Nigerian Naira)✅ Yes
recipient.countryStringNG (Nigeria)✅ Yes
quoteIdStringUnique Quote ID for the payout✅ Yes
reasonStringReason for the payout (e.g., Gift, Invoice Payment)✅ Yes

​
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": "Invoice Payment",
        "reason": "Invoice Payment",
        "referenceNumber": "TXYZD6RWSQMKF",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
            "id": "d19a64f9-5a47-4bda-b7c2-0e8de5aeb13f",
            "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": "0123456789",
                "bankCode": "044"
            },
            "paymentChannel": "BANK_TRANSFER",
            "currency": "NGN",
            "country": "NG"
        },
        "created": "2025-02-27T14:17:48.038044",
        "processed": "2025-02-27T14:20:49.712685"
    }
}

​
Payout Transaction States

The payout transaction can have one of the following states:
StateDescription
COMPLETEDThe payout was successfully processed.
PENDINGThe payout is still being processed.
FAILEDThe payout failed to process.
REFUNDEDThe payout has been sent back to sender.

​
Error Handling

Status CodeMeaningExample Response
400Bad RequestInvalid parameters
401UnauthorizedInvalid API key
422Unprocessable EntityInvalid quote ID
500Internal Server ErrorAn 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.