Verser des fonds pour créditer des comptes clients

Débourser des fonds pour créditer des comptes clients avec le processus Connexion et réception

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

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 :

  1. Un utilisateur de l’application demande de créditer le solde de chèque-cadeau de son compte Amazon.
  2. Dans l’application, une page s’affiche dans le module Connexion avec Amazon invitant l’utilisateur à fournir ses informations d’identification Amazon.
  3. Les nouveaux clients Amazon peuvent créer un compte via le processus Connexion avec Amazon.
  4. 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.
  5. Le module lance une demande d’autorisation à l’aide de l’API Connexion avec Amazon.
  6. Une valeur id qui identifie de manière unique le compte utilisateur est renvoyée en tant qu’objet JSON dans la réponse.
  7. Votre application appelle la méthode LoadAmazonBalance en incluant la valeur id dans le corps de la requête.
  8. L’opération LoadAmazonBalance met à jour le solde de chèque-cadeau du compte.
  9. 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 <Numéro de série : xxx> (40 caractères Unicode maximum)
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 à Load
2. 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 appel
2. 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 transaction
2. 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 à Void
2. 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