Normes du protocole

L'API respecte un ensemble de normes d'API HTTP et accepte idempotence afin de favoriser un environnement l'intégration.

URL hébergées par Google

La documentation relative à 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 la version majeure. L'URL complète est créée. en ajoutant le numéro de compte de l'intégrateur de paiement de l'appelant à la fin. Par exemple, la documentation concernant la méthode d'écho hébergée par Google spécifie l'URL:

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

Si le numéro de compte de l'intégrateur de paiement de l'appelant est INTEGRATOR_1, il ajoute à la fin de l'URL pour former:

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

Remarque: La page de documentation des points de terminaison pour la méthode spécifique que vous implémenterez l'URL la plus adaptée à votre cas.

URL hébergées par le partenaire

La documentation relative à 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 la version majeure. Vous ne devez pas inclure le 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 Standard Payments dans le bac à sable (à des fins de développement à des fins de test) et de production. Requêtes dans l'environnement de bac à sable Google n'entraînent aucune responsabilité financière réelle. Le bac à sable et environnements de production sont complètement distincts et ne partagent pas les informations de transaction.

Google s'attend à ce que votre bac à sable soit disponible en permanence, car nous utiliserons dans le bac à sable pour tester 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 qu'elle appelle la méthode https://billpaynotification.sandbox.googleapis.com, vous pouvez continuer le faire. Les nouvelles intégrations doivent appeler le script "vgw.sandbox.google.com" hôte.

Chemin de base pour l'environnement de production de Google

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

Remarque :Si votre intégration est déjà lancée et qu'elle appelle la méthode https://billpaynotification.googleapis.com, vous pouvez continuer de le faire. Les nouvelles intégrations doivent appeler la bibliothèque "vgw.googleapis.com" hôte.

Ce guide utilisera les points de terminaison de production.

Type de contenu et encodage

Les charges utiles de message utilisant le chiffrement PGP doivent utiliser le type de contenu application/octet-stream; charset=utf-8 Les corps de requête PGP être envoyées en utilisant l'encodage base64url, comme défini dans rfc4648 §5. Les charges utiles de message utilisant le chiffrement JWE doivent utiliser le type de contenu application/jose; charset=utf-8 L'option "Sérialisation compacte" pris en charge par JWE/JWS gère l'encodage du corps de la requête finale.

Codes d'état HTTP

Les API Payments 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 à la fois des demandes ayant abouti ou refusé du point de vue de l'entreprise ou logique d'application. Les requêtes qui ne peuvent pas être traitées ne doivent pas entraîner de problème Code d'état HTTP 200, car ils représentent une erreur entre Google et le partenaire. La réponse de l'API doit utiliser l'état HTTP approprié ci-dessous par un objet ErrorResponse facultatif.

Erreurs HTTP et raisons
400	BAD REQUEST Le client a spécifié un argument incorrect. Il peut également être renvoyé si l'opération a été refusée parce que le système n'est pas dans un état requis pour l'exécution de l'opération. Utilisez cette option si les nouvelles tentatives de la requête ne peuvent pas aboutir tant que le système n'est pas à l'état a été explicitement corrigé. Par exemple, si une demande de remboursement échoue pour les raisons suivantes : s'il fait référence à une capture qui n'existe pas, toute nouvelle tentative échouera tant que la capture n'existe pas dans le système d'intégrateur. Remarque:La valeur BAD_REQUEST (400) ne doit pas être utilisée. lorsqu'une erreur d'application appropriée est disponible. Pour Par exemple, des devises incorrectes doivent renvoyer ACCOUNT_DOES_NOT_SUPPORT_CURRENCY par le code 200 si le la réponse standard contient ce champ ou cette énumération.
401	UNAUTHORIZED La requête ne dispose pas d'identifiants d'authentification valides pour opération. Par exemple, des signatures non valides ou inconnues doivent renvoient une erreur 401.
403	FORBIDDEN / PERMISSION DENIED L'appelant n'a pas l'autorisation d'exécuter l'opération spécifiée.
404	NOT FOUND Impossible de trouver une entité demandée (paiement ou utilisateur, par exemple).
409	CONFLICT / ABORTED L'opération a été annulée, généralement en raison d'un problème de simultanéité, tel que échecs de vérification du séquenceur, annulations de transactions, etc.
412	PRECONDITION FAILED Ce code doit être utilisé lorsqu'une clé d'idempotence est réutilisé avec des paramètres différents.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Une ressource 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 est défectueux.
501	UNIMPLEMENTED L'opération n'est ni mise en œuvre, ni compatible, ni activée dans ce service.
503	UNAVAILABLE Le service est actuellement indisponible. Il s'agit très probablement d'un et peut être corrigée en réessayant.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Le délai a expiré avant la fin de l'opération. Pour les opérations modifier l'état du système, cette erreur peut être renvoyée même si le s'est terminée avec succès. Par exemple, une réponse positive d'un serveur aurait pu être retardé suffisamment longtemps pour que le délai arrive à expiration.

