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 a plusieurs utilités. Ce guide présente deux cas d'utilisation et vous explique leur mise en œuvre.
- Espèces : l'utilisateur paie en espèces dans un établissement physique.
- VAN : l'utilisateur transfère de l'argent vers un numéro de compte virtuel.
Espèces
Un utilisateur peut acheter un produit 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 qu'il peut apporter au magasin pour payer. En outre, Google affichera des instructions indiquant à l'utilisateur comment finaliser l'achat. Dans l'idéal, dès que l'utilisateur effectue l'achat, l'intégrateur en informe Google afin que Google puisse fournir le produit.
Votre point de contact chez Google vous demandera un échantillon de vos instructions de paiement habituelles. Vous travaillerez avec votre contact Google pour optimiser et affiner votre message.
L'expérience utilisateur que Google souhaite offrir est la livraison de la commande du client lorsqu'il quitte le magasin. Google s'attend à recevoir la notification ReferenceNumberPaidNotification dans un délai de trois minutes à compter de la date à laquelle le client a payé le numéro de référence. Une fois la référence ReferenceNumberpaidNotification envoyée, l'intégrateur ne peut plus annuler la transaction.
VAN
Un utilisateur peut payer un bien avec son compte bancaire. Google demandera un numéro de compte virtuel à l'intégrateur, en présentant ce numéro et les instructions à l'utilisateur. L'utilisateur copiera ensuite ce numéro et le saisira 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 notification ReferenceNumberPaidNotification, il fournit le produit. L'intégrateur ne peut pas annuler la transaction.
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 (un paiement, par exemple) qui a déjà été traitée avec succès. La réponse en cas de réussite du traitement doit être indiquée à la place.
Pourquoi cette fonctionnalité est-elle importante ?
Google peut relancer certaines demandes pour s'assurer que l'état de notre côté est identique à celui du 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 retraiter un élément déjà traité avec succès. Dans ce cas, la réponse précédente doit être envoyée à la place.
Implémentation de l'idempotence
Si Google envoie une nouvelle tentative, l'ID de la requête sera le même et le contenu sera identique, mais le code temporel sera différent. Répondez en utilisant la même réponse que celle envoyée précédemment. Si votre première réponse était 200 (réussite), Google s'attendrait à recevoir 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 comme une nouvelle demande, en la vérifiant à nouveau. Cela est utile si votre serveur est tombé en panne la première fois et qu'une nouvelle tentative donne une autre chance à la requête 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)
L'intégration à Google peut nécessiter d'intégrer les différentes entités commerciales de Google. Par exemple, Google Play est une entité, YouTube et Google Ads. Chacune de ces configurations sera représentée par différents comptes marchands.
Pour la mise en correspondance de chaque entité au sein de Google avec chaque compte marchand, Google fournit des ID de compte d'intégrateur de paiements (PIAID). Pour obtenir un exemple de l'API de mode de paiement en espèces, consultez la page generateReferenceNumber. Voici un exemple qui utilise ce mappage.
Pour la mise en correspondance de chaque entité au sein de Google avec chaque compte marchand, Google fournit des ID de compte d'intégrateur de paiements (PIAID). Pour voir un exemple d'utilisation de l'API de mode de paiement en espèces, accédez à 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 mise en surbrillance. Les deux valeurs nécessaires ici sont les paymentIntegratorAccountId fournies par votre contact Google et votre compte marchand.
L'intégrateur peut également disposer de comptes différents en fonction du pays desservi. Cela peut être dû à différentes lois 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 procéder à un règlement avec Google.
Générer un numéro de référence
Google appelle GenerateReferenceNumber lorsque vous effectuez un achat. Nous attendons de vous que vous nous répondiez en fournissant un numéro de référence permettant d'identifier la transaction ou le compte. La latence attendue est inférieure à trois 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 choisir d'annuler un numéro de référence et d'empêcher l'utilisateur de le payer. Un exemple de cas d'utilisation est une promotion qui a expiré. Une fois que votre demande aura 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 un numéro de référence sur le point de vente), votre serveur doit renvoyer une réponse HTTP 423 et une erreur "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 terminée, votre service doit informer Google que la transaction est terminée et que le produit est livré à l'utilisateur. Après réception de cette notification, Google s'attend à ce que la transaction soit finalisée et ne puisse 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"
}
Mettre en œuvre le versement
Une fois que vous avez intégré les API pour votre mode de paiement, vous pouvez procéder au versement. Le versement s'effectue de la même manière sur tous les modes de paiement.
remittanceStatementNotification
Deux jours après une transaction, Google envoie une notification remittanceStatementNotification contenant un récapitulatif des transactions enregistrées 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 dû par l'intégrateur (en micros). De plus, la date et le type de devise apparaissent dans ce message, la période de facturation représentant respectivement 00:00:00.000 et 23:59:59.999 du ou des jours de transaction les plus anciens et les plus récents.
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 paginée d'événements. 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 chargées en parallèle.
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 volumineuse, 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 certaines transactions ne correspondent pas ou si des transactions sont manquantes, contactez Google pour étudier le problème. Si toutes les transactions correspondent et que les frais de traitement n'incluent pas les taxes, appelez le acceptRemittanceStatement. Si les taxes sont inclusives, appelez le 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 de le mettre à jour. Après un acceptRemittanceStatement réussi, effectuez votre virement bancaire vers le compte Google.
URL de la 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 la 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"
}