Recevoir des fonds dans des points de vente

Assurez-vous de configurer votre compte API Amazon Incentives avant de commencer l’intégration. Étapes d’intégration d’Amazon Recharge près de chez vous

Le chargement de solde Amazon est un ensemble de systèmes qui vous permet de charger des fonds directement sur le solde de chèque-cadeau Amazon d’un client en temps réel, à condition que le client puisse s’identifier comme un client Amazon actif.

Le chargement de solde Amazon est un ensemble de systèmes qui vous permet de charger des fonds directement sur le solde de chèque-cadeau Amazon d’un client en temps réel, à condition que le client puisse s’identifier comme un client Amazon actif. Amazon Recharge près de chez vous utilise le service de chargement de solde Amazon pour permettre à un client d’ajouter des fonds à son solde de chèque-cadeau Amazon dans un magasin physique (briques et mortier) de votre réseau en fournissant un code-barres ou un numéro de téléphone mobile identifiant le compte client Amazon. Lorsqu’un compte Amazon actif est introuvable, un client peut obtenir un code de demande de chèque-cadeau Amazon sur un reçu imprimé qu’il pourra utiliser ultérieurement si votre implémentation le permet.

• Intégration avec le chargement de solde Amazon
• Amazon Recharge près de chez vous
• Ajouter votre numéro de téléphone
• Montant minimal et maximal par transaction et par pays
• Processus de chargement de solde en deux étapes
• Processus de chargement de solde en une étape
• Opérations avec exemples
  • Paramètres de demande
    • Type de compte Code-barres
    • Type de compte Numéro de téléphone
  • ValidateAccountForAmazonBalanceLoad
    • Exemple 1 : demande et réponse de réussite pour le compte de type Code-barres
    • Exemple 2 : demande et réponse de réussite pour le compte de type Numéro de téléphone
    • Exemple 3 : demande et réponse Partial_Success pour le compte de type Numéro de téléphone
    • Exemple 4 : réponse d’échec
    • Exemple 5 : renvoi d’une réponse d’échec
    • Exemple 6 : comparaison des réponses (pour les types Code-barres et Numéro de téléphone)
  • LoadAmazonBalance
    • Réponse de réussite pour le type de compte Code-barres
    • Réponse positive pour le type de compte Numéro de téléphone
    • Réponse d’échec
    • Besoins supplémentaires aux points de vente
  • VoidAmazonBalanceLoad
• Données de test
• Signatures numériques – Processus de signature
• Exemple de signature AWS V4

Intégration avec le chargement de solde Amazon

Vous pouvez effectuer des demandes synchrones sur les points de terminaison d’opérations en précisant le montant des fonds que vous souhaitez charger. Les opérations répondent à chaque demande avec un statut indiquant le succès ou l’échec de l’opération.

Ces API sont disponibles pour les partenaires qui concluent un contrat avec Amazon afin de créer une solution (généralement un système de point de vente) pour charger des fonds sur le solde de chèque-cadeau d’un client Amazon.

Amazon Recharge près de chez vous

Le service Amazon Recharge près de chez vous (le nom peut varier d’un pays à l’autre) permet aux clients Amazon de charger des fonds sur leur solde de chèque-cadeau Amazon ou d’obtenir un code de demande de chèque-cadeau en temps réel à partir d’un emplacement de briques et mortier (B&M). Cette transaction est initiée au sein du réseau de sites B&M du partenaire de distribution : les demandes de chargement sont traitées et ces transactions acheminées directement vers Amazon.

Un client pour représenter son compte Amazon sur le site B&M d’un partenaire de deux façons :

1. En affichant un code-barres personnalisé généré par Amazon et associé au compte Amazon du client (les clients obtiennent leur code-barres Amazon Recharge près de chez vous à partir de l’application Amazon ou du site Web Amazon), ou
2. En saisissant ou en fournissant le numéro de téléphone associé au compte Amazon du client, au point de vente

Remarque : la prise en charge des formats d’identification de compte et d’autres détails peut varier d’un pays à l’autre.