Impotence des requêtes

L’idempotence des requêtes est une stratégie centrale utilisée dans les paiements standards API utilisées pour 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 pouvant être envoyés plusieurs fois, mais ont le même effet qu'une seule requête. Cette stratégie facilite la cohérence à terme entre les systèmes en rendant les nouvelles tentatives en toute sécurité, ce qui permet à nos systèmes de fusionner pour s'accorder sur les l'état de la ressource.

Notre API exploite l'idempotence pour:

• réduire les problèmes de rapprochement en facilitant la traçabilité de toutes les actions et vérifiables.
• empêcher les conditions de concurrence en veillant à ce que plusieurs requêtes identiques provenant d'un même client n'entraînent pas un état final différent.
• minimiser l'état en permettant aux requêtes d'être interprétées individuellement, pour améliorer les performances et le débit en supprimant la charge serveur causée par la conservation des données.
• éviter d'avoir à ajouter des champs supplémentaires pour indiquer s'il s'agit d'une nouvelle tentative ;

Remarque :Les résultats d'erreur ne doivent jamais être mis en cache ni renvoyés de manière idempotente. Et les tentatives automatisées en cas d'erreurs doivent utiliser une stratégie d'intervalle exponentiel entre les tentatives.

Exemples

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

Scénario :

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

Résultat :

Dans ce cas, le serveur intégrateur doit répondre avec la même réponse que celle fournie à l'adresse É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 requête à 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 remise en ligne.
6. Google renvoie la demande de l'étape 2 (mêmes ID et détails de la demande). mais a mis à jour requestTimestamp). Notez que les identifiants des deux requêtes doit être identique.
7. Le serveur d'intégration reçoit la requête et renvoie un code d'état OK ainsi que avec une réponse complète.

Résultat :

Dans ce cas, le serveur d'intégration doit traiter la requête à l'étape 7 et ne doit pas renvoient HTTP 503 (UNAVAILABLE). À la place, le serveur d'intégration traiter la demande et renvoyer OK avec le message approprié. Notez que même si le système est UNAVAILABLE. Google peut effectuer des requêtes répétées similaires à l'étape 2. Chaque demande doit entraîner l'affichage d'un message semblable à celui de l'étape 3. Finalement, les étapes 6 et 7 auront lieu.

Exemple 3: Le message faisant l'objet d'une nouvelle tentative ne correspond pas au message initial en raison d'une erreur de récupération

Scénario :

1. Google envoie une requête à l'intégrateur.
2. Le serveur d'intégration reçoit cette requête et la traite correctement.
3. Le serveur de Google n'est plus alimenté en électricité 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 demande mais malheureusement, certains paramètres sont différents.

Résultat :

Dans ce cas, le serveur d'intégration doit répondre avec un code HTTP 412 (PRECONDITION FAILED), ce code d'erreur indique à Google qu'un dans ce système.