> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.dexchange.sn/llms.txt
> Use this file to discover all available pages before exploring further.

# Payer une facture / Recharger

> Payer une facture (SenEau, Senelec) ou recharger un compteur prépayé (Woyofal)

# Payer une facture / Recharger

Règle une facture (SenEau, Senelec) ou effectue une recharge prépayée (Woyofal). Le montant est **débité du solde de votre compte** (montant de la facture + vos frais de service `FEE`).

<Warning>
  Le débit n'a lieu **qu'après acceptation** par le provider. En cas d'échec, aucun débit n'est effectué (ou un remboursement automatique est appliqué pour les recharges asynchrones).
</Warning>

## Endpoint

```bash theme={null}
POST /api/v1/billing/pay
```

## Headers

| Nom           | Type   | Requis | Description           |
| ------------- | ------ | ------ | --------------------- |
| Authorization | string | Oui    | Bearer YOUR\_API\_KEY |
| Content-Type  | string | Oui    | application/json      |

## Corps de la Requête

```json theme={null}
{
  "serviceCode": string,              // Code du biller
  "reference_client": string,         // Numéro de compteur / référence client
  "amount": number,                   // Requis pour Woyofal (montant libre)
  "reference_facture": string,        // Optionnel : facture ciblée
  "externalTransactionId": string,    // Optionnel : votre référence unique
  "callBackURL": string,              // Optionnel : URL de notification
  "customData": string                // Optionnel
}
```

### Paramètres

| Paramètre             | Type   | Requis  | Description                                                                                               |
| --------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------- |
| serviceCode           | string | Oui     | `SENEAU_SN_BILL`, `SENELEC_SN_BILL` ou `WOYOFAL_SN_BILL`                                                  |
| reference\_client     | string | Oui     | Numéro de compteur / police / référence client                                                            |
| amount                | number | Woyofal | Montant à recharger. **Requis pour Woyofal** ; ignoré pour SenEau/Senelec (montant imposé par la facture) |
| reference\_facture    | string | Non     | Cible une facture précise. Sinon, la 1ʳᵉ facture impayée est réglée                                       |
| externalTransactionId | string | Non     | Votre identifiant unique (idempotence)                                                                    |
| callBackURL           | string | Non     | URL pour les notifications webhook                                                                        |
| customData            | string | Non     | Donnée libre renvoyée dans le callback                                                                    |

<Note>
  **Montant** : pour SenEau et Senelec, le montant est **imposé** par la facture (le champ `amount` est ignoré). Pour Woyofal (recharge prépayée), le client **choisit** le montant via `amount`.
</Note>

## Réponse

### Facture payée (SenEau / Senelec — synchrone)

```json theme={null}
{
  "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
  }
}
```

### Recharge réussie (Woyofal — token immédiat)

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

<Note>
  **`token`** = code de recharge à saisir sur le compteur. Présent uniquement pour les recharges prépayées (Woyofal).
</Note>

### Recharge en cours (Woyofal — asynchrone)

