Protokollstandards

Die API entspricht einer Reihe von HTTP API-Standards und unterstützt Idempotenz, um eine robustere

Von Google gehostete URLs

Die Dokumentation für jede von Google gehostete Methode enthält eine Basis-URL, die enthält den Methodennamen und die Hauptversionsnummer. Die vollständige URL wird erstellt. indem Sie die Konto-ID des Zahlungsintegrators zur enden. Beispielsweise in der Dokumentation zur von Google gehosteten Echo-Methode gibt die URL an:

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

Wenn die Konto-ID des Aufrufers für den Zahlungsintegrator INTEGRATOR_1 lautet, fügt er an das Ende der URL anhängen, um Folgendes zu bilden:

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

Hinweis :Die Dokumentationsseite für die jeweilige Methode, die Sie verwenden, wird die URL, die Sie implementieren, die genaueste URL für Ihren Fall erhalten.

Von Partnern gehostete URLs

In der Dokumentation für jede von Partnern gehostete API-Methode wird eine Basis-URL bereitgestellt, die enthält den Methodennamen und die Hauptversionsnummer. Das Tag Konto-ID des Zahlungsintegrators (PIAID) in den von Ihnen gehosteten URLs.

Sandbox- und Produktionsumgebungen

Google hostet Standard Payments APIs in einer Sandbox (für Entwicklung und zu Testzwecken) und in der Produktion. Anfragen in der Google-Sandbox-Umgebung führen zu keiner tatsächlichen finanziellen Haftung. Die Sandbox und Produktionsumgebungen sind völlig unabhängig und teilen keine Schlüssel oder Transaktionsinformationen.

Google geht davon aus, dass Ihre Sandbox immer verfügbar ist, da wir standardmäßig die Sandbox verwenden, um zuerst Änderungen und neue Funktionen zu testen.

Sandbox-Basispfad von Google

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

Hinweis :Wenn deine Integration bereits eingeführt ist und die https://billpaynotification.sandbox.googleapis.com-Host, du kannst fortfahren zu tun Sie dies. Neue Integrationen sollten „vgw.sandbox.google.com“ aufrufen

Basispfad für die Produktion von Google

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

Hinweis :Wenn deine Integration bereits eingeführt ist und die https://billpaynotification.googleapis.com-Host verwenden, können Sie dies auch weiterhin tun. Neue Integrationen sollten „vgw.googleapis.com“ aufrufen

In dieser Anleitung werden die Produktionsendpunkte verwendet.

Inhaltstyp und Codierung

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

HTTP-Statuscodes

Standard Payments APIs geben den HTTP-Statuscode 200 zurück für alle Anfragen, die vom Server verarbeitet werden können. Dazu gehören sowohl erfolgreichen und abgelehnten Anfragen aus Sicht des Unternehmens oder Anwendungslogik. Anfragen, die nicht verarbeitet werden können, sollten nicht zu einer HTTP-Statuscode 200, da sie einen Fehler zwischen Google und dem Partner. Stattdessen sollte in der API-Antwort der entsprechende HTTP-Status verwendet werden. Codes unten durch ein optionales ErrorResponse-Objekt.

HTTP-Fehler und -Gründe
400	BAD REQUEST Der Client hat ein ungültiges Argument angegeben. Sie kann auch zurückgegeben werden, wenn der Vorgang abgelehnt wurde, weil das System sich nicht in einem für die Ausführung des Vorgangs erforderlichen Status befindet. Verwenden Sie diese Option, wenn Wiederholungen der Anfrage erst erfolgreich sein können, wenn der Systemstatus wurde explizit behoben. Wenn ein Erstattungsantrag z. B. aus folgenden Gründen fehlschlägt: auf eine Aufnahme verweist, die nicht vorhanden ist, schlägt der Vorgang fehl. bis die Erfassung im Integratorsystem erfolgt. Hinweis:BAD_REQUEST (400) darf nicht verwendet werden wenn ein entsprechender Anwendungsfehler vorliegt. Für Beispiel: Falsche Währungen sollten ACCOUNT_DOES_NOT_SUPPORT_CURRENCY mit dem Code 200, wenn die Standardantwort enthält dieses Feld oder diese Aufzählung.
401	UNAUTHORIZED Die Anfrage enthält keine gültigen Anmeldedaten zur Authentifizierung für das . Ungültige oder unbekannte Signaturen sollten beispielsweise gibt einen 401-Fehler zurück.
403	FORBIDDEN / PERMISSION DENIED Der Aufrufer hat keine Berechtigung zur Ausführung des angegebenen Vorgangs.
404	NOT FOUND Eine angeforderte Entität wie Zahlung oder Nutzer wurde nicht gefunden.
409	CONFLICT / ABORTED Der Vorgang wurde abgebrochen, in der Regel aufgrund eines Gleichzeitigkeitsproblems wie Sequencer-Prüfungen, Transaktionsabbrüche usw.
412	PRECONDITION FAILED Dieser Code sollte in Situationen verwendet werden, in denen ein Idempotenzschlüssel verwendet wird. mit unterschiedlichen Parametern wiederverwendet.
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 einige Invarianten, die vom zugrunde liegenden System erwartet werden funktioniert nicht.
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 und kann durch einen neuen Versuch korrigiert werden.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Die Frist ist abgelaufen, bevor der Vorgang abgeschlossen werden konnte. Für Operationen, die Systemstatus ändert, kann dieser Fehler zurückgegeben werden, auch wenn der der Vorgang erfolgreich abgeschlossen wurde. Eine erfolgreiche Antwort von einem Server so lange verzögert werden können, verfallen lassen.

