Activer des chèques physiques

Activer des chèques physiques

Assurez-vous de configurer votre compte API Amazon Incentives avant de commencer l’intégration. Créer un compte API Incentives.


L’API Incentives vous permet de créer et de distribuer des codes de demande de chèques-cadeaux Amazon à la demande. Grâce à cette API, vous pouvez insérer des codes de demande de chèques-cadeaux électroniques, proposer des cadeaux de groupe et échanger en temps réel des codes de demande dans des programmes de fidélité (programmes par points).

Chaque chèque-cadeau est associé à un chèque activé sur le Web, unique et pré-généré, avec une dénomination (valeur numérique). Le chèque-cadeau peut être activé en temps réel. Une fois activé, le chèque-cadeau associé à un chèque activé sur le Web peut être distribué et le client peut l’utiliser pour effectuer des achats sur Amazon.

Les opérations d’activation Web de l’API Incentives fournissent une interface de programmation que vous pouvez utiliser pour activer ou désactiver les chèques-cadeaux en temps réel. Vous effectuez des demandes synchrones vers le point de terminaison qui spécifie la valeur du chèque activé sur le Web qu’ils souhaitent activer pour les chèques non dénominés, ou qui fournit le montant prédénominé correspondant pour les chèques prédénominés. L’API répond avec le statut de réussite ou d’échec de l’opération.

Il existe deux types de chèques activés par le Web :

  • Avec dénomination (montant fixe) : le montant est déjà prédéterminé pour le code de demande.
  • Sans dénomination (montant variable) : le montant est attribué lorsque le code de demande est activé.

Votre responsable de compte fournira les numéros des chèques activés sur le Web ainsi que les codes de demande associés, le cas échéant.

Remarque : les chèques activés sur le Web peuvent uniquement être activés par des partenaires autorisés.

Identifiants de la demande

Un appel à un point de terminaison inclut une valeur RequestId dans le corps de la requête.

  • activationRequestId - identifiant unique pour chaque appel ActivateGiftCard/DeactivateGiftCard qui entraîne l’activation ou la désactivation d’un chèque activé sur le Web. Vous devez générer une nouvelle valeur pour chaque demande Activate (sauf pour les nouvelles tentatives). Chaque valeur activationRequestId commence par votre ID de partenaire, suivi d’une valeur alphanumérique unique que vous générez dans vos systèmes. R activationRequestId ne peut pas dépasser 40 caractères. Un deuxième appel avec la même valeur activationRequestId renvoie l’état d’origine qui a été créé la première fois que la valeur activationRequestId a été vue.
  • statusCheckRequestId - Un identifiant utilisé dans un appel ActivationStatusCheck pour obtenir le statut d’un chèque à tout moment après une demande ActivateGiftCard réussie. Cette valeur doit correspondre à la valeur activationRequestId utilisée dans l’appel ActivateGiftCard précédent.

Numéro du chèque activé sur le Web et somme de contrôle : numéro à 16 chiffres du chèque activé sur le Web envoyé avec la somme de contrôle à 3 chiffres lors des demandes de point de terminaison (exemple : 1400000005567585358). Étant donné que les numéros de chèque sont généralement émis sur une plage (exemple : 1400000005567585 - 1400000005568000), utilisez la somme de contrôle pour confirmer que le bon numéro de chèque a été envoyé dans votre demande d’activation. Cette vérification est particulièrement importante si un chèque est activé manuellement et si les numéros du chèque sont communiqués oralement. L’exemple ci-dessous illustre des chèques activés sur le Web. Notez qu’Amazon fournira un format similaire pour des chèques activés sur le Web et des codes de demande dans le cadre d’une activation Web.

SÉQUENCE NUMÉRO DE CHÈQUE SOMME DE CONTRÔLE MONTANT CODE DE DEMANDE
1 1400000005567585 358 0,00 $ WA2W-A3CYCB-RDAMZ
2 1400000005567586 149 0,00 $ WAS3-C8PP8R-MZMMD

Source de transaction (partenaires B&M uniquement) : données d’emplacement permettant d’identifier l’emplacement où le chèque-cadeau a été activé. Ce paramètre est requis pour toutes les demandes de briques et mortier (POSA).

Ce paramètre est composé de ces éléments :

