Payer une facture / Recharger

curl --request POST \
  --url https://api-m.dexchange.sn/api/v1/billing/pay \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCode": "SENELEC_SN_BILL",
  "reference_client": "210278816",
  "amount": 104500,
  "reference_facture": "<string>",
  "externalTransactionId": "INV-001",
  "callBackURL": "<string>",
  "customData": "<string>"
}
'

{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID123456789",
    "externalTransactionId": "INV-001",
    "transactionType": "BILL",
    "amount": 104500,
    "transactionFee": 1045,
    "number": "210278816",
    "referenceFacture": "8000000680",
    "token": "1283930093209223",
    "Status": "SUCCESS",
    "previousBalance": 500000,
    "currentBalance": 394455,
    "message": "<string>"
  }
}

POST

api

billing

pay

Payer une facture / Recharger

curl --request POST \
  --url https://api-m.dexchange.sn/api/v1/billing/pay \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "serviceCode": "SENELEC_SN_BILL",
  "reference_client": "210278816",
  "amount": 104500,
  "reference_facture": "<string>",
  "externalTransactionId": "INV-001",
  "callBackURL": "<string>",
  "customData": "<string>"
}
'

{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID123456789",
    "externalTransactionId": "INV-001",
    "transactionType": "BILL",
    "amount": 104500,
    "transactionFee": 1045,
    "number": "210278816",
    "referenceFacture": "8000000680",
    "token": "1283930093209223",
    "Status": "SUCCESS",
    "previousBalance": 500000,
    "currentBalance": 394455,
    "message": "<string>"
  }
}

Pay a Bill / Top-up

Settles a bill (SenEau, Senelec) or performs a prepaid top-up (Woyofal). The amount is debited from your account balance (bill amount + your service FEE).

The debit only happens after the provider accepts the operation. On failure, no debit is applied (or an automatic refund is issued for asynchronous top-ups).

Endpoint

POST /api/v1/billing/pay

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer YOUR_API_KEY
Content-Type	string	Yes	application/json

Request Body

{
  "serviceCode": string,              // Biller code
  "reference_client": string,         // Meter number / customer reference
  "amount": number,                   // Required for Woyofal (customer-chosen)
  "reference_facture": string,        // Optional: target a specific bill
  "externalTransactionId": string,    // Optional: your unique reference
  "callBackURL": string,              // Optional: notification URL
  "customData": string                // Optional
}

Parameters

Parameter	Type	Required	Description
serviceCode	string	Yes	`SENEAU_SN_BILL`, `SENELEC_SN_BILL` or `WOYOFAL_SN_BILL`
reference_client	string	Yes	Meter number / police / customer reference
amount	number	Woyofal	Top-up amount. Required for Woyofal; ignored for SenEau/Senelec (bill-imposed)
reference_facture	string	No	Target a specific bill. Otherwise the first unpaid bill is settled
externalTransactionId	string	No	Your unique identifier (idempotency)
callBackURL	string	No	Webhook notification URL
customData	string	No	Free data echoed back in the callback

Amount: for SenEau and Senelec the amount is imposed by the bill (amount is ignored). For Woyofal (prepaid top-up) the customer chooses the amount via amount.

Response

Bill paid (SenEau / Senelec — synchronous)

{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID123456789",
    "externalTransactionId": "INV-001",
    "transactionType": "BILL",
    "amount": 104500,
    "transactionFee": 1045,
    "number": "210278816",
    "referenceFacture": "8000000680",
    "Status": "SUCCESS",
    "previousBalance": 500000,
    "currentBalance": 394455
  }
}

Top-up successful (Woyofal — immediate token)

{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID987654321",
    "transactionType": "BILL",
    "amount": 1000,
    "transactionFee": 10,
    "number": "07061270877",
    "token": "1283930093209223",
    "Status": "SUCCESS",
    "currentBalance": 498990
  }
}

token = recharge code to enter on the meter. Present only for prepaid top-ups (Woyofal).

