Di seguito sono riportati alcuni importanti casi d'uso da prendere in considerazione, nonché le linee guida e le API necessarie per implementare la tua forma di pagamento in contanti.
Casi d'uso
L'API Reference Number può essere utilizzata in vari modi. Questa guida illustra due casi d'uso e ne illustra l'implementazione.
- Contanti: l'utente paga in contanti presso un punto fisico.
- VAN: l'utente trasferisce denaro a un numero di conto virtuale.
Contanti
Un utente può acquistare un prodotto da Google pagandolo in contanti presso un punto fisico, ad esempio un minimarket. Per identificare la transazione, l'utente genera un numero di riferimento da portare in negozio per pagare. Inoltre, Google mostrerà all'utente istruzioni su come completare l'acquisto. Idealmente, non appena l'utente completa l'acquisto, l'integratore invia una notifica a Google in modo che Google possa consegnare il prodotto.
Il tuo punto di contatto Google ti chiederà un esempio delle tue istruzioni di pagamento tipiche. Collaborerai con il tuo contatto Google per ottimizzare e perfezionare i messaggi.
L'esperienza utente che Google vuole fornire è che l'ordine del cliente venga consegnato mentre esce dal negozio. Google si aspetta che la ReferenceNumberPaidNotification venga ricevuta a Google entro tre minuti dal pagamento del numero di riferimento da parte del cliente. Una volta inviato il valore ReferenceNumberPaymentNotification, la transazione non può essere annullata dall'integratore.
VAN
Un utente può pagare per un bene tramite il proprio conto bancario. Google richiederà all'integratore un numero di conto virtuale, che presenterà il numero e le istruzioni all'utente. Oltre all'importo da trasferire, l'utente copierà il numero e lo inserirà nella propria applicazione bancaria.
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 ricevuta la notifica ReferenceNumberPaidNotification, Google consegna il prodotto e la transazione non può 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.
Seguire un comportamento idempotente
Idempotency significa che non devi tentare di rielaborare richieste (ad esempio un pagamento) che sono già state elaborate correttamente. La risposta per l'elaborazione corretta dovrebbe essere invece registrata.
Perché è importante
Google potrebbe ritentare alcune richieste per assicurarsi che lo stato da parte nostra corrisponda a quello del fornitore. Il tuo sistema non deve considerare che si tratta 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 Idempotency
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 prima risposta fosse 200 (Successo), Google si aspetta la stessa risposta con un timestamp diverso.
Se la risposta precedente era un errore (400 o 500 e così via), dovrai elaborare la richiesta come nuova richiesta e ricontrollarla. Ciò è utile se il server non era attivo la prima volta e, eseguendo un nuovo tentativo, hai un'altra possibilità che la richiesta venga elaborata correttamente.
Per saperne di più, consulta questa guida dettagliata.
Utilizzare l'ID account di integrazione dei 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. Per rappresentare ciascuna di queste configurazioni, saranno coinvolti account commerciante diversi.
Per la mappatura di ogni entità di Google a ciascun account commerciante, Google fornisce gli ID account di integrazione dei pagamenti (PIAID). Per un esempio dell'API della forma di pagamento contanti, consulta generateReferenceNumber. Ecco un esempio che utilizza questa mappatura.
Per la mappatura di ogni entità di Google a ciascun account commerciante, Google fornisce gli ID account di integrazione dei pagamenti (PIAID). Per un esempio di utilizzo dell'API della forma di pagamento per 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 i paymentIntegratorAccountId forniti dal tuo punto di contatto presso Google e il tuo account commerciante.
L'integratore può anche avere account diversi a seconda del paese servito. Ciò può essere dovuto a varie 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 API seguenti gestiscono la generazione del numero di riferimento e la notifica di pagamento.
Le API seguenti gestiscono versamenti e liquidazioni.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AccettaRemittanceStatement con modifiche
Per generare numeri di riferimento e saldare con Google, dovrai integrare tutte le API indicate sopra.
Genera numero di riferimento
Google chiama GeneraReferenceNumber quando avvii un acquisto. Dovresti rispondere con un numero di riferimento che identifichi la transazione o l'account. La latenza prevista è inferiore a 3 secondi.
Per le transazioni in contanti, il numero di riferimento può contenere fino a 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 impedirne il pagamento da parte dell'utente. Un esempio di caso d'uso è una promozione scaduta. Una volta che la tua richiesta è andata a buon fine, devi assicurarti che non sia possibile pagare il numero di riferimento.
Se l'utente ha già avviato il processo di pagamento, ad esempio una ricerca del numero di riferimento dal 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 informare Google che la transazione è stata completata e consegnare il prodotto all'utente. Dopo aver ricevuto questa notifica, Google prevede che la transazione sia stata finalizzata e non sia 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, puoi effettuare il pagamento. Il metodo di pagamento funziona allo stesso modo per tutte le forme di pagamento.
remittanceStatementNotification
Due giorni dopo una transazione, Google invia una remittanceStatementNotification contenente un riepilogo delle transazioni registrate da Google quel giorno. Due giorni dopo una transazione, vedrai una notifica di esempio simile alla seguente:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Richiedi 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",
}
}
Osserva la mappatura totalDueByIntegrator. Su questa riga puoi vedere l'importo netto dovuto dall'integratore (in micro). Inoltre, la data e il tipo di valuta vengono visualizzati in questo messaggio e il periodo di fatturazione rappresenta rispettivamente 00:00:00, 000 e 23:59:59.999 dei giorni delle transazioni più recenti e precedenti.
Riconciliazione (remittanceStatementDetails)
Per la riconciliazione, l'integratore chiamerà remittanceStatementDetails per ottenere l'elenco degli eventi inclusi nella remittanceStatementNotification.
Google risponde alla richiesta remittanceStatementDetails con un elenco impaginato di eventi. remittanceStatementDetails deve essere chiamato più volte se il numero totale di transazioni è 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
}
Di seguito è riportato un breve snippet di una risposta più ampia, 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 saperne di più, visita la pagina remittanceStatementDetails.
acceptRemittanceStatement e acceptRemittanceStatementWithModifications
Gli integratori dovrebbero confrontare questi eventi con quelli che hanno registrato. Se alcune transazioni non corrispondono o mancano delle transazioni, contatta Google per ulteriori indagini. Se tutte le transazioni corrispondono e la commissione di elaborazione non include le imposte, chiama acceptRemittanceStatement. Se le tasse sono comprensive, chiama il numero acceptRemittanceStatementWithModifications.
Se non vengono applicate imposte sulle commissioni, viene utilizzato il metodo acceptRemittanceStatement.
Se devi includere una tassa, chiama acceptRemittanceStatementWithModifications e indica l'aliquota fiscale. Se l'aliquota fiscale cambia, assicurati che sia aggiornata. Dopo aver eseguito correttamente la procedura di acceptRemittanceStatement, avvia il bonifico bancario sul tuo Account Google.
URL della richiesta per acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Esempio di corpo della richiesta
{
"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
Esempio di corpo della richiesta
{
"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"
}