Im Folgenden finden Sie einige wichtige Anwendungsfälle sowie die Richtlinien und APIs, die für die Implementierung Ihrer Bargeldzahlung erforderlich sind.
Anwendungsfälle
Die Reference Number API kann vielfältig eingesetzt werden. In diesem Leitfaden werden zwei Anwendungsfälle erörtert und Sie werden durch deren Implementierung geführt.
- Bar: Der Nutzer zahlt in bar an einem physischen Standort.
- VAN: Der Nutzer überweist Geld an eine virtuelle Kontonummer.
Barzahlung
Nutzer können etwas bei Google kaufen, indem sie es an einem physischen Standort, z. B. in einem Verbrauchermarkt, mit Bargeld bezahlen. Zur Identifizierung der Transaktion generiert der Nutzer eine Referenznummer, mit der er im Geschäft bezahlen kann. Darüber hinaus zeigt Google dem Nutzer eine Anleitung zum Abschließen des Kaufs an. Im Idealfall benachrichtigt der Integrationspartner Google, sobald der Nutzer den Kauf abgeschlossen hat, damit Google das Produkt liefern kann.
Ihr Ansprechpartner bei Google wird Sie um ein Muster Ihrer typischen Zahlungsanweisungen bitten. Sie arbeiten mit Ihrem Ansprechpartner bei Google zusammen, um die Werbebotschaft zu optimieren.
Die von Google angestrebte Nutzererfahrung ist, dass die Bestellung des Kunden beim Verlassen des Geschäfts geliefert wird. Google erwartet, dass die ReferenceNumberPaidNotification innerhalb von drei Minuten nach Begleichung der Referenznummer durch den Kunden bei Google eingegangen ist. Nachdem die ReferenceNumberpaidNotification gesendet wurde, kann die Transaktion vom Integrator nicht mehr rückgängig gemacht werden.
Virtuelle Kontonummer (VAN)
Nutzer können mit ihrem Bankkonto für eine Ware bezahlen. Google fordert vom Integrator eine virtuelle Kontonummer an, unter der dem Nutzer die Nummer und eine Anleitung präsentiert werden. Der Nutzer kopiert dann die Nummer und gibt sie zusammen mit dem zu überweisenden Betrag in die Banking-App ein.
Der Integrationspartner muss überprüfen, ob der überwiesene Betrag mit dem Betrag der referenceNumberGeneration-Anfrage übereinstimmt, und Google dann darüber informieren, dass die Referenznummer bezahlt wurde.
Sobald Google die ReferenceNumberPaidNotification erhält, stellt Google das Produkt bereit und die Transaktion kann vom Integrator nicht mehr rückgängig gemacht werden.
Nachrichten zwischen Ihren Servern und den Google-Servern senden
Befolgen Sie beim Senden von Nachrichten zwischen Ihren Servern und den Servern von Google oder umgekehrt diese Richtlinien.
Eingehende Anfrage - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Ausgehende Antwort - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Google-Anfrage - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Google-Antwort - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Hier finden Sie eine PGP-Bibliothek und ein Beispiel in Java, die die Verarbeitung von Anfragen und Antworten veranschaulicht.
Idempotentes Verhalten verfolgen
Idempotenz bedeutet, dass Sie nicht versuchen sollten, bereits erfolgreich bearbeitete Anforderungen (z. B. Zahlungen) noch einmal zu bearbeiten. Stattdessen sollte die Antwort für die erfolgreiche Verarbeitung zurückgegeben werden.
Warum ist das wichtig?
Google kann einige Anfragen wiederholen, um zu prüfen, ob der Status auf unserer Seite mit dem Status auf Anbieterseite übereinstimmt. Ihr System sollte keine andere Transaktion erkennen. Daher ist Idempotenz sehr wichtig. Das bedeutet, dass ein Integrator etwas, das bereits erfolgreich verarbeitet wurde, nicht noch einmal verarbeiten sollte. In diesem Fall sollte stattdessen die vorherige Antwort gesendet werden.
Implementierung von Idempotenz
Wenn Google es noch einmal sendet, ist die Anfrage-ID und der Inhalt identisch, nur der Zeitstempel ist anders. Antworten Sie mit der gleichen Antwort, die Sie zuvor gesendet haben. Wenn Ihre erste Antwort „200 (Erfolgreich)“ lautet, erwartet Google dieselbe Antwort mit einem anderen Zeitstempel.
Wenn Ihre vorherige Antwort ein Fehler war (z. B. 400 oder 500), sollten Sie diese Anfrage als neue Anfrage verarbeiten und noch einmal prüfen. Dies ist hilfreich, wenn Ihr Server zum ersten Mal ausfielen und ein neuer Versuch unternommen wird, gibt der Anfrage eine weitere Chance, erfolgreich verarbeitet zu werden.
Weitere Informationen findest du in dieser detaillierten Anleitung.
Zahlungsintegrator-Konto-ID (PIAID) verwenden
Integrationen mit Google erfordern möglicherweise eine Integration mit den verschiedenen Geschäftseinheiten von Google. So ist beispielsweise Google Play ein Rechtssubjekt, ein anderes YouTube und ein weiteres Google Ads. Für jede dieser Konfigurationen sind unterschiedliche Händlerkonten erforderlich.
Für die Zuordnung zwischen den einzelnen Rechtssubjekten innerhalb von Google und den einzelnen Händlerkonton stellt Google Zahlungsintegrator-Konto-IDs (Payment Integrator Account IDs, PIAIDs) zur Verfügung. Ein Beispiel für die Cash FOP API findest du untergenerateReferenceNumber. Im folgenden Beispiel wird diese Zuordnung verwendet.
Für die Zuordnung zwischen den einzelnen Rechtssubjekten innerhalb von Google und den einzelnen Händlerkonton stellt Google Zahlungsintegrator-Konto-IDs (Payment Integrator Account IDs, PIAIDs) zur Verfügung. Ein Beispiel für die Verwendung der Cash FOP API findest du unter generateReferenceNumber. Im folgenden Beispiel wird diese Zuordnung verwendet.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Beachten Sie den hervorgehobenen Teil. Die beiden hier erforderlichen Werte sind die paymentIntegratorAccountId, die du von deinem Ansprechpartner bei Google erhältst, und dein Händlerkonto.
Der Integrator kann je nach Land auch unterschiedliche Konten haben. Das kann an verschiedenen Steuergesetzen und anderen Unterschieden zwischen den Ländern liegen. In diesem Fall könnte für jedes Land eine weitere PIAID generiert werden.
Zu integrierende APIs
Die folgenden APIs verarbeiten die Referenznummerngenerierung und Zahlungsbenachrichtigungen.
Überweisungen und Abrechnungen werden über die folgenden APIs abgewickelt.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement mit Änderungen
Sie müssen alle oben genannten APIs integrieren, um Referenznummern zu generieren und den Vorgang mit Google abzugleichen.
Referenznummer generieren
Google ruft GenerateReferenceNumber auf, wenn Sie einen Kauf initiieren. Sie müssen in Ihrer Antwort eine Referenznummer für die Transaktion oder das Konto angeben. Die erwartete Latenz beträgt weniger als 3 Sekunden.
Bei Bartransaktionen kann die Referenznummer bis zu 12 Zeichen lang sein.
URL: POST https://[your basepath]/v1/generateReferenceNumber
Anfrage (JSON)
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"requestTimestamp": "1561678470395"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"transactionDescription": "Google Play - Tester",
"currencyCode": "USD",
"amount": "10000000"
}
Antwort (JSON)
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Java-Beispiel
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Referenznummer stornieren
Google kann eine Referenznummer deaktivieren und verhindern, dass sie vom Nutzer bezahlt wird. Ein Beispiel für einen Anwendungsfall ist ein Angebot, das abgelaufen ist. Nachdem Sie mit dieser Anfrage zufrieden waren, müssen Sie sicherstellen, dass die Referenznummer nicht mehr gezahlt werden kann.
Wenn der Nutzer den Zahlungsvorgang bereits eingeleitet hat, z. B. mit einem Verweis auf eine Referenznummer an der Kasse, sollte Ihr Server mit der HTTP-Antwort 423 und der Antwort „ErrorResponse“ im Anfragetext mit dem Status USER_ACTION_IN_PROGRESS antworten.
URL: POST https://[your basepath]/v1/cancelReferenceNumber
Anfrage (JSON)
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "51e00f16-36ba-4490-b228-0a670d202206",
"requestTimestamp": "1561678947926"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Antwort (JSON)
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Sobald die Zahlung akzeptiert wurde und die Transaktion abgeschlossen ist, muss Google von Ihrem Dienst darüber informiert werden, dass die Transaktion abgeschlossen ist und das Produkt an den Nutzer geliefert wird. Nach Eingang dieser Benachrichtigung bei Google geht Google davon aus, dass die Transaktion abgeschlossen ist und nicht reserviert werden kann.
Endpunkt-URL für referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Anfrage (JSON)
{
"requestHeader": {
"requestTimestamp": "1561748625577",
"requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
}
},
"paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
"paymentLocation": {
"brandName": "TestMart",
"locationId": "1234"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"paymentTimestamp": "1561748625577"
}
Antwort (JSON)
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Überweisungen implementieren
Sobald Sie die APIs für Ihr Zahlungsmittel integriert haben, können Sie Überweisungen vornehmen. Die Überweisung funktioniert bei allen Zahlungsmitteln gleich.
remittanceStatementNotification
Google sendet zwei Tage nach einer Transaktion eine remittanceStatementNotification mit einer Zusammenfassung der Transaktionen, die Google an diesem Tag erfasst hat. Zwei Tage nach einer Transaktion sehen Sie eine Beispielbenachrichtigung:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Anfrage (JSON)
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-statement-abc",
"requestTimestamp": "1502632800000"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"remittanceStatementSummary": {
"statementDate": "1502607600000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502521199000",
},
"dateDue": "1503212400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
}
}
Beachten Sie die totalDueByIntegrator-Zuordnung. In dieser Zeile sehen Sie den Nettobetrag, den der Integrator bezahlt (in Mikros). In dieser Nachricht werden auch das Datum und der Währungstyp angezeigt, wobei der Abrechnungszeitraum 00:00:00.000 bzw. 23:59:59.999 des frühesten bzw. letzten Transaktionstags entspricht.
Abgleich (remittanceStatementDetails)
Zum Abgleich ruft der Integrator remittanceStatementDetails auf, um die Liste der Ereignisse abzurufen, die in der remittanceStatementNotification enthalten sind.
Google antwortet auf die remittanceStatementDetails-Anfrage mit einer paginierten Liste von Ereignissen. remittanceStatementDetails sollte mehrmals aufgerufen werden, wenn die Anzahl der Transaktionen insgesamt größer als 1.000 ist. Die Anfragen müssen nicht sequenziell gesendet werden und können parallelisiert werden.
Anfrage-URL
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Beispiel für den Anfragetext
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Hier ist ein kurzer Ausschnitt aus einer größeren Antwort, in dem zwei Erfassungsereignisse (Transaktionen) beschrieben werden.
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Weitere Informationen finden Sie unter remittanceStatementDetails.
acceptRemittanceStatement und acceptRemittanceStatementWithModifications
Integratoren sollten diese Ereignisse mit den Ereignissen vergleichen, die sie aufgezeichnet haben. Wenn Transaktionen nicht übereinstimmen oder Transaktionen fehlen, wenden Sie sich zur weiteren Untersuchung an Google. Wenn alle Transaktionen übereinstimmen und die Bearbeitungsgebühr keine Steuern enthält, rufen Sie acceptRemittanceStatement an. Wenn Steuern enthalten sind, rufen Sie acceptRemittanceStatementWithModifications auf.
Die Methode acceptRemittanceStatement wird verwendet, wenn keine Steuern auf Gebühren anfallen.
Wenn eine Steuer enthalten sein soll, rufen Sie acceptRemittanceStatementWithModifications auf und definieren Sie den Steuersatz. Sollte sich Ihr Steuersatz ändern, müssen Sie ihn aktualisieren. Veranlasse nach einer erfolgreichen acceptRemittanceStatement eine Überweisung auf das Google-Konto.
Anfrage-URL für acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Beispiel für den Anfragetext
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Beispielantwort
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
Anfrage-URL für acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Beispiel für den Anfragetext
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Beispielantwort
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}