En plus de la méthode d’identification du client (code-barres ou numéro de téléphone), le client communique le montant des fonds qu’il souhaite charger sur son compte au magasin associé (minimum de 5 $ et maximum de 500 $ par chargement aux États-Unis). Ces informations sont compilées, puis transmises à Amazon qui répond par la suite par une confirmation ou un rejet de la demande de chargement. Vous pouvez opter pour un processus de demande de chargement en une ou deux étapes, comme indiqué ci-dessous.

Intégration

Pour commencer l’intégration, consultez le guide étape par étape fourni dans la rubrique Étapes d’intégration d’Amazon Recharge près de chez vous.

Après votre inscription, vous recevrez un ID de partenaire unique, sensible à la casse. Votre code inclura cet identifiant dans toutes les demandes adressées à l’API Incentives.

Montant minimal et maximal par transaction et par pays

Remarque : si votre intégration concerne un pays non répertorié, consultez votre responsable de compte pour connaître les montants de charge minimaux et maximaux.

Processus de chargement de solde en deux étapes

Le processus de chargement de solde en deux étapes implique l’utilisation de deux API : ValidateAccountForAmazonBalanceLoad et LoadAmazonBalance. Le processus standard est décrit ci-dessous :

1. Le caissier d’un magasin scanne le code-barres Amazon Recharge près de chez vous du client ou saisit le numéro de téléphone du client, puis demande à ce dernier quel montant il souhaite charger.
2. Le caissier saisit le montant dans le terminal PDV et demande la confirmation du client.
3. Le PDV envoie une demande ValidateAccountForAmazonBalanceLoad à Amazon. Amazon vérifie l’éligibilité du client à charger le montant demandé sur son solde de chèque-cadeau Amazon.
4. Si la réponse ValidateAccountForAmazonBalanceLoad confirme la demande, le caissier prend l’argent du client et le PDV envoie la demande LoadAmazonBalance à Amazon via le réseau de partenaires de distribution. Amazon ne recommande pas les activations préalables à la soumission, c’est-à-dire appeler LoadAmazonBalance avant que le caissier de magasin ait reçu l’argent.
5. Amazon traite la demande et vérifie d’abord l’éligibilité du client. S’il est éligible et si le compte Amazon peut être identifié, les fonds demandés sont chargés sur le solde de chèque-cadeau Amazon du client. Une réponse de confirmation est envoyée. Si le compte n’est pas éligible, une réponse de rejet est renvoyée. Si le client fournit un numéro de téléphone pour le processus de chargement de solde, et si ce numéro de téléphone ne peut être associé à aucun compte Amazon, l’opération répondra avec un code de demande chèque-cadeau valide. Dans ce cas, le code de demande doit être imprimé sur le reçu et remis au client.

Figure 1 : diagramme du processus de chargement de solde en deux étapes

Processus de chargement de solde en une étape

Si vous n’avez pas la possibilité d’envoyer une demande ValidateAccountForAmazonBalanceLoad comme décrit dans les instructions en deux étapes ci-dessus, vous pouvez choisir d’utiliser directement la demande LoadAmazonBalance. Voici une description du processus de chargement de solde en une étape :

1. Le caissier d’un magasin scanne le code-barres Amazon Recharge près de chez vous du client ou saisit le numéro de téléphone du client, puis demande à ce dernier quel montant il souhaite charger.
2. Le caissier saisit le montant dans le terminal PDV, demande confirmation au client, puis prend l’argent du client.
3. Le PDV envoie une demande LoadAmazonBalance à Amazon via votre réseau.
4. Pour traiter la demande, Amazon vérifie l’éligibilité du client. Si le client est éligible et si le compte Amazon peut être identifié, Amazon charge les fonds demandés sur le solde de chèque-cadeau du client. Une réponse de confirmation est envoyée. Si le compte n’est pas éligible, une réponse de rejet est renvoyée. Si le client fournit un numéro de téléphone, mais que ce numéro ne peut être associé à aucun compte Amazon, l’opération répondra avec un code de demande de chèque-cadeau valide. Dans ce cas, le code de demande doit être imprimé sur le reçu et remis au client.

