Paiements et statuts
Une facture décrit une commande. Un paiement est une tentative spécifique de la régler. Une tentative de paiement et la disponibilité de son lien sont des états distincts.
Sur cette page
L'enregistrement du paiement#
La facture stocke les conditions de la commande ; le paiement identifie son opération de passerelle. Le premier lancement réserve une liaison durable et une clé d'idempotence serveur. Après le début de l'envoi, une autre méthode ne peut pas créer un second débit sur la même facture.
GET /api/payment-links et GET /api/v1/payments renvoient link.payment au propriétaire. Le statut actif/en pause/annulé/expiré du lien est distinct de l'état du paiement. Un client ne peut lire son opération que via le jeton de paiement aléatoire.
| Données | Objectif |
|---|---|
| Identifiant et commande | Associer la tentative à un achat |
| Montant de base et devise | La base de calcul |
| Méthode de paiement | Frais et taxes applicables |
| Assujetti à la TVA | Qui prend en charge la taxe |
| Frais, TVA et totaux | Calcul enregistré |
| Statut et heure | État actuel de la transaction |
| Référence d'événement de la passerelle | Source de confirmation serveur |
États d'opération en direct#
La démo utilise des enregistrements de test distincts. Modifier un état de démo ne confirme pas un paiement réel et ne modifie pas les enregistrements financiers.
| Statut | Signification |
|---|---|
| en attente | Opération créée ; en attente d'une action ou d'un résultat |
| requires_action | Un code bancaire ou une confirmation du client est requis |
| processing | Le fournisseur confirme encore le résultat |
| réussi | Le serveur a vérifié le paiement exact |
| échoué | Tentative terminée sans paiement confirmé |
| expired | Instructions expirées ; le rapprochement reste disponible |
| review_required | Un examen supplémentaire est nécessaire ; ne payez pas à nouveau |
| partially_paid | Seule une partie du montant a été reçue ; ne créez pas un autre paiement |
| partially_refunded | Une partie du paiement a été remboursée |
| refunded | Remboursement confirmé |
| disputed | L'opération est contestée |
La source de vérité#
Un webhook signé déclenche une lecture authentifiée de l'opération exacte de la passerelle. Les identifiants, la commande, la devise, la méthode, les montants de base et finaux, le mode réel et la version monotone sont validés. Un simple nom d'événement entrant n'est pas une preuve d'argent.
L'état, le reçu et l'événement marchand sont validés de manière atomique. Les réponses plus anciennes ne peuvent pas écraser une version plus récente ; les doublons ne sont pas exécutés deux fois, et « en attente » ne peut pas remplacer un paiement confirmé. Ces enregistrements ne créent pas automatiquement un solde retirable ni un paiement.
Lorsque le résultat est inconnu#
- 1
Conservez la facture d'origine et l'identifiant de l'opération.
- 2
Lisez GET /api/checkout/{token}/status ; cela ne crée pas de débit.
- 3
Utilisez POST /api/checkout/{token}/reconcile lorsqu'un rapprochement explicite est nécessaire.
- 4
Ne modifiez pas la méthode, le montant ou la clé d'idempotence après un résultat incertain.
Plusieurs boutiques et un prix de base USD unique#
Choisissez Toutes les boutiques pour les analyses et opérations agrégées, ou sélectionnez une boutique pour ses propres enregistrements. Chaque boutique possède un storeId, un nom, une TVA par défaut, des factures, des clés API, des points de terminaison webhook, un historique d'événements et une application de site Web distincts. Les notifications et les tickets de support appartiennent au compte. Un compte peut créer jusqu'à 100 boutiques. Les enregistrements existants restent dans sa première boutique.
Les factures du nouvel espace de travail utilisent pricingMode="universal" et un prix de base en USD. Any inclut carte, alipay, sbp et crypto ; un commerçant peut sélectionner un sous-ensemble. Les cartes et Alipay facturent en USD. SBP facture en RUB en utilisant le taux de référence USD/RUB de la Banque de Russie. La crypto facture en USDT selon la règle de facturation explicite 1 USD = 1 USDT. Il s'agit d'une règle de conversion de facturation, pas d'une cotation USDT de marché. La passerelle fournit le taux de la pièce sélectionnée, le montant exact du transfert et les instructions avant le transfert.
Le taux de référence et les deux montants sont gelés à la création. Les factures impliquant une conversion RUB expirent dans les 24 heures. Si le taux de référence ne peut pas être obtenu, la création échoue avec FX_UNAVAILABLE ; aucun taux de secours inventé ou obsolète n'est utilisé. Le montant en monnaie mineure du propriétaire et les cotations utilisent la monnaie comptable USD. quotes[method].settlement contient la cotation de frais native. Le paiement public expose la monnaie de frais sélectionnée dans currency, le prix d'origine dans baseAmountMinor/baseCurrency, et le taux de référence dans fx. Une fois qu'un paiement a été envoyé, sa méthode ne peut pas être modifiée ; une facture a une seule opération de passerelle.
Créez une clé API dans la boutique prévue et envoyez Authorization: Bearer <key> depuis votre serveur. Sa liaison de boutique est immuable ; X-Kevmi-Store ne peut pas lui accorder l'accès à une autre boutique. Les sessions de navigateur sélectionnent X-Kevmi-Store: <storeId> ; si omis, la première boutique est sélectionnée. La valeur all n'est acceptée que par GET /api/account/dashboard et GET /api/payment-links. Les mutations nécessitent une boutique sélectionnée, Origin et X-CSRF-Token. Les identifiants de compte et les identifiants de boutique sont des identifiants différents.
Pour la compatibilité, les demandes API sans pricingMode="universal" conservent la tarification native et les restrictions de monnaie d'origine. Les factures existantes ne sont jamais recalculées. Les reçus confirmés dans les analyses reflètent les paiements vérifiés moins les dépenses de facture enregistrées ; ils ne constituent pas un solde retirable. Les monnaies de facture héritées restent séparées et les paiements sont organisés avec le support. Exécutez une commande uniquement après avoir vérifié payment.fulfillmentReady=true et payment.status="succeeded" via l'API serveur, l'historique d'événements ou un webhook signé.