> For the complete documentation index, see [llms.txt](https://qosic.gitbook.io/qospay/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://qosic.gitbook.io/qospay/merchant-api/payments/collections.md).

# collections

Utilisez une collecte pour demander un paiement à un client final. Le marchand authentifié doit disposer du service de collecte et transfert activé. Si une liste blanche d’adresses IP est activée pour ce service marchand, l’adresse IP source doit également être enregistrée.

```http
POST /api/v1/payment/collections/request HTTP/1.1
Host: api.example.com
Authorization: Bearer <access-token>
Accept: application/json
Content-Type: application/json

{
  "amount": "2500.00",
  "transRef": "COL-20260810-000001",
  "msisdn": "2348012345678",
  "operatorId": "SAYSWITCH",
  "countryCode": "NG",
  "currencyCode": "NGN",
  "firstName": "Ada",
  "lastName": "Okafor",
  "customerEmail": "ada@example.com"
}
```

```bash
curl --request POST "https://api.example.com/api/v1/payment/collections/request" \
  --header "Authorization: Bearer ${QOS_ACCESS_TOKEN}" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": "2500.00",
    "transRef": "COL-20260810-000001",
    "msisdn": "2348012345678",
    "operatorId": "NGPAY",
    "countryCode": "234",
    "currencyCode": "NGN",
    "firstName": "Ada",
    "lastName": "Okafor",
    "customerEmail": "ada@example.com"
  }'
```

### Champs de la requête

| Champ           | Obligatoire | Description                                                                                                     |
| --------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `amount`        | Oui         | Montant décimal positif exprimé sous forme de chaîne. N’incluez ni séparateur de milliers ni symbole de devise. |
| `transRef`      | Oui         | Référence de transaction unique générée par le marchand. Ne la réutilisez jamais.                               |
| `msisdn`        | Oui         | Numéro de téléphone mobile du client dans le format attendu par l’opérateur sélectionné.                        |
| `operatorId`    | Oui         | Opérateur retourné par la découverte.                                                                           |
| `countryCode`   | Oui         | Pays retourné par la découverte.                                                                                |
| `currencyCode`  | Oui         | Devise retournée pour ce pays, normalisée en majuscules.                                                        |
| `firstName`     | Non         | Prénom du client. À inclure lorsqu’il est disponible.                                                           |
| `lastName`      | Non         | Nom du client. À inclure lorsqu’il est disponible.                                                              |
| `customerEmail` | Non         | Adresse e-mail du client utilisée par les parcours provider compatibles.                                        |

### Réponse acceptée/en attente — HTTP 200

```json
{
  "data": {
    "code": "201",
    "userMessage": "Payment request submitted successfully",
    "continuationUrl": null,
    "responseData": {
      "bank_name": "Test Bank",
      "account_number": "0123456780",
      "currency": "NGN",
      "amountToPay": "2550.0000",
      "account_name": "Sample test account name"
    }
  },
  "message": "Success",
  "success": true,
  "responseCode": "00"
}
```

{% hint style="info" %}
`data.code: "201"` représente un résultat accepté/en attente au niveau du provider ; il ne s’agit pas d’un HTTP 201. Conservez `transRef`, présentez `continuationUrl` lorsqu’elle est fournie, suivez les éventuelles instructions de paiement du provider présentes dans `responseData`, puis interrogez le statut. Les champs exacts de `responseData` dépendent du provider ; l’exemple ci-dessus montre la réponse actuelle du compte bancaire en mode test.
{% endhint %}

### Réponse immédiatement réussie — HTTP 200

```json
{
  "data": {
    "code": "00",
    "userMessage": "SUCCESSFUL",
    "continuationUrl": null,
    "responseData": {
      "reference": "PRV-COL-884421",
      "status": "SUCCESSFUL",
      "currency": "NGN",
      "amount": "2500.00"
    }
  },
  "message": "Success",
  "success": true,
  "responseCode": "00"
}
```

La structure de `responseData` est propre au provider et peut varier selon l’opérateur. Votre désérialiseur doit accepter des champs supplémentaires ainsi que des valeurs `null`. L’API considère les codes de collecte `00` ou `0`, ou un message de succès `SUCCESS`/`SUCCESSFUL`, comme une réussite immédiate.

{% hint style="info" %}
Même après une réponse de réussite immédiate, utilisez le statut ou les rapports pour le rapprochement.
{% endhint %}