Figure 2 : diagramme du processus de chargement de solde en une étape (magasin)

Opérations avec exemples

Paramètres de demande

account

Le account identifie un client final en tant que client Amazon actif.

Il s’agit d’une structure composite avec un id et un type.

id: identifiant unique qui permet à Amazon de localiser le compte Amazon d’un client (pour Amazon Recharge près de chez vous, l’ID correspond au code-barres ou au numéro de téléphone du client).

Les opérations prennent en charge deux valeurs de type :

type: type d’identifiant de compte du client final. Il prend en charge les identifiants du client tels que le code-barres, le numéro de téléphone, l’adresse e-mail, etc.

partnerId

Le partnerId est un identifiant unique fourni par Amazon lors du processus d’intégration. Cette valeur est attribuée par le gestionnaire d’intégration de partenaire d’Amazon et identifie de manière unique un partenaire de distribution. Cette valeur respecte la casse.

loadBalanceRequestId

Identifiant unique que vous générez pour représenter une demande. Cette valeur doit être préfixée par la valeur partnerId et doit comporter moins de 40 caractères.

amount

Le amount spécifie les fonds qui doivent être chargés. Il s’agit d’un paramètre composite incluant un code de devise et une valeur.

• currencyCode: code des devises ISO-4217.
• value: valeur du montant demandé. Ce champ contient un nombre entier (exemple : 100,23 comme 10023). Pour les devises ne prenant pas en charge les décimales, aucun remplissage n’est requis. Par exemple, au Japon, 231 yens correspondent à 231, pas à 23100.

timestamp

Horodatage UTC UNIX en millisecondes depuis 1/1/1970 00:00 UTC lorsque vous avez initié la demande.

Exemple : 2018-08-23T15:34:43+00:00 serait représenté comme suit : 1535038483000

voidIfUsed

Valeur booléenne indiquant si LoadAmazonBalance doit être annulé, même si le client final a déjà utilisé les fonds (en totalité ou en partie).

Exemple de cas d’utilisation : si le client a déjà utilisé une partie de ses fonds chargés, mais qu’une demande d’annulation est faite, nous révoquerons tous les fonds restants du montant initial chargé.

Pour un cas d’utilisation dans Amazon Recharge près de chez vous, cette valeur doit toujours être vraie.

transactionSource

Données d’emplacement permettant d’identifier l’emplacement de génération du chargement de solde Amazon. Ce paramètre est requis pour le produit Amazon Recharge près de chez vous.

Ce paramètre est une combinaison des composants suivants :

Le sourceDetails doit contenir la clé institutionName avec la valeur comme nom de la source (par exemple, Nom du vendeur). D’autres informations doivent également être incluses, comme l’emplacement de la source, le numéro de téléphone, etc.

Le institutionName apparaîtra dans l'e-mail de fonds ajouté dans cette phrase : « Des fonds ont été ajoutés à votre solde Amazon depuis institutionName. »

Il existe deux options pour envoyer les données d’emplacement du magasin à Amazon.

1. Forme longue : vous fournissez des données d'emplacement de magasin spécifiques pour chaque transaction (doit inclure sourceId, institutionId et un sourceDetails).
2. Forme courte :vous ne fournissez que sourceId et un institutionId dans la requête API. Un fichier de mappage d’emplacements distinct doit être envoyé pour qu’Amazon puisse analyser les données.

Instructions du fichier de mappage d’emplacements

Remarque : Le sourceDetails doit être formatée en tant qu’objet blob JSON similaire à cet exemple :

"transactionSource":{
      "sourceId":"558978547",
      "institutionId":"97263700008",
  "sourceDetails":"{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}"
   }

Pour plus d’exemples de transactionSource, consultez Source des transactions de points de vente.

Type de compte Code-barres

Prérequis

