Verser des fonds pour créditer des comptes clients

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

Le service Web Connexion et réception fournit une API permettant de verser des fonds à un client Amazon nouveau ou existant. Grâce à ce versement, le compte du client Amazon reçoit en temps réel une valeur monétaire sur son solde de chèque-cadeau. Ce service Web basé sur REST fait partie de l’API Incentives, qui offre un ensemble de services prenant en charge les opérations pour les chèques-cadeaux Amazon.

Appelez l’API Connexion et réception pour les cas d’utilisation suivants :

• Vous avez besoin de versements immédiats et garantis de devises à vos clients via une application Web.
• Vous devez vous assurer que la valeur monétaire n’est pas transférable pour satisfaire à vos obligations légales ou commerciales.
• Vous souhaitez envoyer une notification par e-mail aux clients pour les informer d’un événement de versement.

Cette page explique comment appeler l’API Connexion et réception à partir de votre application et documente les tâches que vous pouvez effectuer avec cette API.

• Concepts clés et flux de base
• Prérequis
• API Connexion et réception
  • Opérations
    • LoadAmazonBalance
    • VoidAmazonBalanceLoad
    • GetAvailableFunds
• Test des demandes
• Script de test Connexion et réception
• Performances
• Codes d’erreur

Concepts clés et flux de base

L’API Connexion et réception utilise le service Web Connexion avec Amazon qui permet aux utilisateurs d’authentifier leur compte Amazon avec leurs informations d’identification de compte Amazon dans leur navigateur ou leur application mobile. Une fois l’authentification terminée, le service Connexion avec Amazon fournit à votre application un identifiant d’utilisateur qui vous servira de paramètre d’entrée pour l’API Connexion et réception. Ces services combinés offrent une expérience transparente aux utilisateurs finaux.

Connexion avec Amazon propose des personnalisations pour s’aligner sur votre expérience utilisateur préférée, y compris un SDK. Pour plus d’informations, consultez la page relative à la connexion avec Amazon sur le portail des développeurs.

Vous trouverez ci-dessous une description du processus de l’application pour l’API Connexion et réception :

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
• VoidAmazonBalanceLoad
• GetAvailableFunds

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.

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.

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.

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.