Voici quelques cas d'utilisation importants à prendre en compte, ainsi que les consignes et les API nécessaires pour implémenter votre mode de paiement en espèces.
Cas d'utilisation
L'API Reference Number peut être utilisée à diverses fins. Ce guide présente deux cas d'utilisation et vous guide tout au long de leur implémentation.
- Espèces : l'utilisateur paie en espèces dans un magasin physique.
- VAN : l'utilisateur transfère de l'argent vers un numéro de compte virtuel.
Espèces
Un utilisateur peut effectuer un achat auprès de Google en le payant en espèces dans un établissement physique tel qu'une supérette. Pour identifier la transaction, l'utilisateur génère un numéro de référence à présenter au magasin pour payer. En outre, Google affichera à l'utilisateur des instructions sur la manière de finaliser l'achat. Idéalement, dès que l'utilisateur a effectué l'achat, l'intégrateur en informe Google afin que Google puisse livrer le produit.
Votre contact Google vous demandera un échantillon des instructions de paiement habituelles. Vous collaborerez avec votre contact Google pour optimiser et affiner le message.
L'expérience utilisateur que Google souhaite offrir au client est que la commande est livrée au moment où il quitte le magasin. La notification ReferenceNumberPaidNotification doit être reçue par Google dans les trois minutes suivant le paiement du numéro de référence par le client. Une fois que la valeur ReferenceNumberDeNotification a été envoyée, la transaction ne peut pas être annulée par l'intégrateur.
VAN
Un utilisateur peut payer un produit avec son compte bancaire. Google demandera un numéro de compte virtuel à l'intégrateur, en présentant le numéro et les instructions à l'utilisateur. L'utilisateur doit ensuite copier le numéro et le saisir dans son application bancaire en plus du montant à transférer.
L'intégrateur doit vérifier que le montant transféré correspond au montant de la demande referenceNumberGeneration, puis informer Google que le numéro de référence a été payé.
Une fois que Google reçoit la ReferenceNumberPaidNotification, il livre le produit et la transaction ne peut pas être annulée par l'intégrateur.
l'envoi de messages entre vos serveurs et les serveurs de Google ;
Vous devez respecter les présentes consignes lorsque vous envoyez des messages entre vos serveurs et les serveurs de Google, et inversement.
Demande entrante – DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Réponse sortante - Base64UrlEncode(EncryptWithGooglePublicKey(request))
Demande Google – Base64UrlEncode(EncryptWithGooglePublicKey(request))
Réponse de Google : DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Voici une bibliothèque et un exemple PGP en Java qui montrent comment gérer les requêtes et les réponses.
Suivre un comportement idempotent
L’idempotence signifie que vous ne devez pas tenter de traiter à nouveau une demande (telle qu’un paiement) qui a déjà été traitée avec succès. La réponse indiquant que le traitement a réussi doit être indiquée à la place.
Pourquoi cette fonctionnalité est-elle importante ?
Google peut relancer certaines requêtes pour s'assurer que l'État de notre côté est identique à l'État côté fournisseur. Votre système ne doit pas considérer qu'il s'agit d'une autre transaction. Par conséquent, l'idempotence est très importante. Cela signifie qu'un intégrateur ne doit pas traiter à nouveau un élément qui a déjà été traité correctement. Dans ce cas, la réponse précédente doit être envoyée à la place.
Comment implémenter l'idempotence
Si Google envoie une nouvelle tentative, l'ID de requête sera le même et le contenu sera le même, mais le code temporel sera différent. Répondez de la même manière que précédemment. Si votre première réponse était un 200 (Opération réussie), Google s'attendrait à la même réponse avec un code temporel différent.
Si votre réponse précédente était une erreur (400 ou 500, etc.), vous devez traiter cette demande en tant que nouvelle demande, en la vérifiant à nouveau. Cela s'avère utile si votre serveur était en panne la première fois et qu'une nouvelle tentative donne à la requête une autre chance d'être traitée correctement.
Pour en savoir plus, consultez ce guide détaillé.
Utiliser l'ID de compte de l'intégrateur de paiement (PIAID)
Les intégrations à Google peuvent nécessiter une intégration aux différentes entités commerciales de Google. Par exemple, Google Play est une entité, YouTube et Google Ads. Différents comptes marchands seront impliqués pour représenter chacune de ces configurations.
Pour le mappage entre chaque entité de Google et chaque compte marchand, Google fournit des ID de compte d'intégrateur de paiement (PIAID). Pour obtenir un exemple d'API de paiement en espèces, consultez generateReferenceNumber. Voici un exemple qui utilise ce mappage.
Pour le mappage entre chaque entité de Google et chaque compte marchand, Google fournit des ID de compte d'intégrateur de paiement (PIAID). Pour obtenir un exemple d'utilisation de l'API de paiement en espèces, consultez generateReferenceNumber. Voici un exemple qui utilise ce mappage.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Notez la partie en surbrillance. Les deux valeurs requises ici sont les paymentIntegratorAccountId fournies par votre contact Google et votre compte marchand.
L'intégrateur peut également disposer de différents comptes en fonction de chaque pays desservi. Cela peut s'expliquer par différentes réglementations fiscales et d'autres différences d'un pays à l'autre. Dans ce cas, un autre PIAID peut être généré pour chaque pays.
API à intégrer
Les API suivantes gèrent la génération des numéros de référence et les notifications de paiement.
Les API suivantes gèrent les versements et les règlements.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement avec des modifications
Vous devrez intégrer toutes les API ci-dessus pour générer des numéros de référence et vous mettre d'accord avec Google.
Générer un numéro de référence
Google appelle GenerateReferenceNumber lorsque vous effectuez un achat. Nous attendons de votre réponse que vous nous fournissiez un numéro de référence identifiant la transaction ou le compte. La latence attendue est < 3 secondes
Pour les transactions en espèces, le numéro de référence peut comporter jusqu'à 12 caractères.
URL: POST https://[your basepath]/v1/generateReferenceNumber
Requête 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"
}
Réponse JSON
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Exemple de code Java
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Annuler le numéro de référence
Google peut décider d'annuler un numéro de référence et d'empêcher le paiement de celui-ci par l'utilisateur. Par exemple, une promotion a expiré. Une fois que votre réponse a abouti, vous devez vous assurer que le numéro de référence ne peut pas être payé.
Si l'utilisateur a déjà lancé le processus de paiement, par exemple en recherchant le numéro de référence depuis le point de vente, votre serveur doit renvoyer une réponse HTTP 423 et une réponse ErrorResponse dans le corps de la requête avec l'état USER_ACTION_IN_PROGRESS.
URL: POST https://[your basepath]/v1/cancelReferenceNumber
Requête 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"
}
Réponse JSON
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Une fois le paiement accepté et la transaction effectuée, votre service doit avertir Google que la transaction est terminée et livrer le produit à l'utilisateur. Une fois cette notification reçue par Google, Google s'attend à ce que la transaction soit finalisée et ne peut pas faire l'objet d'une réservation.
URL du point de terminaison referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Requête 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"
}
Réponse JSON
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Implémenter la remise
Une fois que vous avez intégré les API pour votre mode de paiement spécifique, vous êtes prêt à envoyer des fonds. Les remises fonctionnent de la même manière pour tous les FOP.
remittanceStatementNotification
Deux jours après une transaction, Google envoie une notification remittanceStatementNotification contenant un résumé des transactions enregistrées par Google ce jour-là. Voici un exemple de notification deux jours après une transaction:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Requête 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",
}
}
Notez le mappage totalDueByIntegrator. Sur cette ligne, vous pouvez voir le montant net que l'intégrateur doit (en micros). La date et le type de devise apparaissent également dans ce message. La période de facturation correspond aux valeurs 00:00:00.000 et 23:59:59.999 du ou des jours de transaction les plus anciens et les plus récents, respectivement.
Rapprochement (remittanceStatementDetails)
Pour le rapprochement, l'intégrateur appelle remittanceStatementDetails pour obtenir la liste des événements inclus dans remittanceStatementNotification.
Google répond à la requête remittanceStatementDetails avec une liste d'événements paginée. remittanceStatementDetails doit être appelé plusieurs fois si le nombre total de transactions est supérieur à 1 000. Les requêtes n'ont pas besoin d'être effectuées de manière séquentielle et peuvent être parallélisées.
Request URL
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Exemple de corps de requête
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Voici un court extrait d'une réponse plus longue, décrivant deux événements de capture (transactions).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Pour en savoir plus, consultez remittanceStatementDetails.
acceptRemittanceStatement et acceptRemittanceStatementWithModifications
Les intégrateurs doivent comparer ces événements aux événements qu'ils ont enregistrés. Si des transactions ne correspondent pas ou sont manquantes, contactez Google pour une analyse approfondie. Si toutes les transactions correspondent et que les frais de traitement n'incluent pas les taxes, appelez acceptRemittanceStatement. Si les taxes sont comprises, appelez acceptRemittanceStatementWithModifications.
La méthode acceptRemittanceStatement est utilisée lorsqu'il n'y a pas de taxes sur les frais.
Si une taxe doit être incluse, appelez acceptRemittanceStatementWithModifications et définissez le taux de taxe. Si votre taux de taxe change, assurez-vous qu'il est à jour. Une fois la acceptRemittanceStatement effectuée, lancez le transfert bancaire vers le compte Google.
URL de requête pour acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Exemple de corps de requête
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Exemple de réponse
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
URL de requête pour acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Exemple de corps de requête
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Exemple de réponse
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}