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"
}
Implementa il versamento
Una volta integrate le API per la forma di pagamento specifica, è tutto pronto per il versamento. Il versamento funziona allo stesso modo in tutti i FOP.
remittanceStatementNotification
Due giorni dopo una transazione, Google invia una remittanceStatementNotification contenente un riepilogo delle transazioni registrate da Google quel giorno. Ecco una notifica di esempio, due giorni dopo una transazione:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
JSON richiesta
{
"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",
}
}
Nota la mappatura di totalDueByIntegrator. In questa riga puoi vedere l'importo netto dovuto dall'integratore (in micro). Inoltre, in questo messaggio vengono visualizzate la data e il tipo di valuta, con il periodo di fatturazione che rappresenta rispettivamente 00:00:00.000 e 23:59:59.999 dei giorni di transazione iniziali e finali.
Riconciliazione (remittanceStatementDetails)
Per la riconciliazione, l'integratore chiamerà remittanceStatementDetails per ottenere l'elenco degli eventi inclusi nella notifica remittanceStatement.
Google risponde alla richiesta remittanceStatementDetails con un elenco di eventi paginato. remittanceStatementDetails deve essere chiamato più volte se il numero di transazioni totali è maggiore di 1000. Le richieste non devono essere effettuate in sequenza e possono essere parallelizzate.
URL richiesta
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Esempio di corpo della richiesta
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Ecco un breve snippet di una risposta più grande, che descrive due eventi di acquisizione (transazioni).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Per scoprire di più, visita la pagina remittanceStatementDetails.
acceptRemittanceStatement e acceptRemittanceStatementWithModifications
Gli integratori devono confrontare questi eventi con quelli che hanno registrato. Se alcune transazioni non corrispondono o se mancano transazioni, contatta Google per ulteriori indagini. Se tutte le transazioni corrispondono e la commissione di elaborazione non include le imposte, chiama il numero acceptRemittanceStatement. Se le tasse sono comprensive, chiama il numero acceptRemittanceStatementWithModifications.
Il metodo acceptRemittanceStatement viene utilizzato quando non sono previste imposte sulle commissioni.
Se vuoi includere una tassa, chiama il numero acceptRemittanceStatementWithModifications e definisci l'aliquota fiscale. Se l'aliquota fiscale cambia, assicurati che sia aggiornata. Dopo aver completato la transazione acceptRemittanceStatement, avvia il trasferimento bancario all'Account Google.
URL della richiesta per acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Corpo della richiesta di esempio
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Esempio di risposta
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
URL della richiesta per acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Corpo della richiesta di esempio
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Esempio di risposta
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}