Composant Description
sourceId Identifiant d’une entité source de transaction (exemple : Numéro de magasin ou ID de magasin).
institutionId Identifiant de l’entité parente d’une source de transaction (exemple : ID du vendeur). Si l’entité parente n’existe pas, copiez sourceId.
sourceDetails chaîne servant à fournir plus d’informations sur la source de transaction. Elle 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.
institutionParentCompany Nom de la société mère pour institutionName. S’il n’y a pas de société mère, institutionName doit être répété.

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

  1. Forme longue : vous fournit des données d’emplacement de magasin spécifiques pour chaque transaction (doit inclure sourceId, institutionId et un sourceDetails).
  2. Forme courte : vous fournissez uniquement les valeurs sourceId et institutionId dans la demande 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

Les exemples suivants montrent une charge utile de « forme longue » pour la source de transaction aux formats XML et JSON. Notez que sourceDetails doit être formaté en tant que blob JSON.

XML

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
      <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
   </transactionSource>
</ActivateGiftCardRequest>

JSON

{"value": {"currencyCode": "USD", "amount": 150}, "activationRequestId": "Awssb0327141418PM", "cardNumber": "6215366885893081", "partnerId": "Apppt", "externalReference": "{\"promoCode\":\"855238\"}", "transactionSource": {"sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}", "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"}}

Requis pour les revendeurs uniquement : ProgramID

Vous pouvez utiliser le champ programID pour vous aider à mieux effectuer le suivi des transactions des clients et des cas d’utilisation. L’identifiant approuvé programID est fourni par Amazon lors d’un processus de soumission au cours duquel vous soumettez des informations sur les clients et les cas d’utilisation via le portail API Incentives. Les soumissions approuvées recevront un numéro de référence qui sera ajouté à chaque appel de transaction à l’API. Le paramètre programID est alphanumérique et peut contenir jusqu’à 100 caractères.

L’exemple de message ci-dessous illustre les modifications nécessaires pour gérer le champ programID.

<ActivateGiftCardRequest>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
  <partnerId>Awssb</partnerId>
  <cardNumber>1700000005489413</cardNumber>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>10</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</ActivateGiftCardRequest>

Remarque : pour les partenaires de bons de produits, le format de la demande n’est pas modifié, car le paramètre cardNumber envoyé sera mappé au type de bon de produit correspondant lors de la génération du chèque.

Opérations

Opération Description
ActivateGiftCard Active un chèque physique, de sorte qu’il puisse être échangé par un client.
DeactivateGiftCard Désactive un chèque physique, de sorte qu’il ne puisse pas être échangé.
ActivationStatusCheck Indique le statut d’activation d’un chèque-cadeau physique.

Paramètres communs

Paramètre Exemple de valeur
Méthode de demande HTTP POST
URI canonique (commence par/)
Chaîne de requête canonique (chaîne vide)
En-têtes canoniques (voir ci-dessous)
En-têtes signés content-type;host;x-amz-date;x-amz-target
Algorithme AWS4-HMAC-SHA256
Date de la demande 20140327T212600Z
Portée des informations d’identification 20140327/us-east-1/AGCODService/aws4_request
Nom du service AGCODService
ID de la demande d’activation Awssb0327141418PM
Hôte agcod-v2-gamma.amazon.com (le point de terminaison applicable peut être trouvé dans la spécification technique)
Nom de la région us-east-1 (la région correspondante se trouve dans la spécification technique)
ID de partenaire Awssb (utilisez votre propre ID de partenaire)
Numéro de chèque 1700000005489413

En-têtes canoniques :

content-type:application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20140327T212600Z
x-amz-target: com.amazonaws.agcod.AGCODService.ActivateGiftCard 

ou

content-type:application/x-www-form-urlencoded; charset=UTF-8
host: agcod-v2-gamma.amazon.com
x-amz-date: 20140327T212600Z
x-amz-target: com.amazonaws.agcod.AGCODService.ActivateGiftCard 

ActivateGiftCard

L’opération ActivateGiftCard place une carte physique dans un état actif. Un chèque physique à l’état actif peut être échangé par un client.

Vous envoyez un activationRequestId qui identifie de manière unique cette demande d’activation, ainsi que d’autres détails comme la dénomination, la devise (en plus des métadonnées relatives à cette demande, informations d’authentification, etc.).

