API de liens de paiement et clés API

Une requête serveur renvoie un lien prêt à l’emploi#

POST /api/v1/payments et /api/v1/payment-links créent le même type de facture. Le nom de la route payments n’implique pas de débit : le résultat est une facture persistée avec ses conditions et une checkoutUrl pour le client.

Envoyez Authorization: Bearer <key>, Content-Type: application/json et Idempotency-Key. Les clés d’idempotence contiennent 16 à 100 lettres, chiffres, tirets ou underscores. Persistez une clé pour chaque création logique de commande.

curl 'https://kevmi.maxeevmax1.chatgpt.site/api/v1/payments' \
  -H "Authorization: Bearer $KEVMI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-create-v1' \
  --data '{"title":"Design project · order 1042","description":"One-time payment for the agreed design work","amountMinor":500,"currency":"USD","methods":["card","alipay"],"vatCustomerPercent":100,"feeCustomerPercent":0,"orderId":"order-1042","metadata":{"campaign":"autumn"}}'

Périmètres et expiration des clés API#

Créez une clé à /account#keys dans votre compte marchand vérifié. Sa valeur complète n’apparaît qu’une fois ; seul un hash est stocké. Les clés durent 90 jours par défaut, avec une durée de vie autorisée de 1 à 365 jours et jusqu’à dix clés actives par compte.

Accordez uniquement les périmètres requis. La révocation ou l’expiration bloque l’accès. Une clé ne remplace pas la session navigateur pour les paramètres du compte, l’administration des endpoints, les applications ou la modération. Ne la placez pas dans les widgets, les URL, les dépôts publics ou les messages d’assistance.

Le site web utilise /api/payment-links avec son cookie de session, l’Origin exact et X-CSRF-Token. Ces routes opèrent sur les mêmes factures possédées.

Any et méthodes API concrètes#

Any est un mode de sélection d’interface. Les nouvelles factures acceptent les méthodes : ["card", "alipay"] ou un sous-ensemble non vide pour USD ; ["sbp"] pour RUB ; ["crypto"] pour USDT. La valeur any n’est pas une méthode de paiement API.

Pour une nouvelle facture dans l'interface, USD propose les cartes et Alipay ; RUB propose SBP ; USDT propose la crypto. L'API peut également enregistrer USD + crypto pour compatibilité, mais son paiement crypto en direct est bloqué avec crypto_requires_usdt. USD et USDT sont distincts, sans conversion automatique ni taux de 1:1 supposé. Un paiement crypto nécessite une facture USDT séparée.

Pour un nouveau paiement en direct par carte ou Alipay, la passerelle actuelle ne prend en charge que feeCustomerPercent=0 et vatCustomerPercent=100 : le marchand couvre la totalité des frais de traitement et la TVA est ajoutée intégralement pour le client. D'autres parts peuvent être enregistrées et calculées sur une facture, mais l'exécution est bloquée avec unsupported_allocation. Le serveur ne modifie jamais silencieusement les conditions enregistrées. Les paiements crypto SBP et USDT prennent en charge toutes les parts de frais de traitement et n'ont pas de TVA.

Champs et conditions persistées#

La facture enregistre le nom du marchand, le prix, la devise, les méthodes, les deux parts de coûts et les devis calculés. Les métadonnées sont renvoyées au propriétaire et dans les événements serveur, mais pas via le checkout public. N’y stockez pas de secrets de paiement.

Si les parts sont omises, le marchand couvre les frais ; la TVA hérite de vatPayer ou du paramètre du compte. Une répartition partielle peut renvoyer vatPayer=shared. Le titre, orderId et la description sont publics.

Nouvelle tentative après une erreur réseau#

La création initiale renvoie 201 avec replayed=false. La même clé et le même corps canonique renvoient 200, la checkoutUrl d’origine et replayed=true. Une requête différente sous cette clé renvoie 409 IDEMPOTENCY_CONFLICT.

Ne générez pas une autre clé après un délai d’attente. Répétez la requête d’origine avec des champs identiques. Les valeurs omises n’héritent pas à nouveau des paramètres modifiés. orderId aide à corréler une commande mais ne remplace pas Idempotency-Key et n’est pas requis comme unique en stockage.

Lecture et pagination#

GET /api/v1/payments renvoie links et nextCursor ; GET /api/v1/payments/{id} renvoie un lien possédé. invoices:read est requis. La taille de page par défaut est 30 ; limit accepte 1 à 100.

Les réponses GET liste et détail incluent link.payment : un résumé de l’opération associée, ou null quand aucune opération n’existe. Les réponses POST/PATCH peuvent l’omettre ; relisez la facture lorsque vous avez besoin du résumé. Le statut du lien décrit séparément si un nouveau paiement peut commencer. Les champs de carte et les clés privées ne sont jamais inclus.

Passez nextCursor inchangé via URLSearchParams. null marque la fin ; les ID inconnus et ceux d’autres marchands renvoient tous 404.

GET /api/v1/payments?limit=30
Authorization: Bearer <server-side key>

Pause, reprise et annulation#

PATCH /api/v1/payments/{id} avec invoices:write accepte uniquement {"status":"active"}, {"status":"paused"} ou {"status":"cancelled"}. L’annulation est définitive. expired est dérivé du moment d’expiration ; une facture expirée ne peut pas être prolongée.

Prix, parts de coûts, description, orderId, métadonnées et expiration sont immuables. Créez une autre facture pour des conditions différentes. Modifier la disponibilité émet invoice.updated, pas un événement de paiement réussi.

La réponse client#

GET /api/checkout/{token}?method=card renvoie la facture publique, le devis, la disponibilité des méthodes et l’opération existante. Les métadonnées du propriétaire, les secrets et les soldes ne sont pas exposés.

POST /api/checkout/{token}/pay exige l’Origin du site et une méthode concrète. Les données de carte ne sont acceptées que scellées : {intent,jwe}, après que le navigateur obtient /card-intent. Les codes bancaires sont chiffrés et envoyés via /code. La crypto utilise une facture USDT enregistrée et une paire coin/réseau disponible.

Un nouveau paiement et une intention de carte nécessitent l'approbation de la dernière demande de revue du site du marchand. L'approbation seule ne connecte pas la passerelle de paiement. Si la revue change après l'envoi, l'opération existante reste disponible pour la lecture des statuts, le rapprochement et un code bancaire demandé.

Une connexion live manquante renvoie GATEWAY_NOT_CONNECTED ; une répartition incompatible n’est jamais remplacée par un autre calcul. Status et reconcile lisent l’opération d’origine sans débit en double.

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é.