Protokollstandards

Die API folgt einer Reihe von HTTP-API-Standards und unterstützt Idempotenz, um eine robustere Integration zu ermöglichen.

Von Google gehostete URLs

Die Dokumentation für jede von Google gehostete Methode enthält eine Basis-URL, die den Methodennamen und die Hauptversionsnummer enthält. Zur Erstellung der vollständigen URL wird die Zahlungsintegrator-Konto-ID des Aufrufers an das Ende angehängt. In der Dokumentation für die von Google gehostete Echo-Methode ist beispielsweise die URL angegeben:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Wenn die Zahlungsintegrations-Konto-ID des Aufrufers INTEGRATOR_1 lautet, fügt er diese an das Ende der URL an, um Folgendes zu erstellen:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Hinweis: Die Endpunktdokumentationsseite für die spezifische Methode, die Sie implementieren, enthält die genaueste URL für Ihren Fall.

Von Partnern gehostete URLs

In der Dokumentation für jede vom Partner gehostete API-Methode finden Sie eine Basis-URL, die den Methodennamen und die Hauptversionsnummer enthält. Die Zahlungsintegrator-Konto-ID (PIAID) darf nicht in den von Ihnen gehosteten URLs enthalten sein.

Sandbox- und Produktionsumgebungen

Google hostet Standard-Zahlungs-APIs sowohl in der Sandbox (zu Entwicklungs- und Testzwecken) als auch in der Produktion. Anfragen in der Google-Sandbox-Umgebung führen nicht zu einer finanziellen Haftung. Die Sandbox- und Produktionsumgebungen sind vollständig voneinander getrennt und teilen keine Schlüssel oder Transaktionsinformationen.

Google geht davon aus, dass deine Sandbox ständig verfügbar ist, da wir sie verwenden, um zuerst Änderungen und neue Funktionen zu testen.

Sandbox-Basispfad von Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Hinweis :Wenn Ihre Integration bereits eingeführt wurde und den Host „https://billpaynotification.sandbox.googleapis.com“ aufruft, können Sie das weiterhin tun. Neue Integrationen sollten den Host „vgw.sandbox.google.com“ aufrufen.

Produktionsbasis von Google

https://vgw.googleapis.com/secure-serving/gsp/

Hinweis :Wenn Ihre Integration bereits gestartet wurde und den https://billpaynotification.googleapis.com-Host aufruft, können Sie das weiterhin tun. Neue Integrationen sollten den Host „vgw.googleapis.com“ aufrufen.

In diesem Leitfaden werden die Produktionsendpunkte verwendet.

Inhaltstyp und Codierung

Nachrichtennutzlasten, die PGP-Verschlüsselung verwenden, müssen den Inhaltstyp application/octet-stream; charset=utf-8 verwenden. PGP-Anfragetexte müssen mit der base64url-Codierung gesendet werden, wie in rfc4648 §5 definiert. Nachrichtennutzlasten mit JWE-Verschlüsselung müssen den Inhaltstyp application/jose; charset=utf-8 verwenden. Die von JWE/JWS unterstützte Option für kompakte Serialisierung verarbeitet die Codierung für den endgültigen Anfragetext.

HTTP-Statuscodes

Standard Payments APIs geben für alle Anfragen, die vom Server verarbeitet werden können, den HTTP-Statuscode 200 zurück. Dies umfasst sowohl erfolgreiche als auch abgelehnte Anfragen aus Sicht der Geschäfts- oder Anwendungslogik. Anfragen, die nicht verarbeitet werden können, sollten nicht zu einem HTTP-Statuscode 200 führen, da sie einen Fehler zwischen Google und dem Partner darstellen. Stattdessen sollte die API-Antwort die entsprechenden HTTP-Statuscodes unten mit einem optionalen ErrorResponse-Objekt verwenden.

