Zahlungs-Gateway-Integration
Das Gateway verarbeitet finanzielle Vorgänge. Kevmi verbindet sie mit Bestellungen, Shop-Einstellungen und Benachrichtigungen. Dieser Leitfaden beschreibt den Integrationsvertrag und Verfügbarkeitsprüfungen.
Auf dieser Seite
Verfügbarkeit prüfen#
Kevmi verwendet die Gateway-v3-API, um Vorgänge zu erstellen und wiederherzustellen, Status zu lesen und Ergebnisse abzugleichen. Die Integration unterstützt verschlüsselten Karten- und Bankcode-Transport, Alipay- und SBP-QR-Zahlungen, einen Krypto-Münz-/Netzwerk-Katalog und eingehende finanzielle Ereignisse.
gateway.configured in GET /api/config meldet, ob die erforderlichen Verbindungseinstellungen vorhanden sind. Dieser Endpunkt prüft das Gateway nicht; gateway.connected=false bedeutet hier, dass die Konnektivität nicht verifiziert wurde. Für eine bestimmte Rechnung lesen Sie invoice.availability in GET /api/checkout/{token}: Sie prüft Methode, Betrag, Bedingungen und Händlergenehmigung. Das Kompatibilitätsfeld invoice.gatewayConnected spiegelt availability.available wider und ist weder ein Health-Check noch eine Garantie für Zahlungsgenehmigung.
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.
Kunden-Checkout-Vertrag#
Sensible Daten werden im Browser mit RSA-OAEP-256 und A256GCM verschlüsselt. Der private Schlüssel bleibt auf dem Gateway. Kevmi validiert, dass die Absicht zu dieser Rechnung und diesem Zweck gehört, leitet den Umschlag weiter und speichert keine Klartext-Kartennummern, CVV, Käufername, E-Mail, Bankcodes oder den Umschlag selbst.
Installieren Sie die Erweiterung für verschlüsselten Transport auf dem Gateway-Host, bevor Sie Karten aktivieren. Sie prüft Absichtssignatur, Ablauf, Wiedergabe, Bestellung und Beträge. Es gibt keinen Klartext-Fallback. Dies beschreibt den Schutzmechanismus, nicht PCI-Zertifizierung.
| Kevmi-Route | Zweck |
|---|---|
| GET /api/checkout/{token} | Rechnung, Angebot, Methodenverfügbarkeit und bestehende Zahlung |
| POST /api/checkout/{token}/card-intent | Einmalige Absicht und öffentlicher Schlüssel für Zahlung oder Code |
| POST /api/checkout/{token}/pay | Operation starten; Kartendaten versiegelt: {intent,jwe} |
| POST /api/checkout/{token}/code | Verschlüsselter Einmalcode für die aktuelle Bank-Herausforderung |
| GET /api/checkout/{token}/status | Ursprüngliche Operation ohne weitere Belastung lesen |
| POST /api/checkout/{token}/reconcile | Ursprüngliche Operation explizit abgleichen |
| GET /api/checkout/{token}/crypto-services | Aktuelle Münzen, Netzwerke und Limits für eine USDT-Rechnung |
Hosting und Gateway-Konnektivität#
Kevmi unterstützt Site-Hosting auf Cloudflare Workers mit D1 und Self-Hosting auf Node.js mit SQLite. SQLite erfordert einen persistenten Speicher und Backups. Das Zahlungs-Gateway läuft als separater Dienst mit eigenem dauerhaften Speicher.
Ein externes Gateway erfordert einen HTTPS-Ursprung, der vom Server erreichbar ist. Im Self-Hosting-Paket verbindet sich der Server mit einem festen Gateway-Dienst im privaten Container-Netzwerk; die API des Gateway-Dienstes ist nicht über das Internet erreichbar. Die öffentliche Website und Callbacks verwenden HTTPS. Der Browser verschlüsselt außerdem Kartendaten und Bankcodes, bevor sie Kevmi erreichen.
localhost bezieht sich auf den aktuellen Server oder Container; es legt den Computer des Gateway-Betreibers nicht offen. Verbindungsschlüssel und Geheimnisse gehören ausschließlich in die Serverkonfiguration.
Für eine benutzerdefinierte Domain setzen Sie vor dem Build einen öffentlichen HTTPS-Ursprung in NEXT_PUBLIC_SITE_URL. Dokumentation, kanonische Links und Indexierungsressourcen verwenden diesen Wert. Er akzeptiert nur ein Schema und einen Host mit optionalem Port, ohne Pfad, Query, Fragment oder Anmeldedaten. Gleichen Sie ihn mit APP_ORIGIN in der Serverkonfiguration ab.
Berechnung und unterstützte Bedingungen#
Neue Workspace-Rechnungen verwenden einen USD-Basispreis, und Any bietet alle vier Methoden an. SBP rechnet zum eingefrorenen Referenzkurs der Bank von Russland in RUB um; Krypto verwendet die explizite 1:1-USD/USDT-Rechnungsregel. Legacy-native Preise bleiben für alte Rechnungen und API-Anfragen ohne pricingMode=universal verfügbar. Siehe Abschnitt zu mehreren Geschäften und USD-Preisen unten.
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.
Das Senden eines beliebigen total_cents ändert die Steuerberechnung des Anbieters nicht. Ein tatsächlicher Betrag, der vom gespeicherten Total abweicht, geht in die Prüfung und kann die Ausführung nicht bestätigen. Gateway-business_balance-Felder werden als Abrechnungsnachweis aufbewahrt und nicht als Kevmi-Händlerguthaben behandelt.
Verbindung eines Live-Gateways#
Die Verbindung des Gateways umfasst die Serverkonfiguration, Prüfungen für die ausgewählten Kanäle und die Verarbeitung verifizierter Finanzereignisse. Die Konfigurationsbereitschaft wird getrennt von der Anbieter-Konnektivität geprüft. Eine erfolgreiche Zahlung wird nach Prüfung des Operationsstatus und des Betrags akzeptiert. Bereitstellungsanweisungen finden Sie in ops/gateway-integration.md.
- 1
Stellen Sie den Kevmi-Server und das Gateway als separate Dienste bereit. Konfigurieren Sie dauerhaften Speicher, Backups und die erforderlichen Hintergrundprozesse.
- 2
Für eine externe Verbindung setzen Sie einen HTTPS-Ursprung in GATEWAY_BASE_URL. Das Self-Hosting-Paket verwendet seinen konfigurierten internen Dienst. Beide erfordern einen Nur-Server-GATEWAY_API_KEY und ein separates GATEWAY_WEBHOOK_SECRET; Geheimnisse erreichen niemals den Browser.
- 3
Setzen Sie die Gateway-BACKEND_WEBHOOK_URL auf /api/gateway/webhook bei Kevmi und ein passendes BACKEND_WEBHOOK_SECRET.
- 4
Aktivieren Sie den verschlüsselten Kartentransport und bewahren Sie seinen privaten Schlüssel ausschließlich auf dem Gateway-Host auf. Prüfen Sie die Verfügbarkeit des öffentlichen Schlüssels und passende Einstellungen zur Absichtssignierung.
- 5
Prüfen Sie Kanalbereitschaft, Einschränkungen und die Genehmigung der Händler-Website vor dem Start.
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.