Normes du protocole

L'API suit un ensemble de normes d'API HTTP et prend en charge l'idempotence pour faciliter une intégration plus robuste.

URL hébergées par Google

La documentation de chaque méthode hébergée par Google fournit une URL de base, qui inclut le nom de la méthode et le numéro de version majeure. L'URL complète est créée en ajoutant à la fin l'ID de compte de l'intégrateur de paiement de l'appelant. Par exemple, la documentation de la méthode echo hébergée par Google spécifie l'URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Si l'ID du compte de l'intégrateur de paiement de l'appelant est INTEGRATOR_1, il doit l'ajouter à la fin de l'URL pour remplir ce formulaire:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Remarque :La page de documentation des points de terminaison pour la méthode que vous implémentez comportera l'URL la plus précise pour votre demande.

URL hébergées par le partenaire

La documentation de chaque méthode d'API hébergée par un partenaire fournit une URL de base, qui inclut le nom de la méthode et le numéro de version majeure. Vous ne devez pas inclure l'ID de compte de l'intégrateur de paiement (PIAID) dans les URL que vous hébergez.

Environnements de bac à sable et de production

Google héberge les API de paiement standards à la fois en bac à sable (à des fins de développement et de test) et en production. Les demandes effectuées dans l'environnement de bac à sable Google n'entraînent aucune responsabilité financière réelle. Les environnements de bac à sable et de production sont complètement distincts et ne partagent aucune clé ni information sur les transactions.

Google s'attend à ce que votre bac à sable soit toujours disponible, car nous l'utiliserons pour tester d'abord les modifications et les nouvelles fonctionnalités.

Chemin de base du bac à sable de Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Remarque :Si votre intégration est déjà lancée et appelle l'hôte https://billpaynotification.sandbox.googleapis.com, vous pouvez continuer à le faire. Les nouvelles intégrations doivent appeler l'hôte "vgw.sandbox.google.com".

Chemin d'accès de la base de production de Google

https://vgw.googleapis.com/secure-serving/gsp/

Remarque :Si votre intégration est déjà lancée et appelle l'hôte https://billpaynotification.googleapis.com, vous pouvez continuer à le faire. Les nouvelles intégrations doivent appeler l'hôte "vgw.googleapis.com".

Ce guide utilise les points de terminaison de production.

Type de contenu et encodage

Les charges utiles de message qui utilisent le chiffrement PGP doivent utiliser le type de contenu application/octet-stream; charset=utf-8. Le corps des requêtes PGP doit être envoyé en utilisant l'encodage base64url, tel que défini dans le rfc4648 §5. Les charges utiles de message qui utilisent le chiffrement JWE doivent utiliser le type de contenu application/jose; charset=utf-8. L'option de sérialisation compacte compatible avec JWE/JWS gère l'encodage pour le corps de la requête finale.

Codes d'état HTTP

Les API de paiement standards sont conçues pour renvoyer un code d'état HTTP 200 pour toutes les requêtes pouvant être traitées par le serveur. Cela inclut les requêtes réussies et refusées du point de vue de la logique métier ou d'application. Les requêtes qui ne peuvent pas être traitées ne doivent pas renvoyer de code d'état HTTP 200, car elles représentent une erreur entre Google et le partenaire. À la place, la réponse de l'API doit utiliser les codes d'état HTTP appropriés ci-dessous, avec un objet ErrorResponse facultatif.

Erreurs et motifs HTTP
400	BAD REQUEST Le client a spécifié un argument incorrect. Cette valeur peut également être renvoyée si l'opération a été refusée, car le système n'est pas dans un état requis pour l'exécuter. Utilisez cette option si les nouvelles tentatives de la requête ne peuvent pas aboutir tant que l'état du système n'a pas été explicitement corrigé. Par exemple, si une demande de remboursement échoue parce qu'elle fait référence à une capture qui n'existe pas, la nouvelle tentative n'aboutit pas tant que la capture n'existe pas dans le système d'intégrateurs. Remarque:BAD_REQUEST (400) ne doit pas être utilisé lorsqu'une erreur d'application appropriée est disponible. Par exemple, les devises incorrectes doivent renvoyer ACCOUNT_DOES_NOT_SUPPORT_CURRENCY avec le code 200 si la réponse standard comporte ce champ ou cette énumération.
401	UNAUTHORIZED La requête ne dispose pas d'identifiants d'authentification valides pour l'opération. Par exemple, les signatures non valides ou inconnues doivent renvoyer le code d'état 401.
403	FORBIDDEN / PERMISSION DENIED L'appelant n'a pas l'autorisation d'exécuter l'opération spécifiée.
404	NOT FOUND L'entité demandée, telle que paiement ou utilisateur, est introuvable.
409	CONFLICT / ABORTED L'opération a été annulée, généralement en raison d'un problème de simultanéité tel que des échecs de vérification du séquenceur, des annulations de transactions, etc.
412	PRECONDITION FAILED Ce code doit être utilisé dans les situations où une clé d'idempotence est réutilisée avec différents paramètres.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Une partie des ressources système est épuisée.
499	CANCELLED L'opération a été annulée (généralement par l'appelant).
500	INTERNAL ERROR Erreurs internes. Cela signifie que certaines invariantes attendues par le système sous-jacent ne fonctionnent pas.
501	UNIMPLEMENTED L'opération n'est pas implémentée, prise en charge ou activée dans ce service.
503	UNAVAILABLE Le service est actuellement indisponible. Il s'agit d'un état très probablement temporaire qui peut être corrigé par une nouvelle tentative.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Le délai a expiré avant la fin de l'opération. Pour les opérations qui modifient l'état du système, cette erreur peut être renvoyée même si l'opération a abouti. Par exemple, une réponse réussie d'un serveur aurait pu être retardée suffisamment longtemps pour que le délai expire.

