Send a customer’s available balance to a bank account

POST

withdrawals

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "withdrawalId": "cwd_01hxyz",
    "kind": "customer",
    "status": "processing",
    "amount": 400,
    "chargedAmount": 422.5,
    "netAmount": 400,
    "currency": "NGN",
    "reference": "payout-12345",
    "fees": {
      "providerFee": 10,
      "platformFee": 2.5,
      "merchantFee": 0,
      "totalFees": 12.5
    },
    "customerId": "cus_01hxyz",
    "bankAccountId": "ba_01hxyz",
    "bankCode": "058",
    "accountName": "JANE DOE",
    "last4": "6789",
    "providerReference": "<string>",
    "failureReason": "<string>"
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

Authorizations

Authorization

string

header

required

Secret API key. Use sk_test_... for sandbox data or sk_live_... for live data (after verification and live mode). Do not use pk_ keys.

Headers

Idempotency-Key

string

required

Body

application/json

customerId, 10-digit accountNumber, bankCode, amount in naira, unique reference. currency optional (default NGN).

customerId

string

required

Customer whose available balance is debited.

Example:

"cus_01hxyz"

accountNumber

string

required

10-digit destination account number. Not stored as a customer bank book.

Example:

"0123456789"

bankCode

string

required

CBN bank code from GET /identity/banks.

Example:

"058"

amount

number

required

Amount to send in naira.

Example:

400

reference

string

required

Your unique payout reference. Duplicate values are rejected.

Example:

"payout-12345"

merchantFee

number

Optional merchant surcharge in naira. Debited from the customer with provider and Demat fees, then credited to your settlement balance when the payout completes.

Example:

0

currency

string

ISO currency code. Defaults to NGN.

Example:

"NGN"

Response

Resource created

success

boolean

Example:

true

data

object

Show child attributes

meta

object

Show child attributes

Error

A valid request URL is required to generate request examples

{
  "success": true,
  "data": {
    "withdrawalId": "cwd_01hxyz",
    "kind": "customer",
    "status": "processing",
    "amount": 400,
    "chargedAmount": 422.5,
    "netAmount": 400,
    "currency": "NGN",
    "reference": "payout-12345",
    "fees": {
      "providerFee": 10,
      "platformFee": 2.5,
      "merchantFee": 0,
      "totalFees": 12.5
    },
    "customerId": "cus_01hxyz",
    "bankAccountId": "ba_01hxyz",
    "bankCode": "058",
    "accountName": "JANE DOE",
    "last4": "6789",
    "providerReference": "<string>",
    "failureReason": "<string>"
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request",
    "details": {}
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

customers

escrows

checkout

transactions

wallets

payouts

fees

identity

Send a customer’s available balance to a bank account

Authorizations

Headers

Body

Response