Skip to main content
This endpoint allows you to send payouts in Nigerian Naira (NGN) to recipients in Nigeria. The request must include the recipient’s details, payment method, and a valid quoteId.

​
Endpoint

POST: {{baseURL}}/v2/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}}/v2/payout' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "remark": "Testing",
  "reason": "Gift",
  "invoice": "4b9b6d30-a2ed-421a-bd69-11536344f071",
  "quoteId": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
  "recipient": {
    "name": "Adeolu Adebayo",
    "paymentChannel": "BANK_TRANSFER",
    "currency": "NGN",
    "country": "NG",
    "account": {
      "bankName": "GT Bank",
      "accountNumber": "001040XXXXX",
      "sortCode": "058"
    }
  }
}'
Note: Recipient’s name and Bank name must match the details in the Bank list endpoint and Account enquiry endpoint.

​
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).
invoiceStringOptional identifier for the invoice (returned from file upload endpoint).
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.sortCodeStringThe 3-digit bank unique code (e.g., 058 for GTBank).

​
Success Response (200 OK)

If the payout is successfully created, the API returns the following response:
copy
{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "remark": "Testing",
    "invoice": "4b9b6d30-a2ed-421a-bd69-11536344f071",
    "reason": "Gift",
    "referenceNumber": "TXYZD6RWSQMKF",
    "type": "SEND",
    "state": "COMPLETED",
    "quote": {
      "id": "91e58c2d-ef14-4777-906b-xxxxxxxxxxxxx",
      "source": {
        "currency": "NGN",
        "country": "NG",
        "amount": 100000
      },
      "target": {
        "currency": "NGN",
        "country": "NG",
        "amount": 100000
      },
      "rate": 1,
      "fee": {
        "amount": 100
      }
    },
    "recipient": {
      "name": "Adeolu Adebayo",
      "firstName": "Adeolu",
      "lastName": "Adebayo",
      "relationship": "SELF",
      "type": "BUSINESS",
      "account": {
        "bankName": "GT Bank",
        "accountNumber": "001040XXXXX",
        "sortCode": "058"
      },
      "paymentChannel": "BANK_TRANSFER",
      "currency": "NGN",
      "country": "NG"
    },
    "created": "2025-08-22T10:55:48.038044",
    "processed": "2025-08-22T10:58:49.712685"
  }
}

​
Response Breakdown

FieldTypeDescription
messageStringConfirmation message indicating the result of the request.
statusStringOverall status of the request (success).
dataObjectContainer for the payout transaction details.
data.idStringUnique identifier for the payout transaction.
data.remarkStringOptional note about the transaction, as provided in the request.
data.invoiceStringOptional identifier for the invoice, as provided in the request.
data.reasonStringReason for the payout, as provided in the request.
data.referenceNumberStringUnique reference number generated for the payout.
data.typeStringType of transaction (e.g., SEND).
data.stateStringCurrent state of the payout (COMPLETED, PENDING, FAILED, REFUNDED).
data.quote.idStringUnique ID of the quote used for the transaction.
data.quote.source.currencyStringCurrency of the source funds (NGN).
data.quote.source.countryStringISO country code of the source (NG).
data.quote.source.amountNumberAmount debited from the source.
data.quote.target.currencyStringCurrency received by the recipient (NGN).
data.quote.target.countryStringISO country code of the recipient (NG).
data.quote.target.amountNumberAmount credited to the recipient.
data.quote.rateNumberConversion rate applied (1 for NGN → NGN).
data.quote.fee.amountNumberFee charged for the payout.
data.recipient.nameStringFull name of the recipient.
data.recipient.firstNameStringRecipient’s first name.
data.recipient.lastNameStringRecipient’s last name.
data.recipient.relationshipStringRelationship to account holder (e.g., SELF).
data.recipient.typeStringRecipient type (BUSINESS).
data.recipient.account.accountNumberStringRecipient’s bank account number.
data.recipient.account.sortCodeStringBank unique code (e.g., 058 for GTBank).
data.recipient.account.bankNameStringName of the recipient’s bank.
data.recipient.paymentChannelStringPayment method used (BANK_TRANSFER).
data.recipient.currencyStringCurrency of the recipient’s account (NGN).
data.recipient.countryStringRecipient’s ISO country code (NG).
data.createdStringISO 8601 timestamp when the transaction was created.
data.processedStringISO 8601 timestamp when the transaction was processed.

​
Error Handling

Status CodeMeaningExample Response
400Insufficient BalanceInsufficient Balance
401UnauthorizedInvalid API key provided.
403ForbiddenIP not whitelisted
404Not FoundThe requested endpoint does not exist.
422Unprocessable EntityInvalid quote ID provided.
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.
Testing Failed Payouts: In the sandbox environment, you can simulate a failed payout by setting "remark": "fail" in your request. This triggers a payout.failed webhook, allowing you to test your error handling.