idempotence de la requête

L'idempotence des requêtes est une stratégie centrale utilisée dans les API de paiement standards. Elle permet de garantir que les interactions système entre Google et les partenaires sont robustes et tolérantes aux pannes. Les requêtes idempotentes sont des requêtes qui peuvent éventuellement être envoyées plusieurs fois, mais qui ont le même effet qu'une seule requête. Cette stratégie facilite la cohérence à terme entre les systèmes en sécurisant les nouvelles tentatives, ce qui permet à nos systèmes de se fondre pour s'accorder sur l'état de la ressource.

Notre API exploite l'idempotence pour:

• réduire les problèmes de rapprochement en facilitant la traçabilité et l'audit de toutes les actions.
• d'éviter les conditions de concurrence en garantissant que plusieurs requêtes identiques provenant du même client n'entraînent pas un état final différent ;
• Minimiser l'état en permettant la compréhension des requêtes de manière isolée, ce qui permet d'améliorer les performances et le débit en supprimant la charge du serveur causée par la conservation des données.
• éviter d'avoir à ajouter des champs pour indiquer si une requête est une nouvelle tentative.

Remarque :Les résultats d'erreur ne doivent jamais être mis en cache ni renvoyés idempotentement. En outre, les nouvelles tentatives automatisées en cas d'erreur doivent utiliser une stratégie d'intervalle exponentiel entre les tentatives.

Exemples

Exemple 1: connexion perdue avant la réception de la réponse

Scénario :

1. Google envoie une demande à l'intégrateur.
2. Le serveur d'intégration reçoit cette demande et la traite.
3. Le serveur de Google est hors tension avant de recevoir la réponse de l'étape 2.
4. L'alimentation du serveur de Google est restaurée, et la même requête est envoyée avec les mêmes paramètres (même ID de requête et détails de la requête, mais mise à jour de requestTimestamp) au serveur de l'intégrateur.

Résultat :

Dans ce cas, le serveur d'intégrateur doit répondre de la même manière qu'à l'étape 2, car tous les paramètres, à l'exception de responseTimestamp, sont identiques. L'effet secondaire ne se produit qu'une seule fois, à l'étape 2. L'étape 4 n'a aucun effet secondaire.

Exemple 2: Requête envoyée à un serveur en cours de maintenance

Scénario :

1. La base de données du serveur de l'intégrateur est indisponible pour cause de maintenance.
2. Google envoie une demande à l'intégrateur.
3. L'intégrateur renvoie correctement le code d'état UNAVAILABLE.
4. Le serveur de Google reçoit la réponse et planifie une nouvelle tentative.
5. La base de données du serveur de l'intégrateur est de nouveau en ligne.
6. Google renvoie la requête de l'étape 2 (même ID et détails de la requête, mais requestTimestamp mis à jour). Notez que les ID des deux requêtes doivent être identiques.
7. Le serveur d'intégrateur reçoit la requête et renvoie un code d'état OK avec la réponse complète.

Résultat :

Dans ce cas, le serveur d'intégrateur doit traiter la requête présentée à l'étape 7 et ne pas renvoyer le code HTTP 503 (UNAVAILABLE). Il doit traiter entièrement la requête et renvoyer un message approprié avec les messages appropriés. Notez que même si le système est défini sur UNAVAILABLE, Google peut envoyer des requêtes répétées semblables à l'étape 2. Chaque requête doit renvoyer un message semblable à celui de l'étape 3. Les étapes 6 et 7 auront lieu.

Exemple 3: Le message relancé ne correspond pas au message initial en raison d'une erreur de récupération

Scénario :

1. Google envoie une demande à l'intégrateur.
2. Le serveur d'intégration reçoit cette demande et la traite.
3. Le serveur de Google est hors tension avant de recevoir la réponse de l'étape 2.
4. L'alimentation du serveur de Google est rétablie et tente d'envoyer la même requête, mais malheureusement certains paramètres sont différents.

Résultat :

Dans ce cas, le serveur d'intégrateur doit répondre par un code d'erreur HTTP 412 (PRECONDITION FAILED) qui indique à Google qu'il y a une erreur dans ce système.