Im Folgenden finden Sie einige wichtige Anwendungsfälle sowie die Richtlinien und APIs, die für die Implementierung Ihres Zahlungsmittels erforderlich sind.
Anwendungsfälle
Die Reference Number API kann für verschiedene Zwecke eingesetzt werden. In diesem Leitfaden werden zwei Anwendungsfälle erörtert und Sie durch deren Implementierung geführt.
- Barzahlung: Der Nutzer bezahlt in bar an einem physischen Standort.
- VAN: Der Nutzer überweist Geld auf eine virtuelle Kontonummer.
Barzahlung
Nutzer können etwas bei Google kaufen, indem sie an einem physischen Standort, z. B. in einem Verbrauchermarkt, bar bezahlen. Zur Identifizierung der Transaktion generiert der Nutzer eine Referenznummer, über die er zum Bezahlen das Geschäft bringen kann. Darüber hinaus zeigt Google dem Nutzer eine Anleitung zum Abschließen des Kaufs an. Idealerweise benachrichtigt der Integrator Google, sobald der Nutzer den Kauf abschließt, damit Google das Produkt liefern kann.
Ihr Ansprechpartner bei Google wird Sie um ein Beispiel für eine typische Zahlungsanleitung bitten. In Zusammenarbeit mit Ihrem Ansprechpartner bei Google optimieren Sie die Werbebotschaft.
Google möchte den Kunden bieten, dass die Bestellung beim Verlassen des Geschäfts geliefert wird. Google geht davon aus, dass die ReferenceNumberPaidNotification innerhalb von drei Minuten nach Bezahlung der Referenznummer bei Google eingeht. Sobald die ReferenceNumberPaidNotification gesendet wurde, kann die Transaktion vom Integrator nicht mehr rückgängig gemacht werden.
VAN
Ein Nutzer kann eine Ware über sein Bankkonto bezahlen. Google fordert vom Integrator eine virtuelle Kontonummer an, die dem Nutzer die Nummer und die Anleitung vorlegt. Der Nutzer kopiert dann die Nummer und gibt sie zusätzlich zum Überweisungsbetrag in seiner Bankanwendung ein.
Der Integrator muss überprüfen, ob der übertragene Betrag mit dem Anfragebetrag „referenceNumberGeneration“ übereinstimmt. Anschließend muss er Google darüber informieren, dass die Referenznummer gezahlt wurde.
Sobald Google die ReferenceNumberPaidNotification erhält, liefert Google das Produkt 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 folgen
Idempotenz bedeutet, dass Sie nicht versuchen dürfen, eine bereits erfolgreich verarbeitete Anforderung (z. B. eine Zahlung) erneut zu bearbeiten. Stattdessen sollte die Antwort auf die erfolgreiche Verarbeitung gemeldet werden.
Warum ist das wichtig?
Google kann einige Anfragen wiederholen, um sicherzustellen, dass der Status auf unserer Seite mit dem Status auf der Anbieterseite übereinstimmt. Ihr System sollte diese Transaktion nicht als eine andere Transaktion behandeln. 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.
So implementieren Sie Idempotenz
Wenn Google einen erneuten Versuch sendet, ist die Anfrage-ID und der Inhalt identisch, aber der Zeitstempel ist anders. Antworten Sie mit derselben Antwort, die Sie bereits gesendet haben. Wenn Ihre erste Antwort „200 (erfolgreich)“ war, erwartet Google dieselbe Antwort mit einem anderen Zeitstempel.
Wenn es sich bei Ihrer vorherigen Antwort um einen Fehler (z. B. 400 oder 500) handelt, sollten Sie die Anfrage als neue Anfrage verarbeiten und noch einmal überprüfen. Dies ist hilfreich, wenn Ihr Server zum ersten Mal ausgefallen war und Sie die Anfrage wiederholen können.
Weitere Informationen finden Sie in diesem ausführlichen Leitfaden.
PIAID (Payment Integrator Account ID) verwenden
Für die Verknüpfung mit Google ist möglicherweise eine Integration in die verschiedenen Geschäftseinheiten von Google erforderlich. So ist Google Play beispielsweise das eine Rechtssubjekt, das andere YouTube und ein weiteres Google Ads. Dazu sind verschiedene Händlerkonten erforderlich, die jede dieser Konfigurationen repräsentieren.
Für die Zuordnung der einzelnen Rechtssubjekte innerhalb von Google zu den einzelnen Händlerkontos stellt Google die Konto-IDs der Zahlungsintegratoren (Payment Integrator Account IDs, PIAIDs) bereit. Ein Beispiel für das Cash FOP API findest du unter „generateReferenceNumber“. Im Folgenden sehen Sie ein Beispiel, in dem diese Zuordnung verwendet wird.
Für die Zuordnung der einzelnen Rechtssubjekte innerhalb von Google zu den einzelnen Händlerkontos stellt Google die Konto-IDs der Zahlungsintegratoren (Payment Integrator Account IDs, PIAIDs) bereit. Ein Beispiel für die Verwendung der Cash FOP API findest du unter generateReferenceNumber. Im Folgenden sehen Sie ein Beispiel, in dem diese Zuordnung verwendet wird.
{
"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 benötigten Werte sind die paymentIntegratorAccountId, die Sie von Ihrem Ansprechpartner bei Google erhalten haben, und Ihr Händlerkonto.
Der Integrator kann je nach Land, in dem er angeboten wird, verschiedene Konten haben. Das kann an verschiedenen Steuergesetzen und anderen Ländern liegen. In diesem Fall kann für jedes Land eine weitere PIAID generiert werden.
Einzubindende APIs
Die folgenden APIs verarbeiten die Generierung der Referenznummer und Zahlungsbenachrichtigungen.
Überweisungen und Zahlungen werden von den folgenden APIs verarbeitet.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement mit Änderungen
Sie müssen alle oben genannten APIs einbinden, um Referenznummern zu generieren und mit Google abzurechnen.
Referenznummer generieren
Google ruft GenerateReferenceNumber auf, wenn Sie einen Kauf initiieren. Wir erwarten von Ihnen, dass Sie uns in Ihrer Antwort eine Referenznummer senden, die die Transaktion oder das Konto identifiziert. Die erwartete Latenz beträgt < 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 löschen
Google kann eine Referenznummer stornieren und so verhindern, dass sie vom Nutzer bezahlt wird. Ein Beispiel für einen Anwendungsfall ist ein abgelaufenes Angebot. Nachdem Sie auf diese Anfrage erfolgreich geantwortet haben, müssen Sie dafür sorgen, dass die Referenznummer nicht bezahlt werden kann.
Wenn der Nutzer den Zahlungsvorgang bereits eingeleitet hat, z. B. über eine Suche nach einer Referenznummer an der Kasse, sollte Ihr Server mit einer HTTP 423-Antwort und einer ErrorResponse im Anfragetext mit dem Status USER_ACTION_IN_PROGRESS reagieren.
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 wurde, muss Google von Ihrem Dienst darüber informiert werden, dass die Transaktion abgeschlossen ist und das Produkt an den Nutzer geliefert wird. Sobald Google diese Benachrichtigung erhält, geht Google davon aus, dass die Transaktion abgeschlossen ist und nicht reserviert werden kann.
Endpunkt-URL 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"
}
Überweisung implementieren
Sobald Sie die APIs für Ihre jeweilige Zahlungsquelle eingebunden haben, können Sie Überweisungen vornehmen. Überweisungen funktionieren bei allen Zahlungsmitteln gleich.
remittanceStatementNotification
Zwei Tage nach einer Transaktion sendet Google eine remittanceStatementNotification mit einer Zusammenfassung der Transaktionen, die Google an diesem Tag erfasst hat. Zwei Tage nach einer Transaktion sieht eine Beispielbenachrichtigung so aus:
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 Zuordnung totalDueByIntegrator. In dieser Zeile sehen Sie den Nettobetrag, den der Integrator schuldet (in Mikros). Außerdem sind das Datum und die Währung in dieser Nachricht zu sehen. Der Abrechnungszeitraum umfasst 00:00:00.000 bis 23:59:59.999 des frühesten und des letzten Transaktionstags.
Abgleich (remittanceStatementDetails)
Zum Abgleich ruft der Integrator remittanceStatementDetails auf, um eine 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 Gesamtzahl der Transaktionen größer als 1.000 ist. Die Anfragen müssen nicht nacheinander gestellt werden, sondern können parallelisiert werden.
Anfrage-URL
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Beispiel für einen 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 kurzes Snippet 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 findest du unter remittanceStatementDetails.
acceptRemittanceStatement und acceptRemittanceStatementWithModifications
Integratoren sollten diese Ereignisse mit den von ihnen aufgezeichneten Ereignissen vergleichen. Wenn Transaktionen nicht übereinstimmen oder fehlen, wenden Sie sich an Google, um das Problem untersuchen zu lassen. Wenn alle Transaktionen übereinstimmen und die Bearbeitungsgebühr keine Steuern enthält, rufen Sie acceptRemittanceStatement auf. Wenn Steuern enthalten sind, rufen Sie acceptRemittanceStatementWithModifications an.
Die Methode acceptRemittanceStatement wird verwendet, wenn keine Steuern auf Gebühren anfallen.
Wenn eine Steuer enthalten sein soll, rufe acceptRemittanceStatementWithModifications auf und definiere den Steuersatz. Wenn sich Ihr Steuersatz ändert, aktualisieren Sie ihn bitte. Nach einer erfolgreichen acceptRemittanceStatement veranlassen Sie die Überweisung auf das Google-Konto.
Anfrage-URL für acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Beispiel für einen 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 einen 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"
}