Verser des fonds pour créditer des comptes clients

Assurez-vous de configurer votre compte API HAQM 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 HAQM nouveau ou existant. Grâce à ce versement, le compte du client HAQM 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 HAQM.

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
    • LoadHAQMBalance
    • VoidHAQMBalanceLoad
    • 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 HAQM qui permet aux utilisateurs d’authentifier leur compte HAQM avec leurs informations d’identification de compte HAQM dans leur navigateur ou leur application mobile. Une fois l’authentification terminée, le service Connexion avec HAQM 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 HAQM 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 HAQM 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 HAQM.
2. Dans l’application, une page s’affiche dans le module Connexion avec HAQM invitant l’utilisateur à fournir ses informations d’identification HAQM.
3. Les nouveaux clients HAQM peuvent créer un compte via le processus Connexion avec HAQM.
4. Si votre code requiert le nom, l’adresse e-mail ou le code postal du client HAQM, le processus Connexion avec HAQM 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 HAQM.
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 LoadHAQMBalance en incluant la valeur id dans le corps de la requête.
8. L’opération LoadHAQMBalance met à jour le solde de chèque-cadeau du compte.
9. HAQM envoie un e-mail de confirmation à l’adresse e-mail associée au compte client HAQM 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 LoadHAQMBalance.

Remarques :

• L’utilisateur peut interrompre le processus Connexion avec HAQM à 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 HAQM Incentives.
• Intégrez votre application Web ou mobile au service Web Connexion avec HAQM 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 HAQM, suivez les étapes décrites sur le centre des développeurs HAQM pour accéder au module Connexion avec HAQM. Remarque : pour utiliser Connexion avec HAQM dans votre application mobile, vous devez utiliser le SDK Connexion avec HAQM 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 HAQM 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’HAQM.

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 :

• LoadHAQMBalance
• VoidHAQMBalanceLoad
• GetAvailableFunds

LoadHAQMBalance

L’opération LoadHAQMBalance applique des fonds au solde de chèque-cadeau d’un client HAQM. Voici une description des paramètres du corps de la demande.

Exemple de demande

POST 
/LoadHAQMBalance HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
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":"HAQM123456",
    "partnerId":"HAQM",
    "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": "HAQM123456"
}

VoidHAQMBalanceLoad

Cette opération annule une demande de LoadHAQMBalance précédemment réussie si les fonds du code de demande émis n’ont pas déjà été utilisés par le client HAQM destinataire. Cette opération peut être exécutée dans un délai de 15 minutes à partir de l’appel d’origine à LoadHAQMBalance. Au-delà de ce délai, un appel à VoidHAQMBalanceLoad n’aura aucun effet.

Votre application doit appeler cette opération lorsque vous ne pouvez pas confirmer la réussite d’une demande HAQMBalanceLoad précédente. Par exemple, si votre appel à LoadHAQMBalance ne renvoie aucun résultat, appelez VoidHAQMBalanceLoad pour vous assurer qu’aucun fonds n’a été ajouté au solde de chèque-cadeau du client HAQM.

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 LoadHAQMBalance précédente.

Exemple de demande

POST 
/VoidHAQMBalanceLoad HTTP/1.1

accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidHAQMBalanceLoad
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": "HAQM123456",
    "partnerId": "HAQM",
    "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":"HAQM123456"
}

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": "HAQM123456",
  "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 /LoadHAQMBalance HTTP/1.1
accept:application/json
host:agcod-v2-gamma.haqm.com
x-amz-date:20170111T000339Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadHAQMBalance
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":"HAQM123456",
    "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 LoadHAQMBalance en créant une demande simulée.

Production :

• Utilisez le composant Connexion avec HAQM pour recevoir une valeur customer.id valide pour un compte client HAQM.
• Appelez les points de terminaison LoadHAQMBalance et VoidHAQMBalanceLoad.
• 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.