Idempotenz anfordern

Die Anfrage-IDempotenz ist eine zentrale Strategie, die bei der APIs, mit denen sichergestellt wird, dass Systeminteraktionen zwischen Google und Partnern funktionieren robust und fehlertolerant. Idempotente Anfragen sind Anfragen, mehrere Male gesendet werden, haben aber denselben Effekt wie eine einzelne Anfrage. Diese Strategie sorgt für Eventual Consistency zwischen Systemen, Wiederholungsversuche sicher sind, sodass unsere Systeme sich auf Status der Ressource.

Unsere API nutzt Idempotenz zu folgenden Zwecken:

• Abgleichsprobleme zu reduzieren, indem alle Aktionen leicht nachverfolgt prüfbar sind.
• Race-Bedingungen verhindern, indem Sie sicherstellen, dass mehrere identische Anfragen nicht zu einem anderen Endzustand führen.
• den Status zu minimieren, indem Anfragen isoliert verstanden werden. zur Verbesserung von Leistung und Durchsatz, indem die Serverlast durch die Aufbewahrung von Daten.
• keine zusätzlichen Felder erforderlich, um anzugeben, ob es sich bei einer Anfrage um einen Wiederholungsversuch handelt

Hinweis: Fehlerergebnisse dürfen niemals im Cache gespeichert oder idempotent zurückgegeben werden. Und Bei automatischen Wiederholungsversuchen nach Fehlern muss ein exponentieller Backoff verwendet werden.

Beispiele

Beispiel 1: Verbindung unterbrochen, bevor Antwort empfangen wurde

Szenario:

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

Ergebnis:

In diesem Fall muss der Integrator-Server mit derselben Antwort antworten, die unter Schritt 2, da alle Parameter mit Ausnahme von responseTimestamp identisch sind. Der Nebeneffekt tritt nur einmal in Schritt 2 auf. Schritt 4 hat keine Nebenwirkung.

Beispiel 2: Anfrage an einen Server gesendet, der 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 den Statuscode UNAVAILABLE korrekt zurück.
4. Der Server von Google empfängt die Antwort und plant einen Wiederholungsversuch.
5. Die Datenbank des Integrator-Servers geht wieder online.
6. Google sendet die Anfrage aus Schritt 2 noch einmal (gleiche Anfrage-ID und Anfragedetails). aber requestTimestamp aktualisiert). Die Anfrage-IDs für beide Anfragen sollte identisch sein.
7. Der Integrator-Server empfängt die Anfrage und gibt einen OK-Statuscode zusammen mit vollständiger Antwort.

Ergebnis:

In diesem Fall muss der Integrator-Server die Anfrage in Schritt 7 verarbeiten und nicht gibt HTTP 503 (UNAVAILABLE) zurück. Stattdessen sollte der Integrator-Server die Anfrage verarbeiten und mit der entsprechenden Nachricht "OK" zurückgeben. Hinweis: Während das System ist UNAVAILABLE Google kann wiederholte Anfragen stellen, ähnlich wie Schritt 2. Für jede Anfrage sollte eine Meldung wie in Schritt 3 angezeigt werden. Schritt 6 und Schritt 7 werden schließlich ausgeführt.

Beispiel 3: Wiederholte Nachricht stimmt aufgrund eines Wiederherstellungsfehlers nicht mit der ursprünglichen Nachricht überein

Szenario:

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

Ergebnis:

In diesem Fall sollte der Integrator-Server mit dem HTTP-Statuscode 412 antworten. (PRECONDITION FAILED) Fehlercode, der Google darauf hinweist, Fehler in diesem System.