Payouts (Disbursements)

Send funds from your Sebpay wallet to mobile money recipients via the API.

Immediate deduction

When a payout is initiated, the full amount (amount + fees) is immediately debited from your wallet. If fails, the balance is automatically refunded and the transaction moves to rejected.

Initiate a payout

POST

https://newapi.sebpay.bj/api/v1/payouts

Initiates a disbursement from your Sebpay wallet to a mobile money recipient. Processing is asynchronous — the final confirmation arrives via webhook.

Headers

X-Public-KeyRequired

string

Your public key (pk_...)

X-Secret-KeyRequired

string

Your secret key (sk_...)

Request Body

recipient_nameRequired

string

Full name of the recipient (max 180 characters).

phoneRequired

string

Phone number in international format without the (+).

operatorRequired

string

Operator code (mtn) or slug (mtn-bj), as returned by GET /operators.

countryRequired

string

ISO country code of the recipient (e.g. BJ, CI, SN).

amountRequired

numeric

Amount the recipient will receive.

currencyRequired

string

Currency code of the amount (e.g. XOF, EUR). 3 characters.

external_referenceRequired

string

Your unique identifier. A value that was already used is rejected (422): no duplicate is created; retrieve the original transaction with GET /payouts/{external_reference}.

callback_urlOptional

string

URL that will receive the final status notification (approved / rejected).

descriptionOptional

string

Internal reference or note (max 500 characters).

Response Body

transaction_idRequired

string

Unique SebPay transaction identifier.

statusRequired

string

Initial status: always 'pending'.

external_referenceRequired

string

Your external reference.

amountRequired

number

Amount sent to the recipient.

fee_amountRequired

number

SebPay fees deducted from your wallet.

total_deductedRequired

number

Total debited from your balance (amount + fee_amount).

currencyRequired

string

Your merchant account currency.

curl -X POST https://newapi.sebpay.bj/api/v1/payouts \
  -H "X-Public-Key: pk_live_your_key" \
  -H "X-Secret-Key: sk_live_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Jean Dupont",
    "phone": "22997000000",
    "operator": "mtn",
    "country": "BJ",
    "amount": 5000,
    "currency": "XOF",
    "external_reference": "PAYOUT-8822",
    "callback_url": "https://yoursite.com/webhook/sebpay"
  }'

Check payout status

GET

https://newapi.sebpay.bj/api/v1/payouts/{id_or_reference}

Retrieves the current status of a payout by its SebPay identifier or your external_reference.

Path Parameters

id_or_referenceRequired

string

The SebPay identifier or your external_reference.

Headers

X-Public-KeyRequired

string

Your public key (pk_...)

X-Secret-KeyRequired

string

Your secret key (sk_...)

Response Body

transaction_idRequired

string

Unique SebPay transaction identifier.

external_referenceRequired

string

Your external reference.

statusRequired

string

Current status: pending, approved, or rejected.

amountRequired

number

Transaction amount.

fee_amountRequired

number

Applied fees.

currencyRequired

string

Currency.

created_atRequired

string

Creation date ISO 8601.

updated_atRequired

string

Last update date ISO 8601.

curl -X GET https://newapi.sebpay.bj/api/v1/payouts/PAYOUT-8822 \
  -H "X-Public-Key: pk_live_your_key" \
  -H "X-Secret-Key: sk_live_your_secret"

Asynchronous processing

The final status (approved or rejected) is delivered via webhook to your callback_url. Polling GET /payouts/{id} is a supplement, not the primary mechanism. On rejected, your balance is automatically refunded.