Desembolsar fondos para acreditar cuentas de clientes

Asegúrese de configurar su cuenta de la API de HAQM Incentives antes de iniciar la integración. Crear una cuenta de la API de Incentives.

El servicio web de Inicio de sesión y recepción proporciona una API para desembolsar fondos a un cliente de HAQM nuevo o existente. Un desembolso añade un valor monetario al saldo de Cheques regalo de la cuenta de un cliente de HAQM en tiempo real. Este servicio web basado en REST forma parte de la API de Incentives, que es un conjunto de servicios que admiten operaciones de Cheques regalo de HAQM.

Póngase en contacto con Inicio de sesión y recepción en los siguientes casos prácticos:

• Si necesita desembolsar dinero de manera inmediata y garantizada a sus clientes a través de una aplicación web existente.
• Tiene que asegurar que el valor monetario no sea transferible para cumplir con las obligaciones legales o comerciales.
• Quiere enviar un correo electrónico a los clientes para notificar un caso de desembolso.

Esta página describe cómo llamar a la API de Inicio de sesión y recepción desde la aplicación, y documenta las tareas que puede realizar con ella.

• Conceptos clave y flujo básico
• Requisitos previos
• API de Inicio de sesión y recepción
  • Operaciones
    • LoadHAQMBalance
    • VoidHAQMBalanceLoad
    • GetAvailableFunds
• Solicitudes de prueba
• Script de prueba de Inicio de sesión y recepción
• Rendimiento
• Códigos de error

Conceptos clave y flujo básico

La API de Inicio de sesión y recepción utiliza el servicio web Inicio de sesión con HAQM que permite a los usuarios autenticar su cuenta de HAQM utilizando sus credenciales de cuenta de HAQM dentro de su aplicación móvil o en el navegador. Una vez completada la autenticación, el servicio Inicio de sesión con HAQM proporciona a su aplicación un identificador de usuario que podrá utilizar como parámetro de entrada para la API de Inicio de sesión y recepción. Juntos, estos servicios ofrecen una experiencia perfecta a los usuarios finales.

Inicio de sesión con HAQM ofrece personalizaciones que se adaptan a su experiencia de usuario preferida, incluyendo SDK. Visite Inicio de sesión con HAQM en el Portal para desarrolladores para obtener más información.

A continuación se muestra una descripción del proceso de la aplicación para Inicio de sesión y recepción:

1. Un usuario de la aplicación solicita abonar el saldo de Cheques regalo de su cuenta de HAQM.
2. La aplicación muestra una página en el módulo Inicio de sesión con HAQM que solicita al usuario sus credenciales de HAQM.
3. Los nuevos clientes de HAQM pueden registrar una nueva cuenta en el proceso de inicio de sesión con HAQM.
4. Si su código solicita el nombre, la dirección de correo electrónico o el código postal del cliente de HAQM, el proceso de Inicio de sesión con HAQM solicitará el consentimiento del cliente para compartir esta información con el servicio.
5. El módulo inicia una solicitud de autorización mediante la API de Inicio de sesión con HAQM.
6. Un valor de id que identifica de forma exclusiva la cuenta de usuario se devuelve como objeto JSON en la respuesta.
7. La aplicación llama al método LoadHAQMBalance con el valor de id en el cuerpo de la solicitud.
8. La operación LoadHAQMBalance actualiza el saldo de Cheques regalo de la cuenta.
9. HAQM envía una confirmación por correo electrónico a la dirección de correo electrónico asociada a la cuenta de cliente de HAQM cuando los fondos se han aplicado correctamente o se ha anulado el saldo de Cheques regalo de la cuenta del cliente. Este correo electrónico contendrá el texto especificado en el parámetro notificationMessage de la solicitud LoadHAQMBalance.

Notas:

• El usuario puede cancelar el proceso de Inicio de sesión con HAQM en cualquier momento seleccionando Cancelar o cerrando la ventana emergente (si se utiliza este método de UX).
• El almacenamiento de información de identificación personal, incluido el nombre, la dirección de correo electrónico y el código postal, requerirá disposiciones de seguridad adicionales para cumplir con el RGPD, la CCPA y otras leyes de privacidad.

Requisitos previos

Complete estos pasos de configuración para usar Inicio de sesión y recepción:

• Siga las instrucciones de la guía de configuración de la integración de la API de Incentives para establecer una cuenta y aceptar un contrato con HAQM Incentives.
• Integre su aplicación web o móvil en el servicio web Inicio de sesión con HAQM para proporcionar autenticación y acceso (opcional) a los datos del perfil de usuario. Para obtener más información sobre cómo integrar su aplicación con Inicio de sesión con HAQM, siga los pasos del Centro de desarrolladores de Inicio de sesión con HAQM. Nota: Para usar Inicio de sesión con HAQM en su aplicación móvil, debe usar el SDK de Inicio de sesión con HAQM. Aunque una interacción basada en navegador es técnicamente posible desde una aplicación móvil, lo prohibimos por razones de seguridad.
• El Sandbox es un entorno de pruebas que utilizará al desarrollar y probar su aplicación. Póngase en contacto con su administrador de cuentas de HAQM para obtener las credenciales de acceso a Sandbox. Una vez que se le haya concedido el acceso a Sandbox, puede comenzar el desarrollo y las pruebas utilizando el valor de ID de socio que le hayan proporcionado. Las direcciones URL de punto de enlace para acceder a Sandbox se proporcionan en la sección Regiones y puntos de enlace. Con el acceso a Sandbox, puede desarrollar y probar su código siguiendo las instrucciones de la guía de configuración de la API de Integración de HAQM Incentives.