Pour assurer l’intégration avec le produit Amazon Recharge près de chez vous, ainsi que la prise en charge du type de compte 1 (basé sur des codes-barres), votre système PDV (point de vente) doit disposer de scanneurs de codes-barres capables de numériser les codes-barres sur les téléphones mobiles et compatibles avec les codes-barres 1D au format code 128.

Format de codes-barres

Amazon utilise son propre code produit et numéro d’identification d’émetteur (IIN) pour établir son code-barres. Le code-barres Amazon contient 30 chiffres, dont :

• 11 chiffres pour le code UPC
• 13 chiffres pour le code EAN ou JAN
• 6 chiffres pour le numéro IIN
• 12 chiffres pour le code PAN
• 1 chiffre pour la somme de contrôle

Amazon utilise l’algorithme de Luhn pour générer la somme de contrôle. Cet algorithme est appliqué aux numéros IIN et PAN.

Vous trouverez ci-dessous le code produit Amazon (UPC/EAN/JAN) et le numéro IIN, ainsi qu’un exemple de code-barres. Notez que le code produit varie en fonction du pays.

Code produit (UPC 11, EAN 13, JAN 13)

1. Numéro d’identification de l’émetteur global (IIN) : 608574

Figure 3.1a : exemple de codes-barres à 30 chiffres

Figure 4.1b : exemple de codes-barres à 32 chiffres

Type de compte Numéro de téléphone

Prérequis

Le numéro de téléphone est un autre type de compte pris en charge (type 4). Pour assurer l’intégration avec le produit Amazon Recharge près de chez vous, ainsi que la prise en charge du type de compte Numéro de téléphone, votre système PDV doit permettre à un opérateur d’entrer des numéros de téléphone et d’imprimer un reçu avec un code de demande dynamique. Dans certains cas, la transaction Amazon Recharge près de chez vous doit renvoyer un reçu papier contenant un code de demande dynamique que le client pourra utiliser en ligne pour créditer son compte par la suite.

Format du numéro de téléphone

Le numéro de téléphone saisi doit respecter l’un des formats suivants :

Les numéros E.164 peuvent comporter un maximum de quinze chiffres et sont formatés comme suit :

[+] [country code] [subscriber number including area code]   

Par exemple, +14155552671 (numéro aux États-Unis) ou +442071838750 (numéro au Royaume-Uni).

Nous préférons que vous nous envoyiez des numéros de téléphone au format E.164.

Remarque : actuellement, nous prenons uniquement en charge l’utilisation de numéros de téléphone locaux dans le pays où a lieu la transaction. Par conséquent, si un client tente d’utiliser un numéro de téléphone mexicain dans un kiosque/magasin américain, la transaction sera rejetée au PDV.

Exigences de reçus

Les exigences de reçu diffèrent en fonction de la capacité des systèmes PDV à modifier le contenu selon que l’appel LoadAmazonBalance pour le chargement basé sur le facteur de formulaire de téléphone a appliqué les fonds au compte du client (numéro de téléphone vérifié) ou émis un code de demande (numéro de téléphone non vérifié).

Texte d’instruction par défaut

Si le système PDV ne peut pas modifier le contenu du reçu, ce texte doit apparaître :

Conservez ce reçu jusqu’à ce que l’ajout de fonds à votre solde Amazon soit confirmé. Si les fonds n’ont pas été automatiquement appliqués à votre compte, consultez la page www.amazon.com/gc/redeem pour terminer la transaction. Les transactions Amazon Recharge près de chez vous ne sont pas remboursables, sauf si la loi l’exige. D’autres restrictions s’appliquent. Pour plus d’informations sur les conditions générales, consultez la page www.amazon.com/gc-legal.

ValidateAccountForAmazonBalanceLoad

L’opération ValidateAccountForAmazonBalanceLoad valide si le montant prévu se situe dans la plage autorisée pour ce pays et vérifie si le compte Amazon d’un client est éligible au processus de chargement de solde.