HTTP-Fehler und -Gründe
400	BAD REQUEST Der Client hat ein ungültiges Argument angegeben. Er kann auch zurückgegeben werden, wenn der Vorgang abgelehnt wurde, da sich das System nicht in einem Zustand befindet, der für die Ausführung des Vorgangs erforderlich ist. Verwenden Sie diese Option, wenn Wiederholungsversuche der Anfrage erst dann erfolgreich sind, wenn der Systemstatus explizit korrigiert wurde. Wenn beispielsweise eine Erstattungsanfrage fehlschlägt, weil sie auf eine nicht vorhandene Erfassung verweist, ist ein Wiederholungsversuch erst erfolgreich, wenn die Erfassung im Integratorsystem vorhanden ist. Hinweis:BAD_REQUEST (400) darf nicht in Situationen verwendet werden, in denen ein entsprechender Anwendungsfehler verfügbar ist. Falsche Währungen sollten beispielsweise ACCOUNT_DOES_NOT_SUPPORT_CURRENCY mit dem Code 200 zurückgeben, wenn die Standardantwort dieses Feld oder diese Enum enthält.
401	UNAUTHORIZED Die Anfrage enthält keine gültigen Authentifizierungsdaten für den Vorgang. Beispielsweise sollte bei ungültigen oder unbekannten Signaturen der Fehler 401 zurückgegeben werden.
403	FORBIDDEN / PERMISSION DENIED Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs.
404	NOT FOUND Ein angefordertes Element (z. B. Zahlung oder Nutzer) wurde nicht gefunden.
409	CONFLICT / ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Nebenläufigkeitsproblems wie Fehler bei der Sequencer-Überprüfung, abgebrochenen Transaktionen usw.
412	PRECONDITION FAILED Dieser Code sollte in Situationen verwendet werden, in denen ein Idempotenzschlüssel mit anderen Parametern wiederverwendet wird.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Eine Systemressource ist erschöpft.
499	CANCELLED Der Vorgang wurde abgebrochen (in der Regel vom Aufrufer).
500	INTERNAL ERROR Interne Fehler. Das bedeutet, dass einige Invarianten, die vom zugrunde liegenden System erwartet werden, nicht mehr funktionieren.
501	UNIMPLEMENTED Der Vorgang ist in diesem Dienst nicht implementiert, unterstützt oder aktiviert.
503	UNAVAILABLE Der Dienst ist derzeit nicht verfügbar. Dies ist höchstwahrscheinlich ein vorübergehender Zustand und kann durch Wiederholungsversuche behoben werden.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Bei Vorgängen, die den Systemstatus ändern, kann dieser Fehler auch dann zurückgegeben werden, wenn der Vorgang erfolgreich abgeschlossen wurde. Beispielsweise kann eine erfolgreiche Antwort von einem Server so lange verzögert worden sein, dass die Frist abgelaufen ist.

Idempotenz anfordern

Die Anfrage-IDempotenz ist eine zentrale Strategie, die in den Standard-Zahlungs-APIs verwendet wird, um sicherzustellen, dass die Systeminteraktionen zwischen Google und Partnern robust und fehlertolerant sind. Idempotente Anfragen sind Anfragen, die möglicherweise mehrmals gesendet werden, aber denselben Effekt wie eine einzelne Anfrage haben. Diese Strategie ermöglicht Eventual Consistency zwischen Systemen, indem Wiederholungsversuche sicher gemacht werden, sodass unsere Systeme zu einer Einigung über den Zustand der Ressource kommen.

Unsere API nutzt Idempotenz für Folgendes:

• Abgleichsprobleme lassen sich reduzieren, indem alle Aktionen leicht nachvollziehbar und prüfbar gemacht werden.
• Race-Bedingungen verhindern, indem mehrere identische Anfragen vom selben Client nicht zu einem anderen Endzustand führen.
• den Status zu minimieren, indem Sie zulassen, dass Anfragen isoliert gelesen werden. Dies ermöglicht eine verbesserte Leistung und einen höheren Durchsatz, da die durch die Aufbewahrung von Daten verursachte Serverlast beseitigt wird.
• Es sind keine zusätzlichen Felder erforderlich, die angeben, ob es sich bei einer Anfrage um eine Wiederholung handelt.

