Skip to main content
POST
/
v1
/
payouts
Payout
curl --request POST \
  --url https://carbonapistagingsecure.getcarbon.co/baas/api/v1/payouts \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --header 'x-carbon-key: <x-carbon-key>' \
  --data '
{
  "amount": "Provide amount",
  "source": {
    "account_number": "Provide source account number"
  },
  "beneficiary": {
    "bank_code": "Provide bank code",
    "bank_name": "Provide bank name",
    "account_number": "Provide account number",
    "account_name": "Provide account name"
  },
  "reference": "Provide reference",
  "meta_data": {},
  "remark": "Provide remark"
}
'
{
  "status": "success",
  "message": "payout was initiated successfully",
  "data": {
    "amount": 150,
    "total": 175,
    "fee": 25,
    "reference": "204041344312337",
    "beneficiary": {
      "bank_code": "057",
      "bank_name": "Dummy Bank",
      "account_number": "32324546565",
      "account_name": "Test User"
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.getcarbon.co/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This endpoint allows you to initiate a payout to a beneficiary account by providing the necessary details such as amount, source account, and beneficiary information.
Before creating a payout, you must validate the beneficiary bank account using the Resolve Account endpoint to ensure the account details are correct.
The minimum payout amount is ₦200.

​
Request

Method: POST
URL: /v1/payouts

​
Parameters

NameInTypeRequiredDescription
x-carbon-keyHeaderstringYesAPI key for authentication.

​
Request Body

FieldTypeRequiredDescription
amountnumberYesAmount to be paid out in kobo (minimum: 20000 = ₦200)
source.account_numberstringYesSource account number for the payout
beneficiary.bank_codestringYesBank code of the beneficiary’s bank
beneficiary.bank_namestringYesName of the beneficiary’s bank
beneficiary.account_numberstringYesBeneficiary’s account number (must be validated using /api-reference/banks/resolve-account)
beneficiary.account_namestringYesBeneficiary’s account name (obtained from resolve account response)
referencestringYesUnique reference for this payout request (max 30 characters)
meta_dataobjectNoAdditional metadata for the transaction
remarkstringYesDescription or note for the payout
The reference field must be unique for each new payout request. Using a duplicate reference will result in an error.
Example Reference Formats:
  • PAYOUT_USER123_20260119
  • PAY_INV_456789
  • SALARY_EMP001_JAN26
{
  "amount": 15000,
  "source": {
    "account_number": "1234567890"
  },
  "beneficiary": {
    "bank_code": "565",
    "bank_name": "CARBON",
    "account_number": "9876543210",
    "account_name": "John Doe"
  },
  "reference": "PAYOUT_USER123_20260119",
  "meta_data": {},
  "remark": "Payment for services"
}

​
Response

Status Code: 200 OK
Content-Type: application/json

​
Example Response

{
  "status": "success",
  "message": "Payout was initiated successfully",
  "data": {
    "amount": 15000,
    "total": 15000,
    "fee": 0,
    "reference": "PAYOUT_USER123_20260119",
    "beneficiary": {
      "bank_code": "565",
      "bank_name": "CARBON",
      "account_number": "9876543210",
      "account_name": "John Doe"
    }
  }
}

Authorizations

​
apikey
string
header
required

Provide your API key in the 'apikey' header.

Headers

​
x-carbon-key
string
required

Body

application/json

Provide the required values for the request body.

​
amount
number
required

Provide amount

​
source
object
required
​
beneficiary
object
required
​
reference
string
required

Provide reference

​
meta_data
object
required
​
remark
string
required

Provide remark

Response

200 - application/json

OK

The response is of type object.