Pour effectuer cette opération, envoyez une requête ActivateGiftCard réussie. Amazon vérifie que votre compte Amazon Payments ou un autre compte de prépaiement dispose de fonds suffisants, déduit les fonds du compte et envoie un message de réponse synchrone qui inclut le statut d’activation, cardNumber, cardStatus, et activationRequestId. Vous devez stocker activationRequestId, amount, et currencyCode pour toutes les requêtes ultérieures liées à la même transaction. Le message de réponse contient également des métadonnées et le statut de l’exécution. Actuellement, les statuts WAC (Web Activated Card) retournés sont soit Activated, AwaitingActivationou Invalidated.

Cette opération est idempotente. Par conséquent, l’API Incentives reçoit plus d’une requête avec la même activationRequestId, alors la première demande entraînera l’activation d’un nouveau WAC, tandis que toutes les réponses ultérieures retourneront le WAC activé à l’origine et ne seront pas traitées comme des transactions distinctes.

Remarques :

  • Un appel ActivateGiftCard n’entraîne qu’une seule activation. (L’activation en bloc n’est pas prise en charge pour le moment.)
  • En tant qu’une couche supplémentaire de protection contre la fraude, lorsque trois tentatives de réclamation sont faites à un code chèque-cadeau associé à un WAC dénommé variable (désigné par une valeur initiale nulle) lorsqu’il est dans le champ AwaitingActivation , le statut WAC sera modifié en Invalidated. Le ActivateGiftCard/DeactivateGiftCard ne sera pas en mesure d’opérer contre le WAC à l’état Invalidated . Si vous trouvez un grand nombre de WAC avec l’état Invalidated , il peut être révélateur d’activités frauduleuses contre les cartes WAC ou d’erreurs de processus de votre côté. Contactez votre responsable de compte pour obtenir de l’aide.
  • La valeur de la devise varie en fonction de votre segment de marché national.

Exemple de demande HTTP POST ActivateGiftCard avec charge utile JSON

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10
  }
}

Exemple de demande HTTP POST ActivateGiftCard avec charge utile XML

DEMANDE SIGNÉE

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</ActivateGiftCardRequest>

Exemple ActivationGiftCardResponse

JSON

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "expirationDate": null,
    "value": {
      "amount": 10,
      "currencyCode": "USD"
    }
  },
  "status": "SUCCESS"
}

XML

<ActivateGiftCardResponse>
  <cardInfo>
    <value>
      <amount>10.0</amount>
      <currencyCode>USD</currencyCode>
    </value>
    <cardStatus>Activated</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
</ActivateGiftCardResponse>

Besoins supplémentaires aux points de vente

Chaque appel à ActivateGiftCard 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.

Champ dans transactionSource Description
sourceId Identifiant d’une entité source de transaction (exemple : Numéro de magasin ou ID de magasin).
institutionId Identifiant de l’entité parente d’une source de transaction (exemple : ID du vendeur). Si l’entité parente n’existe pas, copiez la chaîne sourceId.
sourceDetails servant à fournir plus d’informations sur la source de transaction. Elle 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.
institutionParentCompany Nom de la société mère pour instituitionName. S'il n'y a pas de société mère, institutionName devrait être répété.

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é comme un blob JSON) :

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
      <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
   </transactionSource>
</ActivateGiftCardRequest>

Exemple de forme longue du corps JSON :