Si le provider ne confirme pas immédiatement, la transaction passe en `PROCESSING`. Le token est livré dès résolution (consultable via le webhook / l'historique de transaction).

```json theme={null}
{
  "message": "Bill paid successfully",
  "transaction": {
    "success": true,
    "transactionId": "TID987654321",
    "transactionType": "BILL",
    "amount": 1000,
    "Status": "PROCESSING",
    "message": "Recharge en cours — token disponible sous peu"
  }
}
```

<Warning>
  Pour une recharge `PROCESSING` qui échoue finalement, le montant débité (montant + frais) est **automatiquement remboursé** sur votre solde et un callback `FAILED` est envoyé.
</Warning>

### Réponse d'Erreur

```json theme={null}
{
  "message": "Failed to pay bill",
  "transaction": {
    "success": false,
    "Status": "FAILED",
    "message": "Insufficient balance"
  }
}
```

## Codes d'Erreur

| Code HTTP | Description                                                 |
| --------- | ----------------------------------------------------------- |
| 400       | Paramètres invalides, solde insuffisant, facture déjà payée |
| 401       | Clé API invalide                                            |
| 403       | API en maintenance                                          |
| 409       | externalTransactionId déjà utilisé                          |

## Exemples de Requête

### Payer une facture Senelec

```bash theme={null}
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"
  }'
```

### Recharger un compteur Woyofal

```bash theme={null}
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"
  }'
```

## Webhook de Notification

Comme pour les transactions classiques, un webhook est envoyé à `callBackURL` lors du changement de statut (`SUCCESS` / `FAILED`) :

```json theme={null}
{
  "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
}
```


## OpenAPI

````yaml POST /api/v1/billing/pay
openapi: 3.0.1
info:
  title: DEXCHANGE-API
  description: >-
    Unifiez tous vos paiements mobiles à travers une seule API puissante.
    DEXCHANGE-API est une passerelle de paiement qui regroupe plusieurs wallets
    (Orange Money, Wave, Free Money, Wizall) sur une seule API, simplifiant
    l'intégration des paiements mobiles en Afrique de l'Ouest.
  version: 1.0.0
  contact:
    name: DEXCHANGE Support
    email: team@dexchange.sn
    url: https://docs-api.dexchange.sn
  license:
    name: MIT
servers:
  - url: https://api-m.dexchange.sn
    description: Production Server
security:
  - bearerAuth: []
tags:
  - name: Transactions
    description: Operations for managing payment transactions
  - name: Merchant
    description: Merchant-specific payment operations
  - name: Services
    description: Service and balance information
  - name: Billing
    description: Bill payment and prepaid top-up operations
paths:
  /api/v1/billing/pay:
    post:
      tags:
        - Billing
      summary: Payer une facture / Recharger
      description: >-
        Règle une facture (SenEau, Senelec) ou effectue une recharge prépayée
        (Woyofal). Le montant est débité du solde (montant + FEE).
      operationId: billingPay
      requestBody:
        description: Détails du paiement
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingPayRequest'
        required: true
      responses:
        '201':
          description: Paiement effectué (ou recharge en cours)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPayResponse'
        '400':
          description: Solde insuffisant, facture déjà payée, ou paramètres invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    BillingPayRequest:
      type: object
      required:
        - serviceCode
        - reference_client
      properties:
        serviceCode:
          type: string
          enum:
            - SENEAU_SN_BILL
            - SENELEC_SN_BILL
            - WOYOFAL_SN_BILL
          description: Code du biller
          example: SENELEC_SN_BILL
        reference_client:
          type: string
          description: Numéro de compteur / police / référence client
          example: '210278816'
        amount:
          type: number
          description: >-
            Montant à recharger. Requis pour Woyofal ; ignoré pour
            SenEau/Senelec (montant imposé).
          example: 104500
        reference_facture:
          type: string
          description: >-
            Optionnel : cible une facture précise. Sinon la 1re impayée est
            réglée.
        externalTransactionId:
          type: string
          description: 'Optionnel : votre référence unique (idempotence)'
          example: INV-001
        callBackURL:
          type: string
          description: 'Optionnel : URL de notification webhook'
        customData:
          type: string
          description: Optionnel
    BillingPayResponse:
      type: object
      properties:
        message:
          type: string
          example: Bill paid successfully
        transaction:
          $ref: '#/components/schemas/BillingTransaction'
    Error:
      type: object
      properties:
        message:
          type: array
          items:
            type: string
        success:
          type: boolean
      required:
        - message
        - success
    BillingTransaction:
      type: object
      properties:
        success:
          type: boolean
          example: true
        transactionId:
          type: string
          example: TID123456789
        externalTransactionId:
          type: string
          example: INV-001
        transactionType:
          type: string
          example: BILL
        amount:
          type: number
          example: 104500
        transactionFee:
          type: number
          example: 1045
        number:
          type: string
          example: '210278816'
        referenceFacture:
          type: string
          example: '8000000680'
        token:
          type: string
          nullable: true
          description: Code de recharge (Woyofal) à saisir sur le compteur
          example: '1283930093209223'
        Status:
          type: string
          enum:
            - SUCCESS
            - PROCESSING
            - FAILED
          example: SUCCESS
        previousBalance:
          type: number
          example: 500000
        currentBalance:
          type: number
          example: 394455
        message:
          type: string
          description: Présent pour les recharges en cours (PROCESSING) ou les échecs
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Entrez votre clé API comme: Bearer <API_KEY>'

````