Verser des fonds pour créditer des comptes clients
Assurez-vous de configurer votre compte API Amazon Incentives avant de commencer l’intégration. Créer un compte API Incentives.
Le service Web Connexion et réception fournit une API permettant de verser des fonds à un client Amazon nouveau ou existant. Grâce à ce versement, le compte du client Amazon reçoit en temps réel une valeur monétaire sur son solde de chèque-cadeau. Ce service Web basé sur REST fait partie de l’API Incentives, qui offre un ensemble de services prenant en charge les opérations pour les chèques-cadeaux Amazon.
Appelez l’API Connexion et réception pour les cas d’utilisation suivants :
- Vous avez besoin de versements immédiats et garantis de devises à vos clients via une application Web.
- Vous devez vous assurer que la valeur monétaire n’est pas transférable pour satisfaire à vos obligations légales ou commerciales.
- Vous souhaitez envoyer une notification par e-mail aux clients pour les informer d’un événement de versement.
Cette page explique comment appeler l’API Connexion et réception à partir de votre application et documente les tâches que vous pouvez effectuer avec cette API.
- Concepts clés et flux de base
- Prérequis
- API Connexion et réception
- Test des demandes
- Script de test Connexion et réception
- Performances
- Codes d’erreur
Concepts clés et flux de base
L’API Connexion et réception utilise le service Web Connexion avec Amazon qui permet aux utilisateurs d’authentifier leur compte Amazon avec leurs informations d’identification de compte Amazon dans leur navigateur ou leur application mobile. Une fois l’authentification terminée, le service Connexion avec Amazon fournit à votre application un identifiant d’utilisateur qui vous servira de paramètre d’entrée pour l’API Connexion et réception. Ces services combinés offrent une expérience transparente aux utilisateurs finaux.
Connexion avec Amazon propose des personnalisations pour s’aligner sur votre expérience utilisateur préférée, y compris un SDK. Pour plus d’informations, consultez la page relative à la connexion avec Amazon sur le portail des développeurs.
Vous trouverez ci-dessous une description du processus de l’application pour l’API Connexion et réception :
- Un utilisateur de l’application demande de créditer le solde de chèque-cadeau de son compte Amazon.
- Dans l’application, une page s’affiche dans le module Connexion avec Amazon invitant l’utilisateur à fournir ses informations d’identification Amazon.
- Les nouveaux clients Amazon peuvent créer un compte via le processus Connexion avec Amazon.
- Si votre code requiert le nom, l’adresse e-mail ou le code postal du client Amazon, le processus Connexion avec Amazon demande le consentement du client pour partager ces informations avec votre service.
- Le module lance une demande d’autorisation à l’aide de l’API Connexion avec Amazon.
- Une valeur id qui identifie de manière unique le compte utilisateur est renvoyée en tant qu’objet JSON dans la réponse.
- Votre application appelle la méthode LoadAmazonBalance en incluant la valeur id dans le corps de la requête.
- L’opération LoadAmazonBalance met à jour le solde de chèque-cadeau du compte.
- Amazon envoie un e-mail de confirmation à l’adresse e-mail associée au compte client Amazon après versement ou annulation des fonds sur le solde de chèque-cadeau du compte client. Cet e-mail contiendra le texte spécifié dans le paramètre notificationMessage de la demande LoadAmazonBalance.
Remarques :
- L’utilisateur peut interrompre le processus Connexion avec Amazon à tout moment en sélectionnant Annuler ou en fermant la fenêtre contextuelle (si cette méthode est utilisée).
- Le stockage des informations d’identification personnelles, y compris le nom, l’adresse e-mail et le code postal, nécessitera la mise en place de mesures de sécurité supplémentaires à des fins de conformité avec le RGDP, le CCPA et d’autres lois sur la protection de la vie privée.
Prérequis
Pour utiliser l’API Connexion et réception, procédez comme suit :
- Suivez les instructions du guide de configuration pour l’intégration de l’API Incentives afin de créer un compte et d’accepter le contrat avec Amazon Incentives.
- Intégrez votre application Web ou mobile au service Web Connexion avec Amazon pour fournir l’authentification et éventuellement l’accès aux données des profils d’utilisateurs. Pour en savoir plus sur l’intégration de votre application à Connexion avec Amazon, suivez les étapes décrites sur le centre des développeurs Amazon pour accéder au module Connexion avec Amazon. Remarque : pour utiliser Connexion avec Amazon dans votre application mobile, vous devez utiliser le SDK Connexion avec Amazon mobile. Bien qu’une interaction basée sur un navigateur soit techniquement possible à partir d’une application mobile, nous l’interdisons pour des raisons de sécurité.
- Vous utiliserez l’environnement de test sandbox lors du développement et du test de votre application. Contactez votre responsable de compte Amazon pour obtenir vos informations d’identification et d’accès à l’environnement sandbox. Une fois l’accès à l’environnement sandbox octroyé, vous pourrez commencer le développement et le test à l’aide de votre ID de partenaire. Les URL de base des points de terminaison permettant d’accéder à l’environnement sandbox sont fournies dans la section Régions et points de terminaison. Dans un environnement sandbox, vous pouvez développer et tester votre code en suivant les instructions du guide de configuration pour l’intégration de l’API Incentives d’Amazon.
API Connexion et réception
Votre application interagit avec l’API Connexion et réception en envoyant des demandes synchrones au service Web. Cette section décrit la structure d’une demande et les opérations disponibles. L’appel d’une opération consiste à envoyer une demande HTTP à un point de terminaison de l’API Incentives et à attendre la réponse. Une demande HTTP REST à la passerelle contient une méthode de demande, un URI, des en-têtes et un corps présenté au format XML ou JSON. La réponse contient un code de statut HTTP, des en-têtes de réponse et un corps de réponse. Chaque appel d’API devra être signé à l’aide de vos informations d’identification de sécurité et selon le processus de signature d’AWS Signature Version 4.
Vous trouverez ci-dessous une description de chaque opération d’API, des en-têtes de demande et des paramètres associés.
Opérations
Les opérations suivantes sont prises en charge :
LoadAmazonBalance
L’opération LoadAmazonBalance applique des fonds au solde de chèque-cadeau d’un client Amazon. Voici une description des paramètres du corps de la demande.
Paramètre de la demande | Description |
---|---|
loadBalanceRequestId |
Identifiant unique représentant la demande préfixée avec un ID de partenaire sensible à la casse (40 caractères maximum). Valeur alphanumérique, ne doit pas contenir de caractères. |
partnerId |
Identifiant unique sensible à la casse pour représenter votre compte |
amount |
Valeur des fonds à ajouter au solde de chèque-cadeau Amazon |
currencyCode |
Code de devise ISO-4217 |
value |
Valeur monétaire à verser, spécifiée comme un nombre entier (par exemple, 100,23 = 10023). Dans les régions où la devise ne prend pas en charge la décimale, aucun remplissage n’est requis. Par exemple : au Japon, 231 yens correspondent à 231, pas à 23100. |
account |
Informations permettant d’identifier un client Amazon actif fournies par l’API Connexion avec Amazon. Pour les requêtes Sandbox, utilisez amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ |
id |
Valeur d’identification de compte client unique qui identifie le compte Amazon de l’utilisateur renvoyé comme réponse HTTP JSON à partir de l’API Connexion avec Amazon. |
type |
Spécifie le type d’identifiant. Valeur de type valide = 2 (ID client) |
transactionSource |
Données permettant d’identifier la source de la transaction |
sourceId |
Facultatif. Identifiant de la transaction. Ces métadonnées s’afficheront dans le registre du solde Amazon des clients. Par exemple : Chèque-cadeau de |
externalReference |
Champ de texte que vous pouvez utiliser pour décrire la demande lors de son affichage dans le portail API Incentives. (100 caractères Unicode maximum) |
notificationDetails |
Facultatif. Description du motif de versement des fonds. |
notificationMessage |
Facultatif. Chaîne qui apparaîtra dans l’e-mail de confirmation (250 caractères Unicode maximum). |
Exemple de demande
POST
/LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{ "loadBalanceRequestId":"Amazon123456",
"partnerId":"Amazon",
"amount":{
"currencyCode":"USD",
"value": 1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"transactionSource":{
"sourceId":"Customer Service"
},
"externalReference":"serviceId:123",
"notificationDetails":{
"notificationMessage":"Thank you for your purchase!"
}
}
Exemple de réponse
{
"status": "Success",
"amount": {
"currencyCode": "USD",
"value": 9000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
},
"loadBalanceRequestId": "Amazon123456"
}
VoidAmazonBalanceLoad
Cette opération annule une demande de LoadAmazonBalance précédemment réussie si les fonds du code de demande émis n’ont pas déjà été utilisés par le client Amazon destinataire. Cette opération peut être exécutée dans un délai de 15 minutes à partir de l’appel d’origine à LoadAmazonBalance. Au-delà de ce délai, un appel à VoidAmazonBalanceLoad n’aura aucun effet.
Votre application doit appeler cette opération lorsque vous ne pouvez pas confirmer la réussite d’une demande AmazonBalanceLoad précédente. Par exemple, si votre appel à LoadAmazonBalance ne renvoie aucun résultat, appelez VoidAmazonBalanceLoad pour vous assurer qu’aucun fonds n’a été ajouté au solde de chèque-cadeau du client Amazon.
Voici une description des paramètres du corps de la demande.
Remarque : tous les paramètres ci-dessous doivent correspondre à ceux utilisés dans une demande LoadAmazonBalance précédente.
Paramètre | Description |
---|---|
loadBalanceRequestId |
Identifiant unique utilisé dans une demande LoadAmazonBalance précédemment réussie |
partnerId |
Identifiant unique sensible à la casse pour représenter votre compte |
amount |
Montant monétaire fourni dans une demande LoadAmazonBalance |
currencyCode |
Code de devise ISO-4217 |
value |
Valeur monétaire de la transaction d’origine à déduire du solde de chèque-cadeau du client Amazon, spécifiée sous forme d’un nombre entier (par exemple 100,23 = 10023). Dans les régions où les devises ne prennent pas en charge les décimales, aucun remplissage n’est requis. Par exemple, au Japon, 231 yens correspondent à 231, pas à 23100. |
account |
Numéro de compte du client auquel l’opération d’annulation sera appliquée (à partir d’une opération de chargement précédente). Pour les requêtes Sandbox, utilisez amzn1.account.AFEM4VZRQQMBAAMVQEP3BPBH7OYQ |
id |
Valeur d’identification unique pour un compte client Amazon. Renvoyée à l’origine comme réponse HTTP JSON à partir de l’API Connexion avec Amazon. |
type |
Spécifie le type d’identifiant. Doit être défini sur 2 (ID client) |
Exemple de demande
POST
/VoidAmazonBalanceLoad HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{
"loadBalanceRequestId": "Amazon123456",
"partnerId": "Amazon",
"amount": {
"currencyCode": "USD",
"value": 1000
},
"account": {
"id": "amz1.account.123512341234",
"type": "2"
}
}
Exemple de réponse
{
"status":"Success",
"amount":{
"currencyCode":"USD",
"value":1000
},
"account":{
"id":"amz1.account.123512341234",
"type":"2"
},
"loadBalanceRequestId":"Amazon123456"
}
GetAvailableFunds
Consultez la sectionGetAvailableFunds.
Test des demandes
Pour tester votre intégration, vous pouvez simuler une réponse de l’API en créant une demande simulée. La réponse de la demande simulée est contrôlée par le paramètre id. Par exemple, si vous transmettez l’ID F0000, une réponse de réussite sera simulée, tandis que la transmission de l’ID F1000 simulera une erreur générale. Consultez la section Codes d’erreur pour obtenir la liste complète des réponses disponibles. Les paramètres suivants sont requis pour appeler une demande simulée :
{
"loadBalanceRequestId": "Amazon123456",
"account": {
"id": "F2044",
"type": "0"
}
}
Remarque : les valeurs transmises dans d’autres champs seront simplement répercutées dans la réponse et ne sont pas requises.
Exemple de demande simulée
POST /LoadAmazonBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256 Credential=AKIAIGHKAVYIDBOH3O3A/20170111/us-east-1/AGCODService/aws4_request,SignedHeaders=accept;host;x-amz-date;x-amz-target, Signature=ec86661c1d39f74b5891666505bb7656b172b0d060d911bee3b6a1c29ae17657
{ "loadBalanceRequestId":"Amazon123456",
"partnerId":"",
"amount":{
"currencyCode":"",
"value":""
},
"account":{
"id":"F2044",
"type":"0"
},
"transactionSource":{
"sourceId":""
},
"externalReference":"",
"notificationDetails":{
"notificationMessage":""
}
}
Exemple de réponse simulée
{
"errorCode": "F2044",
"errorMessage": "Source Id is too long. Received 41 characters. Maximum
number of characters is 40",
"errorType": "SourceIdTooLong",
"status": "FAILURE"
}
Script de test Connexion et réception
Vous pouvez vérifier certains composants de votre intégration à l’aide de l’environnement sandbox. Cependant, des tests complets de l’expérience utilisateur de vos applications peuvent uniquement être réalisés avec le compte de l’API de production.
Sandbox : Simulez une réponse à partir de l’API LoadAmazonBalance en créant une demande simulée.
Production :
- Utilisez le composant Connexion avec Amazon pour recevoir une valeur customer.id valide pour un compte client Amazon.
- Appelez les points de terminaison LoadAmazonBalance et VoidAmazonBalanceLoad.
- Effectuez un test exhaustif de votre application et de l’expérience utilisateur.
Test | Action | Résultat attendu |
---|---|---|
1. Créer des comptes de test amazon.com (ou locaux) | Créez plusieurs comptes Amazon dans la région pour tester l’appel d’API d’équilibrage de charge. | Les comptes sont créés. |
2. Valider le module Connexion avec Amazon | 1. Validez la réussite de la connexion. 2. Validez le jeton d’autorisation. 3. Validez la valeur user.id renvoyée. |
Pour chaque compte : 1. La connexion est réussie. 2. Le jeton d’autorisation est fourni. 3. Une valeur user.id unique est fournie. |
3. Validater LoadAmazonBalance | Utilisez le processus d’expérience utilisateur de votre application pour appeler cette méthode pour un compte de test créé à l’étape (1) pour une valeur monétaire (par exemple, 0,10 $). 2. Connectez-vous au compte Amazon et sélectionnez Afficher le solde du chèque-cadeau. 4. Valider le message de notification s’affiche sur l’e-mail de confirmation et correspond au paramètre notificationMessage inséré dans la requête API.5. Vérifiez que l’e-mail a été envoyé à l’adresse e-mail enregistrée sur le compte amazon.com. |
1. status = success est retourné pour chaque appel à Load2. Le solde de chèque-cadeau du compte correspond au montant chargé. 3. Le message de notification correspond au message fourni. 4. L’e-mail a été reçu. 5. Valeur spécifiée dans amount.value débité du compte dans le portail de l’API Incentives |
4. Valider l’idempotence LoadAmazonBalance | 1. Invoquer la méthode plusieurs fois avec le même loadBalanceRequestId et user.id 2. Connectez-vous à votre compte Amazon. 3. Affichez le solde de chèque-cadeau. |
1. status = success retourné pour chaque appel2. La valeur amount.value du premier appel est appliquée, mais les appels suivants de la méthode LoadAmazonBalance ont été ignorés. |
5. Valider VoidAmazonBalanceLoad | 1. Utiliser précédemment créé loadBalanceRequestId pour annuler une transaction2. Connectez-vous au compte amazon.com pour la valeur user.id correspondante. 3. Le solde a été annulé. 4. Vérifiez que l’e-mail a été envoyé à l’adresse e-mail enregistrée sur le compte amazon.com. 5. Connectez-vous au portail API Incentives et affichez la transaction. |
1. status = success est retourné pour chaque appel à Void2. Le solde de chèque-cadeau du compte correspond au montant chargé. 3. Le message de notification correspond au message fourni. 4. L’e-mail a été reçu. 5. Fonds spécifiés dans amount.value remboursé au compte dans le portail de l’API Incentives |
Performances
L’API est conçue pour traiter les transactions à un taux maximum de 10 transactions par seconde (TPS).
Remarque : l’environnement sandbox n’est régi par aucun accord sur le niveau de service et les taux de transaction peuvent sembler erratiques.
Codes d’erreur
Nous regroupons les types d’erreurs en cinq groupes. Par exemple, lorsque la cause est du côté client, l’API répond avec une erreur F2xx.
Code d’erreur | Description |
---|---|
F100 | Erreur interne Amazon |
F200 | Erreur de demande non valide (problème lié à la charge utile de la demande) |
F300 | Erreur associée au compte (généralement due à l’intégration, à l’authentification, à des problèmes d’accès, etc.) |
F400 | Erreur de nouvelle tentative (problème temporaire). Consultez la section Traitement des erreurs |
F500 | Erreur inconnue |
Type d’erreur Code d’erreur/Code simulé |
Description |
---|---|
GeneralError F100/F1000 |
Erreur interne Amazon |
BalanceLoadCannotBeVoided F100/F1001 |
Impossible d’annuler le chargement de solde en raison d’une erreur interne Amazon |
InvalidRequestInput F200/F2000 |
Le corps de la demande est nul |
InvalidPartnerIdInput F200/F2002 |
L’ID de partenaire ne peut pas être nul |
InvalidAmountInput F200/F2003 |
Le montant ne peut pas être nul |
InvalidAmountValue F200/F2004 |
Le montant doit être supérieur à 0 |
InvalidCurrencyCodeInput F200/F2005 |
Le code de devise ne peut pas être nul |
InvalidRequestIdInput F200/F2006 |
loadBalanceRequestId ne peut pas être nul |
MaxAmountExceeded F200/F2015 |
Le montant dépasse la valeur maximale autorisée dans le segment de marché national (p. ex. 500 $ aux États-Unis) |
FractionalAmountNotAllowed F200/F2017 |
Montant fractionnaire non autorisé dans la devise (p. ex. JP) |
RequestIdTooLong F200/F2021 |
loadBalanceRequestId dépasse 40 caractères |
RequestIdMustStartWithPartnerName F200/F2022 |
loadBalanceRequestId doit commencer par partnerId |
InvalidAccountType F200/F2033 |
Le type de compte fourni dans la demande n’est pas défini |
UndefinedAccountId F200/F2034 |
Le paramètre AccountId fourni dans la demande n’existe pas dans le système Amazon. |
AccountIdNotInValidStatus F200/F2035 |
Le statut du paramètre AccountId n’est pas valide pour l’opération demandée (par exemple, il est désactivé). |
InvalidCurrencyInMarketplace F200/F2036 |
Le code de devise n’est pas pris en charge dans le segment de marché national pour lequel AccountId a été créé. |
AmountBelowMinThreshold F200/F2037 |
Le montant est inférieur au minimum requis. |
LoadBalanceRequestIdAlreadyUsed F200/F2038 |
Le paramètre loadBalanceRequestId fourni dans l’API de chargement a déjà été utilisé (par exemple, en cas d’échec de la vérification de l’idempotence de loadBalanceRequestId). |
LoadBalanceRequestIdDoesNotExist F200/F2039 |
La demande de chargement avec le paramètre loadBalanceRequestId fourni dans l’API d’annulation n’existe pas. |
RequestMismatchFromLoadRequest F200/F2040 |
Les paramètres transmis dans une demande d’annulation ne correspondent pas aux paramètres d’une demande de chargement. |
BalanceLoadCannotBeVoided F200/F2041 |
Lorsque le solde chargé a été utilisé et que l’indicateur voidIfUsed est faux |
ExternalReferenceTooLong F200/F2042 |
La valeur utilisée dépasse le nombre maximal de caractères Unicode |
NotificationMessageTooLong F200/F2043 |
La valeur utilisée dans le paramètre notificationDetails dépasse 250 caractères Unicode. |
SourceIdTooLong F200/F2044 |
La valeur utilisée dans le champ sourceID dépasse le nombre maximal de 40 caractères Unicode. |
BalanceLoadCannotBeVoided F200/F2045 |
Impossible d’annuler le solde, car le délai de réception de la demande a expiré. |
InvalidPartnerId F300/F3000 |
L’ID de partenaire utilisé dans la demande d’API n’existe pas dans le système Amazon. |
InvalidAccessKey F300/F3001 |
La clé d’accès de sécurité utilisée pour signer la demande n’existe pas dans le système Amazon (non applicable en Chine). |
InvalidAccessKey F300/F3001 |
(Pour la Chine) La clé d’accès utilisée pour signer la demande API n’existe pas dans le système Amazon. |
AccessDenied F300/F3002 |
Le compte est bloqué. |
InsufficientFunds F300/F3003 |
Le compte ne dispose pas de fonds suffisants pour émettre le montant de la demande. (Chaque partenaire reçoit une certaine limite de crédit et peut uniquement émettre le solde correspondant. La limite de crédit est réinitialisée lorsque le partenaire effectue un paiement.) |
IssuanceCapExceeded F300/F3004 |
La limite d’émission du solde définie par le contrat a été atteinte pour la période spécifiée. |
OperationNotPermitted F300/F3006 |
La demande est rejetée. Le partenaire n’est pas autorisé à appeler l’API. (Cette erreur se produit lorsqu’un partenaire de distribution de chargement de solde non Amazon tente d’appeler une API de chargement de solde Amazon avant l’intégration.) |
ActiveContractNotFound F300/F3009 |
La configuration du compte du partenaire n’est pas terminée. |
CustomerSurpassedDailyVelocityLimit F300/F3010 |
Le client a dépassé la limite de vitesse quotidienne. |
CustomerAccountBlocked F300/F3011 |
Ce compte Amazon n’est pas autorisé à effectuer cette transaction. |
SystemTemporarilyUnavailable F400/F4000 |
Le système Amazon n’est pas disponible temporairement. Consultez la section Traitement des erreurs |
GeneralError F500/F5000 |
Erreur inconnue |