{
  "value": {
    "currencyCode": "USD",
    "amount": 150
  },
  "activationRequestId": "Awssb0327141418PM",
  "cardNumber": "6215366885893081",
  "partnerId": "Apppt",
  "externalReference": "{\"promoCode\":\"855238\"}",
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

DeactivateGiftCard

L’opération DeactivateGiftCard place un chèque physique dans un état inactif. Un chèque inactif ne peut pas être échangé par un client.

Vous pouvez désactiver un chèque activé sur le Web dans les conditions suivantes :

  • Le code de demande associé au chèque activé sur le Web n’est pas réclamé par un client Amazon.
  • Le chèque activé sur le Web ne présente pas l’état Invalidated .
  • Le chèque activé sur le Web a été précédemment activé par le même partenaire. Le paramètreactivationRequestId d’origine utilisé pour activer le chèque activé sur le Web et le numéro de chèque doivent être fournis pour une opération DeactivateGiftCard.

Pour effectuer cette opération, envoyez une demande DeactivateGiftCard. L’API Incentives répond avec un DeactivateGiftCardResponse synchrone.

Cette opération est idempotente : si l’API Incentives reçoit plus d’une demande avec le même activationRequestId, la première demande entraînera la désactivation du chèque activé sur le Web, tandis que toutes les réponses suivantes seront sans effet et ne seront pas traitées comme des transactions différentes.

Remarque : les opérations ActivateGiftCard/DeactivateGiftCard doivent uniquement être utilisées avec des chèques-cadeaux physiques, et non avec des codes de demande créés à l’aide de l’API CreateGiftCard.

Exemple de demande HTTP POST DeactivateGiftCard avec charge utile JSON

DEMANDE SIGNÉE

POST /DeactivateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213727Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=86a6ce1bfdb1e0e5842b5e351ad87058b673bdc6f7fd770c6fdb8349a1de1bde
{"activationRequestId": "Awssb0327141418PM", "partnerId": "Awssb", "cardNumber": "1700000005489413"}

Exemple de demande HTTP POST DeactivateGiftCard avec charge utile XML

DEMANDE SIGNÉE

POST /DeactivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213942Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0ace0a2eaefc9ecf62e1224c7e59abe46af934a8e772b808c18dccdfdab009a5
<DeactivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
</DeactivateGiftCardRequest>

Exemple DeactivateGiftCardResponse

JSON

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS"
}

XML

<DeactivateGiftCardResponse>
  <cardInfo>
    <cardStatus>AwaitingActivation</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
</DeactivateGiftCardResponse>

ActivationStatusCheck

L’opération ActivationStatusCheck permet de vérifier le statut du chèque activé sur le Web après l’exécution de l’appel ActivateGiftCard/DeactivateGiftCard. Amazon répondra avec un ActivationStatusCheckResponse synchrone qui indiquera le statut actuel du chèque activé sur le Web.

Les statuts renvoyés pour les chèques activés sur le Web sont Activated, AwaitingActivation ou Invalidated.

Remarque : les opérations CreateGiftCard/CancelGiftCard et ActivateGiftCard/DeactivateGiftCard ne doivent pas être combinées. Par exemple, un code de demande créé avec l’appel CreateGiftCard ne doit pas être désactivé avec l’appel DeactivateGiftCard . De même, un code de demande activé avec ActivateGiftCard ne doit pas être annulé avec l’appel CancelGiftCard.

Exemple de demande HTTP POST ActivationStatusCheck avec charge utile JSON

DEMANDE SIGNÉE

POST /ActivationStatusCheck HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234321Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=ae3aa76cdc3043d45ca962a3a85ea9b95c6202a87f9700e7fe04b4c8d956ca31
{"statusCheckRequestId": "Awssb0327141418PM", "partnerId": "Awssb", "cardNumber": "1700000005489413"}

Exemple de demande HTTP POST ActivationStatusCheck avec charge utile XML

DEMANDE SIGNÉE

POST /ActivationStatusCheck HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234634Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=96025ab925782595bffde21366bcd1927406ce5ddb723e89088f2cb0026040e8
<ActivationStatusCheckRequest>
  <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
  <partnerId>Awssb</partnerId>
  <cardNumber>1700000005489413</cardNumber>
</ActivationStatusCheckRequest>

Exemple ActivationStatusCheckResponse

JSON

Si le chèque activé sur le Web n’est pas déjà activé :

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": "Awssb0327141418PM"
}

OU, si le chèque activé sur le Web est déjà activé :

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": " Awssb0327141418PM"
}

XML

Si le chèque activé sur le Web n’est pas déjà activé :

<ActivationStatusCheckResponse>
  <cardInfo>
    <cardStatus>AwaitingActivation</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>

OU, si le chèque activé sur le Web est déjà activé :

<ActivationStatusCheckResponse>
  <cardInfo>
    <cardStatus>Activated</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  < statusCheckRequestId> Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>

Exemples de tests

Nous fournissons des ID de demande d’erreur simulée pour simuler certaines réponses d’erreur concernant les appels de création ou d’annulation. Lors de la simulation d’une réponse d’erreur, l’ID de demande d’erreur simulée doit être transmis en tant que paramètre activationRequestId. Les valeurs fournies pour les autres champs seront répercutées dans la réponse.

Test de simulation de réussite avec requestId F0000

