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
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/
Chemin d'accès de la base de production de Google
https://vgw.googleapis.com/secure-serving/gsp/
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 contenuapplication/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.
|
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.
Exemples
Exemple 1: connexion perdue avant la réception de la réponse
Scénario :
- Google envoie une demande à l'intégrateur.
- Le serveur d'intégration reçoit cette demande et la traite.
- Le serveur de Google est hors tension avant de recevoir la réponse de l'étape 2.
- 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 :
- La base de données du serveur de l'intégrateur est indisponible pour cause de maintenance.
- Google envoie une demande à l'intégrateur.
- L'intégrateur renvoie correctement le code d'état
UNAVAILABLE
. - Le serveur de Google reçoit la réponse et planifie une nouvelle tentative.
- La base de données du serveur de l'intégrateur est de nouveau en ligne.
- 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. - 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 :
- Google envoie une demande à l'intégrateur.
- Le serveur d'intégration reçoit cette demande et la traite.
- Le serveur de Google est hors tension avant de recevoir la réponse de l'étape 2.
- 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.