conventions

URL de base

Les informations d’onboarding contiennent l’hôte de l’API. Les exemples utilisent la valeur fictive suivante :

https://api.example.com

Remplacez-la par l’hôte qui vous a été communiqué. Les chemins des endpoints ne changent pas lorsque le marchand passe de l’environnement de test à la production ; c’est l’environnement actif du marchand authentifié qui détermine la configuration utilisée.

Transport et encodage

• Utilisez uniquement HTTPS.

• Envoyez et acceptez du JSON encodé en UTF-8.

• Envoyez Content-Type: application/json pour les requêtes contenant un body.

• Envoyez Accept: application/json sur toutes les requêtes.

• Les montants sont des chaînes JSON, et non des nombres JSON.

• Les codes pays sont des identifiants configurés dans la plateforme, généralement des codes ISO à deux lettres en majuscules tels que NG.

• Les codes devise sont normalisés en majuscules et doivent être des codes ISO 4217 tels que NGN ou USD.

• Les filtres de date utilisent le format yyyy-MM-dd.

• Les timestamps de réponse sont en UTC, sauf indication contraire dans les informations d’onboarding.

En-tête d’autorisation

À l’exception de la connexion, tous les endpoints de ce guide nécessitent :

Authorization: Bearer <access-token>

N’envoyez jamais un secret client aux endpoints de transaction. Le secret sert uniquement à obtenir un token bearer.

Contextes d’authentification pris en charge

Les intégrations API directes doivent obtenir un token d’accès marchand via POST /api/v1/auth/login.

Enveloppe standard des opérations

La plupart des endpoints marchand renvoient un OperationResponse :

{
  "data": {},
  "message": "Success",
  "success": true,
  "responseCode": "00"
}

Champ	Type	Signification
data	object, array ou null	Résultat spécifique à l’endpoint.
message	string	Description destinée à la plateforme ou au provider.
success	boolean	true uniquement lorsque le responseCode de l’enveloppe est 00.
responseCode	string	Code de l’enveloppe de la plateforme. 00 signifie que l’opération API a réussi ; 400 signifie qu’elle a échoué.

La réponse de connexion et les réponses d’exception utilisent des structures différentes. Elles sont décrites dans Statuts HTTP, codes de réponse et gestion des erreurs.

Une enveloppe avec success: true signifie que l’opération API a réussi. Pour une opération financière, cela ne signifie pas nécessairement que le paiement sous-jacent est finalisé. Vérifiez le code ou le statut de transaction imbriqué, puis confirmez avec l’endpoint de statut.