API de Inicio de sesión y recepción

Su aplicación interactúa con Inicio de sesión y recepción realizando solicitudes sincrónicas al servicio web. En esta sección se describe la estructura de una solicitud y las operaciones disponibles. Invocar una operación consiste en enviar una solicitud HTTP a un punto de enlace de la API de Incentives y esperar la respuesta. Una solicitud HTTP REST contiene un método de solicitud, URI, encabezados y un cuerpo presentado en XML o JSON. La respuesta contiene un código de estado HTTP, encabezados de respuesta y un cuerpo de respuesta. Cada llamada a la API deberá firmarse utilizando sus credenciales de seguridad y el proceso de firma de AWS Signature Version 4.

A continuación se muestra una descripción de cada operación de API, encabezados de solicitud y parámetros asociados.

Operaciones

Se admiten las siguientes operaciones:

• LoadHAQMBalance
• VoidHAQMBalanceLoad
• GetAvailableFunds

LoadHAQMBalance

La operación LoadHAQMBalance aplica fondos al saldo de Cheques regalo de un cliente de HAQM. A continuación se muestra una descripción de los parámetros del cuerpo de la solicitud.

Solicitud de muestra

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!"
    }
}

Respuesta de muestra

{
    "status": "Success",
    "amount": {
        "currencyCode": "USD",
        "value": 9000
    },
    "account": {
        "id": "amz1.account.123512341234",
        "type": "2"
    },
    "loadBalanceRequestId": "HAQM123456"
}

VoidHAQMBalanceLoad

Esta operación anula una solicitud LoadHAQMBalance que ya se ha realizado correctamente si el cliente receptor de HAQM aún no ha utilizado los fondos del código promocional emitido. Esta operación se puede ejecutar hasta 15 minutos desde la llamada original a LoadHAQMBalance. Después de eso, una llamada a VoidHAQMBalanceLoad no hará nada.

Su aplicación debe llamar a esta operación cuando no pueda confirmar que una solicitud anterior de HAQMBalanceLoad se haya realizado correctamente. Por ejemplo, si su llamada a LoadHAQMBalance no devuelve ningún resultado, llame a VoidHAQMBalanceLoad para asegurar que no se añaden fondos al saldo de Cheques regalo del cliente de HAQM.

A continuación se muestra una descripción de los parámetros del cuerpo de la solicitud.

Nota: Todos los siguientes parámetros deben coincidir con los utilizados en una solicitud anterior de LoadHAQMBalance.

Solicitud de muestra

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"
    }
}

Respuesta de muestra

{
    "status":"Success",
    "amount":{
        "currencyCode":"USD",
        "value":1000
    },
    "account":{
        "id":"amz1.account.123512341234",
        "type":"2"
    },
    "loadBalanceRequestId":"HAQM123456"
}

GetAvailableFunds

Consulte GetAvailableFunds.

Solicitudes de prueba

Para probar su integración, puede simular una respuesta desde la API creando una solicitud simulada. La respuesta de la solicitud simulada está controlada por el parámetro ID. Por ejemplo, pasar en ID F0000 simulará una respuesta positiva mientras que pasar en ID F1000 simulará un error general. Consulte los Códigos de error para obtener una lista completa de las respuestas disponibles. Los siguientes son los parámetros necesarios (mínimos) para invocar una solicitud simulada:

{
  "loadBalanceRequestId": "HAQM123456",
  "account": {
    "id": "F2044",
    "type": "0"
  }
}

Nota: Cualquier valor que se pase a otros campos se repetirá en la respuesta y no es obligatorio.

Muestra de solicitud simulada

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":""
    }
}

Muestra de respuesta simulada

{
    "errorCode": "F2044",
    "errorMessage": "Source Id is too long. Received 41 characters. Maximum   
number of characters is 40",
    "errorType": "SourceIdTooLong",
    "status": "FAILURE"
}

Script de prueba de Inicio de sesión y recepción

Puede verificar algunos componentes de la integración usando el entorno Sandbox. Sin embargo, las pruebas completas de la experiencia de usuario de las aplicaciones solo se pueden realizar utilizando la cuenta de API de producción.

Sandbox: Simular una respuesta desde la API LoadHAQMBalance creando una solicitud "simulada".

Producción:

• Utilice el componente Inicio de sesión con HAQM para recibir un valor de customer.id válido para una cuenta de cliente de HAQM.
• Llame a los puntos de enlace LoadHAQMBalance y VoidHAQMBalanceLoad.
• Pruebas completas de su aplicación y experiencia de usuario.

Rendimiento

La API está diseñada para procesar transacciones a una velocidad máxima de 10 transacciones por segundo (TPS).

Nota: El entorno de Sandbox no se rige por un SLA y las tasas de transacción pueden parecer erráticas.

Códigos de error

Utilizamos una convención de códigos para indicar errores. Por ejemplo, cuando la causa está del lado del cliente, la API responde con un error F2xx y F1XX si el problema se debe a un problema del sistema de HAQM. En general, los códigos de error se traducen como se muestra en la tabla siguiente.