Top-up processing (Woyofal — asynchronous)

If the provider does not confirm immediately, the transaction goes to PROCESSING. The token is delivered once resolved (available via webhook / transaction history).

{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID987654321",
    "transactionType": "BILL",
    "amount": 1000,
    "Status": "PROCESSING",
    "message": "Top-up in progress — token available shortly"
  }
}

For a PROCESSING top-up that ultimately fails, the debited amount (amount + fee) is automatically refunded to your balance and a FAILED callback is sent.

Error Response

{
  "message": "Failed to pay bill",
  "transaction": {
    "success": false,
    "Status": "FAILED",
    "message": "Insufficient balance"
  }
}

Error Codes

HTTP Code	Description
400	Invalid parameters, insufficient balance, bill already paid
401	Invalid API key
403	API under maintenance
409	externalTransactionId already used

Request Examples

Pay a Senelec bill

curl -X POST https://api-m.dexchange.sn/api/v1/billing/pay \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "SENELEC_SN_BILL",
    "reference_client": "210278816",
    "externalTransactionId": "INV-001",
    "callBackURL": "https://your-domain.com/callback"
  }'

Top up a Woyofal meter

curl -X POST https://api-m.dexchange.sn/api/v1/billing/pay \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceCode": "WOYOFAL_SN_BILL",
    "reference_client": "07061270877",
    "amount": 1000,
    "externalTransactionId": "RCH-001",
    "callBackURL": "https://your-domain.com/callback"
  }'

Notification Webhook

As with regular transactions, a webhook is sent to callBackURL on status change (SUCCESS / FAILED):

{
  "id": "TID123456789",
  "externalTransactionId": "INV-001",
  "transactionType": "BILL",
  "AMOUNT": 104500,
  "FEE": 1045,
  "PHONE_NUMBER": "210278816",
  "STATUS": "SUCCESS",
  "COMPLETED_AT": "2024-03-20T10:35:00Z",
  "PREVIOUS_BALANCE": 500000,
  "CURRENT_BALANCE": 394455
}

Authorizations

Authorization

string

header

required

Entrez votre clé API comme: Bearer <API_KEY>

Body

application/json

Détails du paiement

serviceCode

enum<string>

required

Code du biller

Available options:

SENEAU_SN_BILL,

SENELEC_SN_BILL,

WOYOFAL_SN_BILL

Example:

"SENELEC_SN_BILL"

reference_client

string

required

Numéro de compteur / police / référence client

Example:

"210278816"

amount

number

Montant à recharger. Requis pour Woyofal ; ignoré pour SenEau/Senelec (montant imposé).

Example:

104500

reference_facture

string

Optionnel : cible une facture précise. Sinon la 1re impayée est réglée.

externalTransactionId

string

Optionnel : votre référence unique (idempotence)

Example:

"INV-001"

callBackURL

string

Optionnel : URL de notification webhook

customData

string

Optionnel

Response

Paiement effectué (ou recharge en cours)

message

string

Example:

"Bill paid successfully"

transaction

object

Show child attributes

Bill Inquiry Initialize Merchant Payment

​Pay a Bill / Top-up

​Endpoint

​Headers

​Request Body

​Parameters

​Response

​Bill paid (SenEau / Senelec — synchronous)

​Top-up successful (Woyofal — immediate token)

​Top-up processing (Woyofal — asynchronous)

​Error Response

​Error Codes

​Request Examples

​Pay a Senelec bill

​Top up a Woyofal meter

​Notification Webhook

Authorizations

Body

Response

Pay a Bill / Top-up

Endpoint

Headers

Request Body

Parameters

Response

Bill paid (SenEau / Senelec — synchronous)

Top-up successful (Woyofal — immediate token)

Top-up processing (Woyofal — asynchronous)

Error Response

Error Codes

Request Examples

Pay a Senelec bill

Top up a Woyofal meter

Notification Webhook