Zahlungslink-API und API-Schlüssel

Eine Serveranfrage gibt einen fertigen Link zurück#

POST /api/v1/payments und /api/v1/payment-links erstellen denselben Rechnungstyp. Der Routenname payments impliziert keine Belastung: Das Ergebnis sind gespeicherte Rechnungsbedingungen und eine checkoutUrl für den Kunden.

Senden Sie Authorization: Bearer <key>, Content-Type: application/json und Idempotency-Key. Idempotenz-Schlüssel enthalten 16–100 Buchstaben, Ziffern, Bindestriche oder Unterstriche. Speichern Sie einen Schlüssel für jede logische Bestellabwicklung.

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"}}'

API-Schlüssel-Bereiche und Ablauf#

Erstellen Sie einen Schlüssel unter /account#keys in Ihrem verifizierten Händlerkonto. Sein vollständiger Wert erscheint nur einmal; nur ein Hash wird gespeichert. Schlüssel gelten standardmäßig 90 Tage, mit einer zulässigen Lebensdauer von 1–365 Tagen und bis zu zehn aktiven Schlüsseln pro Konto.

Gewähren Sie nur die erforderlichen Bereiche. Widerruf oder Ablauf beendet den Zugriff. Ein Schlüssel ersetzt nicht die Browser-Sitzung für Kontoeinstellungen, Endpunktverwaltung, Anwendungen oder Moderation. Halten Sie ihn fern von Widgets, URLs, öffentlichen Repositories und Supportnachrichten.

Die Website verwendet /api/payment-links mit ihrem Sitzungs-Cookie, exaktem Origin und X-CSRF-Token. Diese Routen arbeiten mit denselben eigenen Rechnungen.

Beliebig und konkrete API-Methoden#

Beliebig ist ein Schnittstellen-Auswahlmodus. Neue Rechnungen akzeptieren Methoden: ["card", "alipay"] oder eine nichtleere Teilmenge für USD; ["sbp"] für RUB; ["crypto"] für USDT. Der Wert any ist keine API-Zahlungsmethode.

Für eine neue Rechnung in der Oberfläche bietet USD Karten und Alipay an; RUB bietet SBP an; USDT bietet Krypto an. Die API kann auch USD + Krypto für die Kompatibilität speichern, aber ihre Live-Kryptozahlung ist mit crypto_requires_usdt blockiert. USD und USDT sind unterschiedlich, ohne automatische Umrechnung oder angenommenen 1:1-Kurs. Eine Kryptozahlung erfordert eine separate USDT-Rechnung.

Für eine neue Live-Karten- oder Alipay-Zahlung unterstützt das aktuelle Gateway nur feeCustomerPercent=0 und vatCustomerPercent=100: der Händler übernimmt die gesamte Bearbeitungsgebühr und die MwSt wird dem Kunden vollständig hinzugefügt. Andere Anteile können auf einer Rechnung gespeichert und berechnet werden, aber die Ausführung ist mit unsupported_allocation blockiert. Der Server ändert gespeicherte Bedingungen niemals stillschweigend. SBP- und USDT-Kryptozahlungen unterstützen jeden Bearbeitungsgebührenanteil und haben keine MwSt.

Felder und gespeicherte Bedingungen#

Die Rechnung speichert den Händlernamen, Preis, Währung, Methoden, beide Kostenanteile und berechnete Angebote. Metadaten werden an den Eigentümer und in Serverereignissen zurückgegeben, jedoch nicht über öffentlichen Checkout. Speichern Sie keine Zahlungsgeheimnisse darin.

Wenn Anteile weggelassen werden, trägt der Händler die Gebühr; die Mehrwertsteuer erbt vatPayer oder die Kontoeinstellung. Eine Teilzuordnung kann vatPayer=shared zurückgeben. Der Titel, orderId und Beschreibung sind öffentlich.

Erneut versuchen nach einem Netzwerkfehler#

Die anfängliche Erstellung gibt 201 mit replayed=false zurück. Derselbe Schlüssel und derselbe kanonische Text geben 200 mit der ursprünglichen checkoutUrl und replayed=true zurück. Eine andere Anfrage unter diesem Schlüssel gibt 409 IDEMPOTENCY_CONFLICT zurück.

Generieren Sie nach einem Timeout keinen weiteren Schlüssel. Wiederholen Sie die ursprüngliche Anfrage mit identischen Feldern. Weggelassene Werte erben nicht erneut geänderte Einstellungen. orderId hilft bei der Zuordnung einer Bestellung, ersetzt aber nicht Idempotency-Key und muss in der Speicherung nicht eindeutig sein.

Lesen und Seitennummerierung#

GET /api/v1/payments gibt Links und nextCursor zurück; GET /api/v1/payments/{id} gibt einen eigenen Link zurück. invoices:read ist erforderlich. Die Standardseitengröße ist 30; limit akzeptiert 1–100.

GET-Listen- und Detailantworten enthalten link.payment: eine Zusammenfassung des zugehörigen Vorgangs, oder null, wenn kein Vorgang existiert. POST/PATCH-Antworten können dies weglassen; lesen Sie die Rechnung erneut, wenn Sie die Zusammenfassung benötigen. Der Linkstatus beschreibt separat, ob eine neue Zahlung beginnen darf. Kartendaten und private Schlüssel sind nie enthalten.

Übergeben Sie nextCursor unverändert über URLSearchParams. null markiert das Ende; unbekannte und andere Händler-IDs geben beide 404 zurück.

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

Pausieren, fortsetzen und stornieren#