Pour le type de compte Code-barres, le contrôle d’éligibilité valide que le code-barres est associé à un compte client Amazon actif et qu’il est autorisé à ajouter des fonds sur son solde de chèque-cadeau Amazon.

Pour le type de compte Numéro de téléphone, la vérification porte sur la validité du numéro de téléphone fourni. Si le numéro de téléphone peut être identifié comme étant associé à un compte client Amazon, le statut d’éligibilité du client sera également validé. Sinon, la validation NE rejettera PAS le numéro de téléphone non identifié (qui n’est associé à aucun client Amazon) et traitera ce numéro comme un compte valide. L'opération répondra avec un PARTIAL_SUCCESS dans ce cas. Pour les numéros de téléphone non vérifiés, l’opération LoadAmazonBalance renverra un code de demande que le client pourra échanger manuellement par la suite.

Remarque : cette opération est préférée, mais ce n’est PAS une condition préalable à l’exécution ultérieure d’une opération LoadAmazonBalance.

  Paramètres de demande

Figure 5 : paramètres de demande ValidAccountForAmazonBalance

Réponse de réussite, réponse de réussite partielle

Figure 6 : réponse de réussite ValidAccountForAmazonBalanceLoad

Réponse d’échec

Ces chaînes obligatoires apparaissent dans ValidateAccountForAmazonBalanceLoadException :

• errorCode
• errorType
• errorMessage
• status  

  Exemple 1 : demande et réponse de réussite pour le compte de type Code-barres

Demande

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.ValidateAccountForAmazonBalanceLoad
	Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
Payload=

<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
    <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Réponse

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Example 2 : demande et réponse de réussite pour le compte de type Numéro de téléphone

Demande

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
    <account>
        <id>2061231234</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>

Réponse

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Example 3 : demande et réponse Partial_Success pour le compte de type Numéro de téléphone

Demande

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>2061231235</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
       <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
	 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample
Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Réponse

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231235</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Exemple 4 : réponse d’échec

réponse d’échec

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F200</errorCode>
 	<errorType>InvalidRequestInput</errorType>
 	<errorMessage>API request body is null/empty</errorMessage>
 	<status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>  

Exemple 5 : renvoi d’une réponse d’échec

Réponse d’échec

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F400</errorCode>
 	<errorType>SystemTemporarilyUnavailable</errorType>  	<errorMessage>Amazon system is temporarily not available</errorMessage>
 	<status>RESEND</status>
</ValidateAccountForAmazonBalanceLoadException>

Une erreur F400 nécessite un traitement minutieux des nouvelles tentatives pour éviter tout versement imprévu. Consultez la section Traitement des erreurs

Exemple 6 : comparaison des réponses (pour les types Code-barres et Numéro de téléphone)

Réponses pour le type Numéro de téléphone (valeur de type 4) lorsque le numéro de téléphone est vérifié

Numéro de téléphone vérifié (téléphone associé et vérifié sur le compte Amazon)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Numéro de téléphone non vérifié (téléphone NON associé/vérifié sur le compte Amazon)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>
<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+12061231234</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Réponses pour le type Code-barres (valeur de type 1)

Code-barres valide/actif

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Code-barres non valide/inactif

<ValidateAccountForAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>UndefinedAccountId</errorType>
    <errorMessage>AccountId provided in request does not exist in Amazon system</errorMessage>
    <status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>

LoadAmazonBalance

L’opération LoadAmazonBalance charge les fonds sur le solde de chèque-cadeau Amazon d’un client ou renvoie un code de demande de chèque-cadeau valide (si le numéro de téléphone fourni apparaît comment non vérifié sur un compte Amazon). Cette opération est idempotente, en ce sens que si Amazon reçoit plusieurs requêtes LoadAmazonBalance avec le même loadBalanceRequestId avec tous les paramètres correspondants (account, partnerId, amount, et transactionSource), la même réponse du premier appel sera renvoyée. Le loadBalanceRequestId que vous fournissez peut avoir une longueur maximale de 40 caractères, doit être préfixé avec votre partnerId, et doit être unique.