Hinweis: Fehlerergebnisse dürfen niemals im Cache gespeichert oder idempotent zurückgegeben werden. Und bei automatischen Wiederholungsversuchen nach Fehlern muss eine Strategie mit exponentiellem Backoff angewendet werden.

Beispiele

Beispiel 1: Konnektivität vor dem Empfang der Antwort unterbrochen

Szenario:

1. Google sendet eine Anfrage an den Integrator.
2. Der Integratorserver empfängt diese Anfrage und verarbeitet sie erfolgreich.
3. Der Google-Server wird mit Strom versorgt, bevor die Antwort in Schritt 2 eingeht.
4. Die Serverleistung von Google wird wiederhergestellt und dieselbe Anfrage mit denselben Parametern (dieselbe Anfrage-ID und Anfragedetails, aber aktualisierter requestTimestamp) an den Server des Integrators gesendet.

Ergebnis:

In diesem Fall muss der Integratorserver mit der in Schritt 2 angegebenen Antwort antworten, da alle Parameter mit Ausnahme von responseTimestamp identisch sind. Der Nebeneffekt tritt in Schritt 2 nur einmal auf. Schritt 4 hat keinen Nebeneffekt.

Beispiel 2: An einen Server gesendete Anfrage, die gerade gewartet wird

Szenario:

1. Die Datenbank des Integrator-Servers ist wegen Wartungsarbeiten nicht verfügbar.
2. Google sendet eine Anfrage an den Integrator.
3. Der Integrator gibt korrekt den Statuscode UNAVAILABLE zurück.
4. Der Google-Server empfängt die Antwort und plant einen erneuten Versuch.
5. Die Datenbank des Integrator-Servers ist wieder online.
6. Google sendet die Anfrage aus Schritt 2 noch einmal (dieselbe Anfrage-ID und Anfragedetails, aber aktualisierte requestTimestamp). Die Anfrage-IDs müssen für beide Anfragen identisch sein.
7. Der Integrator-Server empfängt die Anfrage und gibt einen Statuscode „OK“ zusammen mit der vollständigen Antwort zurück.

Ergebnis:

In diesem Fall muss der Integratorserver die Anfrage in Schritt 7 verarbeiten und nicht die HTTP-Anfrage 503 (UNAVAILABLE) zurückgeben. Stattdessen sollte der Integratorserver die Anfrage vollständig verarbeiten und die entsprechende Nachricht mit „OK“ zurückgeben. Obwohl das System den Status UNAVAILABLE hat, kann Google ähnliche Anfragen wie in Schritt 2 wiederholen. Jede Anfrage sollte zu einer Meldung wie in Schritt 3 führen. Schließlich werden Schritt 6 und Schritt 7 ausgeführt.

Beispiel 3: Nachricht in wiederholtem Sendevorgang stimmt nicht mit ursprünglicher Nachricht aufgrund eines Wiederherstellungsfehlers überein

Szenario:

1. Google sendet eine Anfrage an den Integrator.
2. Der Integratorserver empfängt diese Anfrage und verarbeitet sie erfolgreich.
3. Der Google-Server wird mit Strom versorgt, bevor die Antwort in Schritt 2 eingeht.
4. Die Serverleistung von Google wird wiederhergestellt und versucht, die gleiche Anfrage zu senden, aber einige Parameter unterscheiden sich leider nicht.

Ergebnis:

In diesem Fall sollte der Integratorserver mit dem HTTP-Fehlercode 412 (PRECONDITION FAILED) antworten, der Google darauf hinweist, dass in diesem System ein Fehler vorliegt.