Collections

The Collections API lets you initiate Mobile Money payment requests directly from your platform.

Initiate a collection

POST

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

Initiates a payment request to a customer's phone. The customer will receive a USSD message or notification to validate the transaction.

Headers

X-Public-KeyRequired

string

Your public key (pk_...)

X-Secret-KeyRequired

string

Your secret key (sk_...)

Request Body

amountRequired

numeric

The transaction amount.

currencyRequired

string

Currency code (e.g. XOF, EUR, USD).

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 (BJ, CI, SN...)

external_referenceRequired

string

Your unique identifier for this transaction. A value that was already used is rejected (422).

callback_urlOptional

string

URL that will receive the final status notification.

otp_codeOptional

string

OTP code required for certain operators (e.g. Orange CI, BF, SN). Check GET /operators: if otp_required is true, ask the user for this code before submitting.

Response Body

transaction_idRequired

string

Unique SebPay transaction identifier.

statusRequired

string

Initial status (usually 'pending').

external_referenceRequired

string

Your external reference as provided in the request.

amountRequired

number

Transaction amount.

currencyRequired

string

Currency used.

provider_linkOptional

string

Redirect link (e.g. Wave). If present, you MUST redirect the user to this URL in a new tab for them to validate the payment.

messageRequired

string

Descriptive message about the status of the initiated transaction.

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

Response envelope format

All API responses are wrapped in a common object:

{
  "success": true,
  "data": { ... },
  "message": "..."
}

Get a transaction

GET

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

Retrieves the details and current status of a transaction by its SebPay identifier or your external reference.

Path Parameters

id_or_referenceRequired

string

The SebPay transaction 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 as provided in the request.

statusRequired

string

Current status: pending, approved, or rejected.

amountRequired

number

Transaction amount.

currencyRequired

string

Currency used.

created_atRequired

string

Creation date ISO 8601.

updated_atRequired

string

Last update date ISO 8601.

curl -X GET https://newapi.sebpay.bj/api/v1/collections/ORDER-123 \
  -H "X-Public-Key: pk_live_your_key" \
  -H "X-Secret-Key: sk_live_your_secret"

Integration tip

Always use the callback_url parameter to receive real-time updates. Do not rely solely on manual polling to confirm payments.