Paramètres de demande

Figure 8 : paramètres LoadBalanceRequest

Réponse de réussite pour le type de compte Code-barres

Figure 9 : réussite LoadBalanceResponse

Réponse de réussite pour le type de compte Numéro de téléphone

Paramètres de réponse LoadAmazonBalance

Le additionalInfo contient des informations telles que le code chèque-cadeau au format texte JSON. Voir l’exemple pour plus de détails.

Réponse d’échec

LoadAmazonBalanceException inclut 4 paramètres de chaîne :

• errorCode
• errorType
• errorMessage
• status

Exemple de réponse d’échec LoadAmazonBalance :

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Exemple 1 : demande LoadAmazonBalance et réponse de réussite pour le compte de type Code-barres

Demande

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Réponse

<LoadAmazonBalanceResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</LoadAmazonBalanceResponse>

Exemple 2 : demande LoadAmazonBalance et réponse de réussite (type de compte Numéro de téléphone) avec numéro de téléphone non vérifié (le code de demande de chèque-cadeau doit être réclamé manuellement)

Demande

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Réponse de réussite

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>
{"claimcode":"ABCD-EFGH-JK123"}
</additionalInfo>
</LoadAmazonBalanceResponse>

Réponse d’échec

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Exemple 3 : demande LoadAmazonBalance et réponse de réussite (type de compte Numéro de téléphone) avec numéro de téléphone vérifié (fonds automatiquement appliqués/réclamés)

Demande

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10,
Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Réponse

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadAmazonBalanceResponse>

Exemple de réponse d’échec LoadAmazonBalance :

Réponse d’échec

<LoadAmazonBalanceException>
 	<errorCode>F100</errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Exemple de renvoi de réponse LoadAmazonBalance :

Réponse d’échec

<LoadAmazonBalanceException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</LoadAmazonBalanceException>

Besoins supplémentaires aux points de vente

Chaque appel à LoadAmazonBalance qui se produit à un point de vente doit inclure les détails de l'emplacement où la transaction a eu lieu. Les demandes adressées à ces points de terminaison peuvent inclure un objet transactionSource qui décrit l'emplacement physique de l'événement.

Remarque : LoadAmazonBalance utilisée avec Connexion et réception ne doit pas inclure un objet transactionSource .

Il existe deux options pour envoyer les données d’emplacement du magasin à Amazon :

1. Forme longue : le partenaire fournit des données d'emplacement de magasin spécifiques pour chaque transaction (doit inclure sourceId, institutionId et sourceDetails)
2. Forme abrégée : le partenaire fournit uniquement le sourceId et institutionId dans la requête API. Un fichier de mappage d’emplacements distinct doit être envoyé pour mapper ces identifiants à des emplacements physiques. Reportez-vous aux instructions du fichier de mappage d’emplacements dans cette feuille de calcul.

Un exemple de charge utile de « forme longue » pour la source de transaction aux formats XML et JSON est illustré ci-dessous. Notez que sourceDetails doit être formaté en tant que blob JSON. Dans l’exemple JSON, l’objet blob JSON utilise la barre oblique inverse pour échapper les guillemets.

Exemple de forme longue de corps XML (notez que la valeur sourceDetails doit être formatée en tant que blob JSON) :

<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Exemple de forme courte de transactionSource dans le corps JSON :

{
  "loadBalanceRequestId": "Amxx134565",
  "partnerId": "Amxx1",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "account": {
    "id": "5551112222",
    "type": "4"
  },
  "timestamp": 1574704599588,
  "transactionSource": {
    "sourceId": "12345",
    "institutionId": "A123"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for loading balance at 12345!"
  }
}

VoidAmazonBalanceLoad

