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.

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": "[e-mail]"
}

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": "[e-mail]"
  }'

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

{
  "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"
}

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.

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

{
  "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.

Même après une réponse de réussite immédiate, utilisez le statut ou les rapports pour le rapprochement.