Di seguito sono riportati alcuni casi d'uso importanti da considerare, nonché le linee guida e le API necessarie per implementare la forma di pagamento.
Casi d'uso
L'API Reference Number può essere utilizzata in vari modi. Questa guida illustra due casi d'uso e illustra la loro implementazione.
- Contanti: l'utente paga in contanti in un luogo fisico.
- VAN: l'utente trasferisce denaro a un numero di conto virtuale.
Contanti
Un utente può effettuare un acquisto da Google pagandolo in contanti in un negozio fisico, ad esempio un minimarket. Per identificare la transazione, l'utente genererà un numero di riferimento da portare in negozio per il pagamento. Inoltre, Google mostrerà all'utente le istruzioni per completare l'acquisto. Idealmente, non appena l'utente completa l'acquisto, l'integratore invia una notifica a Google affinché Google possa consegnare il prodotto.
Il tuo punto di contatto di Google ti chiederà un esempio delle istruzioni di pagamento standard. Collaborerai con il tuo contatto Google per ottimizzare e perfezionare i messaggi.
L'esperienza utente che Google vuole offrire è che l'ordine del cliente venga consegnato non appena esce dal negozio. Google si aspetta che Google riceva la ReferenceNumberPaidNotification entro tre minuti dal pagamento del numero di riferimento. Dopo l'invio di ReferenceNumberpaidNotification, la transazione non può essere annullata dall'integratore.
VAN
Un utente può pagare per un bene con il proprio conto bancario. Google richiederà un numero di conto virtuale all'integratore, presentando il numero e le istruzioni all'utente. L'utente copierà quindi il numero e lo inserirà nella propria applicazione bancaria oltre all'importo da trasferire.
L'integratore deve verificare che l'importo trasferito corrisponda all'importo della richiesta ReferenceNumberGeneration, quindi comunicare a Google che il numero di riferimento è stato pagato.
Una volta che Google riceve la ReferenceNumberPaidNotification, consegnerà il prodotto e la transazione non potrà essere annullata dall'integratore.
Invio di messaggi tra i tuoi server e quelli di Google
Durante l'invio di messaggi tra i propri server e quelli di Google o viceversa, è necessario attenersi alle presenti linee guida.
Richiesta in arrivo - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Risposta in uscita - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Richiesta di Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Risposta di Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Ecco una libreria e un esempio PGP in Java che mostra le richieste e le risposte di gestione.
Segui comportamenti idempotenti
Per "idempotenza" si intende che non devi tentare di elaborare nuovamente alcuna richiesta (ad esempio un pagamento) che è già stata elaborata correttamente. Deve invece essere segnalata la risposta per l'elaborazione riuscita.
Perché è importante
Google potrebbe riprovare alcune richieste per assicurarsi che lo stato dal nostro lato corrisponda a quello dal lato del fornitore. Il tuo sistema non deve pensare che si tratti di un'altra transazione. Pertanto, l'idempotenza è molto importante. Ciò significa che un integratore non deve rielaborare qualcosa che è già stato elaborato correttamente. In questo caso, deve essere inviata la risposta precedente.
Come implementare l'idempotenza
Se Google invia un nuovo tentativo, l'ID richiesta sarà lo stesso e i contenuti saranno gli stessi, ma il timestamp sarà diverso. Rispondi con la stessa risposta che hai inviato in precedenza. Se la tua prima risposta fosse 200 (Operazione riuscita), Google si aspetta la stessa risposta con un timestamp diverso.
Se la risposta precedente era un errore (400 o 500 e così via), devi elaborare questa richiesta come una nuova richiesta e controllarla di nuovo. Questa operazione è utile se il server non era disponibile per la prima volta e se ha riprovato, la richiesta ha un'altra possibilità di essere elaborata correttamente.
Per ulteriori informazioni, consulta questa guida dettagliata.
Utilizza l'ID account dell'integratore pagamenti (PIAID)
Le integrazioni con Google possono richiedere l'integrazione con le diverse entità aziendali di Google. Ad esempio, Google Play è un'entità, un'altra è YouTube e un'altra ancora è Google Ads. Saranno coinvolti diversi account commerciante per rappresentare ciascuna di queste configurazioni.
Per associare ogni entità all'interno di Google a ogni account commerciante, Google fornisce gli ID account Payment Integrator Account ID (PIAID). Per un esempio dell'API FOP in contanti, consulta generateReferenceNumber. Ecco un esempio che utilizza questa mappatura.
Per associare ogni entità all'interno di Google a ogni account commerciante, Google fornisce gli ID account Payment Integrator Account ID (PIAID). Per un esempio di utilizzo dell'API FOP in contanti, consulta generateReferenceNumber. Ecco un esempio che utilizza questa mappatura.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Osserva la parte evidenziata. I due valori necessari qui sono il paymentIntegratorAccountId fornito dal tuo punto di contatto presso Google e il tuo account commerciante.
L'integratore potrebbe anche avere account diversi a seconda del paese servito. Ciò può essere dovuto a diverse leggi fiscali e ad altre differenze da un paese all'altro. In questo caso, potrebbe essere generato un altro PIAID per ogni paese.
API per l'integrazione
Le seguenti API gestiscono la generazione del numero di riferimento e la notifica di pagamento.
Le seguenti API gestiscono i pagamenti e le liquidazione.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AccettaRemittanceStatement con modifiche
Dovrai integrare tutte le API sopra indicate per generare i numeri di riferimento e stabilirti con Google.
Genera numero di riferimento
Google chiama GeneraReferenceNumber all'avvio di un acquisto. Ci aspettiamo che tu risponda con un numero di riferimento che identifichi la transazione o l'account. La latenza prevista è < 3 secondi.
Per le transazioni in contanti, il numero di riferimento può essere composto da un massimo di 12 caratteri.
URL: POST https://[your basepath]/v1/generateReferenceNumber
Richiedi 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"
}
JSON risposta
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Java di esempio
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Annulla numero di riferimento
Google può decidere di annullare un numero di riferimento e di impedirne il pagamento da parte dell'utente. Un esempio di caso d'uso è una promozione scaduta. Dopo che avrai risposto positivamente a questa richiesta, dovrai assicurarti che il numero di riferimento non possa essere pagato.
Se l'utente ha già avviato la procedura di pagamento, ad esempio una ricerca del numero di riferimento nel point of sale, il server deve rispondere con una risposta HTTP 423 ed ErrorResponse nel corpo della richiesta con lo stato USER_ACTION_IN_PROGRESS.
URL: POST https://[your basepath]/v1/cancelReferenceNumber
Richiedi 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"
}
JSON risposta
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Una volta accettato il pagamento e completata la transazione, il servizio deve comunicare a Google che la transazione è stata completata e il prodotto deve essere consegnato all'utente. Dopo aver ricevuto questa notifica, Google si aspetta che la transazione sia finalizzata e non prenotabile.
URL dell'endpoint referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Richiedi 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"
}
JSON risposta
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Implement remittance
Once you have integrated the APIs for your particular FOP, you are ready for remittance. Remittance works the same across all FOPs.
remittanceStatementNotification
Two days after a transaction, Google will send a remittanceStatementNotification containing a summary of the transactions Google recorded that day. A sample notification looks like this, two days after a transaction:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Request 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",
}
}
Notice the totalDueByIntegrator mapping. On this line you can see the net amount the Integrator owes (in micros). Also, the date and type of currency appear in this message, with the billing period representing 00:00:00.000 and 23:59:59.999 of the earliest and latest transaction day(s) respectively.
Reconciliation (remittanceStatementDetails)
For reconciliation, the integrator will call remittanceStatementDetails to get the list of events included in the remittanceStatementNotification.
Google responds to the remittanceStatementDetails request with a paginated list of events. remittanceStatementDetails should be called multiple times if the number of total transactions is greater than 1000. The requests do not need to be made sequentially, and can be parallelized.
Request URL
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Sample request body
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Here is a short snippet of a larger response, describing two capture events (transactions).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
See remittanceStatementDetails to learn more.
acceptRemittanceStatement and acceptRemittanceStatementWithModifications
Integrators should compare these events against the events that they have recorded. If any transactions do not match or transactions are missing, contact Google for further investigation. If all transactions match, and the process fee does not include taxes, call acceptRemittanceStatement. If taxes are inclusive, call acceptRemittanceStatementWithModifications.
The acceptRemittanceStatement method is used when there are no taxes on fees.
If a tax is to be included, call acceptRemittanceStatementWithModifications and define the tax rate. If your tax rate changes, make sure this is updated. After a successful acceptRemittanceStatement, initiate your bank transfer to the Google account.
Request URL for acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Sample request body
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Sample response
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
Request URL for acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Sample request body
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Sample response
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}