Skip to main content
POST
/
v1
/
payouts
cURL
curl --request POST \
  --url https://api.example.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "amount": 10000,
  "currency": "XOF",
  "destination_number": "+22507123456",
  "reference": "PAYOUT_001",
  "description": "<string>",
  "webhook_url": "<string>"
}
'
{
  "id": "payout_ci_123456789",
  "status": "processing",
  "amount": 10000,
  "currency": "XOF",
  "destination_number": "+22507123456",
  "reference": "PAYOUT_001",
  "description": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "failure_reason": "<string>",
  "transaction_fee": 50,
  "ussd_reference": "USSD123456",
  "idempotency_key": "<string>"
}

​
Create Payout API

This API allows you to create a new payout to transfer funds to a specified destination.

​
Endpoint

POST /v1/payouts

​
Request Body

NameTypeDescription
amountintegerThe amount to be paid out in the smallest currency unit (e.g., cents for USD).
currencystringThe currency code (e.g., “usd”, “eur”) for the payout.
destinationstringThe destination identifier where the payout will be sent (e.g., bank account ID).
descriptionstring(Optional) A description for the payout.

​
Responses

​
201 Created

{
  "id": "string",
  "amount": 0,
  "currency": "string",
  "status": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

​
400 Bad Request

{
  "error": "Invalid request parameters"
}

​
500 Internal Server Error

{
  "error": "An unexpected error occurred"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
idempotency-key
string
required

UUID

Maximum string length: 1000

Body

application/json
​
amount
integer
required
Required range: x >= 100
Example:

10000

​
currency
enum<string>
required
Available options:
XOF
Example:

"XOF"

​
destination_number
string
required
Example:

"+22507123456"

​
reference
string
Maximum string length: 100
Example:

"PAYOUT_001"

​
description
string
Maximum string length: 200
​
webhook_url
string<uri>

Response

Payout already exist

​
id
string
Example:

"payout_ci_123456789"

​
status
enum<string>
Available options:
pending,
processing,
completed,
failed,
cancelled
Example:

"processing"

​
amount
integer
Example:

10000

​
currency
string
Example:

"XOF"

​
destination_number
string
Example:

"+22507123456"

​
reference
string
Example:

"PAYOUT_001"

​
description
string
​
created_at
string<date-time>
​
completed_at
string<date-time> | null
​
failure_reason
string | null
​
transaction_fee
integer
Example:

50

​
ussd_reference
string
Example:

"USSD123456"

​
idempotency_key
string