Conventions de champs & Glossaire
En-têtes de requête
| En-tête | Requis | Définition |
|---|
| x-api-key | Oui | Clé API émise dans l'application (section « Business »). L'organisation est déterminée à partir de l'hôte de la requête |
| Content-Type | Oui (POST) | application/json pour les requêtes de création |
Montant & Devise
| Terme | Définition |
|---|
| amount | Chaîne d'un entier en unités mineures |
| amount_with_fee | Montant incluant la commission |
| currency | Code devise / token (USDT) |
| currency_dest | Devise de destination pour conversion (FX). Optionnel ; par défaut égal à currency |
Identifiants
| Terme | Définition |
|---|
| id | UUID interne de transaction |
| txid | Identifiant externe idempotent. Doit être un UUID valide s'il est fourni ; peut être omis |
Routage & Environnement
| Terme | Définition |
|---|
| route | Alias de traitement configuré |
| env | Environnement: prod (défaut) ou test |
Statuts
| Statut | Signification |
|---|
| created | Acceptée, en attente |
| new | État initial avant le début du traitement |
| authorizing | Autorisation en cours |
| pre_authorized_3ds | En attente d'authentification 3DS |
| action_required | Action supplémentaire requise (3DS / autorisation additionnelle) |
| charging | En cours |
| payment_suspended | Transaction entrante temporairement suspendue |
| payout_suspended | Transaction sortante temporairement suspendue |
| charged | Terminée avec succès (terminal) |
| reversed | Débit annulé (terminal) |
| refunded | Remboursée (terminal) |
| rejected | Rejetée (terminal) |
| failed | Échouée (terminal) |
Statuts terminaux : charged, reversed, refunded, rejected, failed. Parcours typique : created → charging → charged.
Temps
| Champ | Signification |
|---|
| started | Horodatage de début (ISO) |
| finished | Horodatage de fin (ISO) |
money_storage
| Champ | Signification |
|---|
| network | Réseau blockchain |
| type | Type d'instrument |
| wallet_id | Identifiant de wallet |
| cardnumber | Numéro de carte virtuelle |
| cvv | CVV virtuel |
| exp_month / exp_year | Expiration |
| cardholder | Titulaire |
Erreurs
| Champ | Signification |
|---|
| error_description | Message d'erreur (non stable) |
Idempotence
Utilisez un txid unique (UUID valide) par opération métier. Ne répétez une requête de création qu'avec le même txid — une répétition renvoie la transaction déjà créée au lieu d'en créer une nouvelle. Un txid non-UUID est rejeté avec 422 invalid_txid.
Polling
Délais: 1s → 2s → 4s → 8s jusqu'à charged / rejected.
Webhook
Informative uniquement — confirmer par GET.