Lorsqu’un PDV ne peut pas garantir qu’une demande a été exécutée correctement, par exemple en raison d’un message manqué suite à des problèmes de réseau, le PDV et/ou le partenaire de distribution doivent exécuter une demande VoidAmazonBalanceLoad pour s’assurer que les fonds ne seront pas ajoutés au solde de chèque-cadeau Amazon du client. En cas de défaillance au point de vente, le caissier retourne toujours l’argent au client final. L’annulation est donc importante, car elle permet d’assurer le retrait rapide des fonds du solde de chèque-cadeau Amazon du client, dans l’éventualité où des fonds auraient été ajoutés, mais que le PDV n’aurait reçu aucun message de confirmation.

L’opération VoidAmazonBalanceLoad annulera une demande LoadAmazonBalance réussie uniquement dans les 15 minutes suivant la demande d’origine. L'original loadBalanceRequestId utilisé pour charger des fonds à partir d'une demande LoadAmazonBalance réussie est nécessaire pour l'opération annulée. Le currencyCode, value, sourceId et institutionId doivent correspondre aux valeurs respectives fournies dans la demande LoadAmazonBalance d'origine. L’opération d’annulation est idempotente.

Paramètres de demande

Figure 12 : diagramme de demande VoidAmazonBalanceLoad

Réponse de réussite

Figure 13 : diagramme de réponse positive VoidAmazonBalanceLoad

Réponse d’échec

Lorsque la demande d’annulation échoue, une exception VoidAmazonBalanceLoad avec ces paramètres de chaîne est renvoyée :

• errorCode
• errorType
• errorMessage
• status

Exemple 1 : demande VoidAmazonBalanceLoad et réponse de réussite (type de compte Code-barres)

Demande

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
	 	<partnerId>PartnerUS</partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails{"institutionName":"Walgreens",
"Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone":"+12061232333"}</sourceDetails>
 	</transactionSource>
 	<voidIfUsed>True</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Réponse

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

  Exemple 2 : demande VoidAmazonBalanceLoad et réponse de réussite (type de compte Numéro de téléphone)

Demande

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
    <account>
        <id>7574662233</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS</partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{"institutionName":"Walgreens",
          "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
          "Phone":"+12061232333"}</sourceDetails>
    </transactionSource>
    <voidIfUsed>True</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Réponse

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+17574662233</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

Exemple 3 : réponse d’échec VoidAmazonBalanceLoad

Réponse d’échec

<VoidAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>LoadBalanceRequestIdDoesNotExist</errorType>
    <errorMessage>Balance Load with provided loadBalanceRequestId does not exist</errorMessage>
    <status>FAILURE</status>
</VoidAmazonBalanceLoadException>

Exemple 4 : renvoi de réponse VoidAmazonBalanceLoad

Réponse d’échec

<VoidAmazonBalanceLoadException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</VoidAmazonBalanceLoadException>

Données de test

Afin de vous aider à effectuer des tests pendant le développement, nous avons créé des comptes de test (amazon.com). Différents comptes sont disponibles pour les environnements sandbox et de production. Des jetons sont disponibles à l’adresse https://s3.amazonaws.com/AGCOD/tech_spec/amazon-test-tokens.txt.

Consultez également les codes simulés que vous pouvez utiliser pour tester la façon dont votre code gère les échecs de requête courants.

Signatures numériques – Processus de signature

Chaque demande d’opération pour l’API Incentives doit être signée numériquement à l’aide de vos informations d’identification de sécurité de l’API Incentives et de l’algorithme de signature Signature Version 4.

Exemple de signature AWS V4

(en us-east-1 région)

Charge utile à signer :

{
  "account": {
    "id": "0360002414571003423331033001453",
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}

Charge utile hachée

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Demande canonique (avec lignes vides)

POST
/LoadAmazonBalance
 accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target
24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Demande canonique hachée

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Chaîne à signer

AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Clé de signature dérivée

 780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Signature

(Votre signature sera différente, car vos informations d’identification AWS sont différentes.)

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a  

Charge utile signée

POST /LoadAmazonBalance HTTP/1.1
accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance Authorization:AWS4-HMAC-SHA256 Credential=<Access Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a 
{
  "account": {
    "id": "0360002414571003423331033001453",
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}