DEMANDE SIGNÉE

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140402T234117Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140402/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=fdd5f610c04cea390b07d6f2e4891516f6bdfa0158595e7deda8eedc8468422d
<ActivateGiftCardRequest><activationRequestId>F0000</activationRequestId> <partnerId>Awssb</partnerId><cardNumber>abc123</cardNumber><value><currencyCode>phonybucks</currencyCode><amount>10</amount></value></ActivateGiftCardRequest>

RÉPONSE

<ActivateGiftCardResponse>
  <cardInfo>
    <value>
      <amount>10.0</amount>
      <currencyCode>phonybucks</currencyCode>
    </value>
    <cardStatus>Activated</cardStatus>
    <cardNumber>abc123</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>F0000</activationRequestId>
</ActivateGiftCardResponse>

Test de simulation d’échec avec requestId F2005

DEMANDE SIGNÉE

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140402T234840Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140402/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=fa280d821ac7a8ba3e031e463c7c121509642cd6f7bf54c3a4586bfc2d8eae8f
<ActivateGiftCardRequest><activationRequestId>F2005</activationRequestId> <partnerId>Awssb</partnerId><cardNumber>abcdef</cardNumber><value><currencyCode>phonybucks</currencyCode><amount>10</amount></value></ActivateGiftCardRequest>

RÉPONSE

<AGCODValidationException>
  <Message>Currency Code can't be null or empty</Message>
  <errorType>InvalidCurrencyCodeInput</errorType>
  <errorCode>F200</errorCode>
  <agcodResponse>
    <status>FAILURE</status>
  </agcodResponse>
</AGCODValidationException>

Activer le stock physique (POSA) - Script de test

Pour vérifier votre intégration avec l’API, exécutez les tests suivants :

Description du test Détails du cas de test Résultat attendu
1. Vérification du statut Envoyer une ActivationStatusCheck requête pour un numéro de carte sandbox qui n’a pas été utilisé auparavant. Vous devriez recevoir une réponse SUCCESS avec l’état de la carte de Activated.
2. Activer le chèque Envoyer une ActivateGiftCard à l’URL Sandbox pour le numéro de carte utilisé dans la vérification d’état (1). Vous devriez recevoir une réponse SUCCESS avec l’état de la carte de Activated.
3. Désactiver le chèque Envoyer un requête DeactivateGiftCard en utilisant le même ID de demande pour le numéro de carte qui a été activé (2). Vous devriez recevoir une réponse SUCCESS avec l’état de la carte de AwaitingActivation.
4. Activer l’idempotence Envoyer une nouvelle requête ActivateGiftCard et enregistrer la réponse. Renvoyez la même demande Activate en utilisant le même ID de demande et le même montant. Vous devriez recevoir une réponse SUCCESS avec la même réponse que la demande originale.

FAQ sur l’activation Web

Q.1 : Comment utiliser les API Activate et Desactivate ?

A.1 Utilisez le ActivateGiftCard pour activer un chèque-cadeau en fournissant le activationRequestId et le montant (montant libellé ou prélibellé selon le type de carte). Si vous avez déjà activé un code chèque-cadeau avec succès et que vous devez l’annuler, vous devez fournir l’original activationRequestId, le montant et les valeurs de devise que vous avez utilisées dans l’opération ActivateGiftCard . Si vous voyez un délai d’expiration de la passerelle AGCOD lors de la création d’une opération ActivateGiftCard ou DeactivateGiftCard et vous n’êtes pas sûrs si votre appel a réussi, appelez alors ActivationStatusCheck pour vérifier l’état de la carte.


Q.2 : Je reçois une erreur « Le chèque a déjà été activé avec un ID de demande différent » lorsque j’effectue un appel ActivateGiftCard .

R.2 : Il se peut que le même numéro de série du chèque ait été activé avec un différent activationRequestId. Trouvez l’original activationRequestId et réessayez l’appel.


Q.3 Y a-t-il des limites de temps à partir du moment où une demande ActivateGiftCard est effectuée et lorsqu’un DeactivateGiftCard sera accepté ?

R.3 : Il n’y a actuellement aucune limite de temps. Les appels à DeactivateGiftCard échoueront une fois qu’une transaction d’utilisation a été traitée pour le chèque-cadeau. Par exemple, si le chèque-cadeau a été réclamé par votre client final, appelez à DeactivateGiftCard échouera. De plus, un chèque-cadeau activé ne peut pas être désactivé après sa date d’expiration. Les chèques-cadeaux émis aux États-Unis, au Canada et en Australie n’expirent pas.