PATCH /api/v1/payments/{id} mit invoices:write akzeptiert nur {"status":"active"}, {"status":"paused"} oder {"status":"cancelled"}. Stornierung ist endgültig. expired wird aus der Ablaufzeit abgeleitet; eine abgelaufene Rechnung kann nicht verlängert werden.

Preis, Kostenanteile, Beschreibung, orderId, Metadaten und Ablauf sind unveränderlich. Erstellen Sie eine andere Rechnung für andere Bedingungen. Eine Änderung der Verfügbarkeit gibt invoice.updated aus, kein Ereignis für erfolgreiche Zahlung.

Die Kundenantwort#

GET /api/checkout/{token}?method=card gibt die öffentliche Rechnung, Angebot, Methodenverfügbarkeit und vorhandenen Vorgang zurück. Eigentümer-Metadaten, Geheimnisse und Guthaben werden nicht offengelegt.

POST /api/checkout/{token}/pay erfordert den Site-Origin und eine konkrete Methode. Kartendaten werden nur als versiegelt akzeptiert: {intent,jwe}, nachdem der Browser /card-intent erhalten hat. Bankcodes sind verschlüsselt und werden über /code gesendet. Krypto verwendet eine gespeicherte USDT-Rechnung und ein verfügbares Münz-/Netzwerkpaar.

Eine neue Zahlung und Kartenabsicht erfordern, dass der neueste Website-Review-Antrag des Händlers genehmigt wurde. Die Genehmigung allein verbindet das Zahlungsgateway nicht. Wenn die Überprüfung nach dem Versand geändert wird, bleibt der bestehende Vorgang für Statusabfragen, Abgleich und einen angefragten Bankcode verfügbar.

Eine fehlende Live-Verbindung gibt GATEWAY_NOT_CONNECTED zurück; eine inkompatible Zuordnung wird nie durch eine andere Berechnung ersetzt. Status und reconcile lesen den ursprünglichen Vorgang ohne doppelte Belastung.

Mehrere Geschäfte und ein USD-Basispreis#

Wählen Sie Alle Geschäfte für aggregierte Analysen und Betrieb, oder wählen Sie ein Geschäft für dessen eigene Aufzeichnungen. Jedes Geschäft hat eine separate storeId, einen Namen, einen MwSt-Standardwert, Rechnungen, API-Schlüssel, Webhook-Endpunkte, Ereignisverlauf und Website-Anwendung. Benachrichtigungen und Support-Tickets gehören zum Konto. Ein Konto kann bis zu 100 Geschäfte erstellen. Vorhandene Datensätze verbleiben im ersten Geschäft.

Neue Workspace-Rechnungen verwenden pricingMode="universal" und einen USD-Basispreis. Any umfasst Karte, Alipay, SBP und Krypto; ein Händler kann eine Teilmenge auswählen. Karten und Alipay berechnen USD. SBP berechnet RUB unter Verwendung des USD/RUB-Referenzkurses der Bank von Russland. Krypto berechnet USDT gemäß der expliziten Rechnungsregel 1 USD = 1 USDT. Dies ist eine Rechnungsumrechnungsregel, kein Markt-USDT-Kurs. Das Gateway liefert den Kurs der ausgewählten Münze, den genauen Überweisungsbetrag und Anweisungen vor der Überweisung.

Der Referenzkurs und beide Beträge werden bei der Erstellung eingefroren. Rechnungen mit RUB-Umrechnung verfallen innerhalb von 24 Stunden. Wenn der Referenzkurs nicht abgerufen werden kann, schlägt die Erstellung mit FX_UNAVAILABLE fehl; es wird kein erfundener oder veralteter Ersatzkurs verwendet. Der Basisbetrag Minor und Angebote verwenden die USD-Buchungswährung. quotes[method].settlement enthält das native Belastungsangebot. Der öffentliche Checkout legt die ausgewählte Belastungswährung in currency, den ursprünglichen Preis in baseAmountMinor/baseCurrency und den Referenzkurs in fx offen. Sobald eine Zahlung ausgelöst wurde, kann ihre Methode nicht geändert werden; eine Rechnung hat einen Gateway-Vorgang.

Erstellen Sie einen API-Schlüssel im vorgesehenen Geschäft und senden Sie Authorization: Bearer <key> von Ihrem Server. Seine Geschäftsbindung ist unveränderlich; X-Kevmi-Store kann ihm keinen Zugriff auf ein anderes Geschäft gewähren. Browser-Sitzungen wählen X-Kevmi-Store: <storeId>; wenn es weggelassen wird, wird das erste Geschäft ausgewählt. Der Wert all wird nur von GET /api/account/dashboard und GET /api/payment-links akzeptiert. Mutationen erfordern ein ausgewähltes Geschäft, Origin und X-CSRF-Token. Konto-IDs und Geschäfts-IDs sind unterschiedliche Kennungen.

Aus Kompatibilitätsgründen behalten API-Anfragen ohne pricingMode="universal" native Preise und die ursprünglichen Währungsbeschränkungen bei. Bestehende Rechnungen werden nie neu berechnet. Bestätigte Zahlungseingänge in Analysen spiegeln verifizierte Zahlungen abzüglich gespeicherter Rechnungsausgaben wider; sie sind kein abhebbarer Saldo. Legacy-Rechnungswährungen bleiben getrennt, und Auszahlungen werden mit dem Support vereinbart. Führen Sie eine Bestellung erst aus, nachdem Sie payment.fulfillmentReady=true und payment.status="succeeded" über die Server-API, den Ereignisverlauf oder einen signierten Webhook geprüft haben.