> 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/getting-started/conventions.md).

# 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 :

```http
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` :

```json
{
  "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](file:///2825698/integration-rules/error-handling.md).

{% hint style="info" %}
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.
{% endhint %}