Recibir fondos en sitios físicos

Asegúrese de configurar su cuenta de la API de Amazon Incentives antes de iniciar la integración. Pasos de incorporación a Amazon Top Up in Store

La Carga de saldo de Amazon (ABL) es un conjunto de sistemas que le permiten cargar fondos directamente en el saldo del Cheque regalo de Amazon del cliente en tiempo real, siempre y cuando el cliente pueda identificarse como cliente activo de Amazon.

La Carga de saldo de Amazon (ABL) es un conjunto de sistemas que le permiten cargar fondos directamente en el saldo del Cheque regalo de Amazon del cliente en tiempo real, siempre y cuando el cliente pueda identificarse como cliente activo de Amazon. Amazon Top Up in Store utiliza el servicio de carga de saldo de Amazon para permitir que un cliente agregue fondos a su saldo de Cheque regalo de Amazon en una tienda física de su red mediante un código de barras o un número de teléfono móvil que identifique la cuenta de cliente de Amazon. Cuando no se encuentra una cuenta de Amazon activa, un cliente puede obtener un código de reclamación del Cheque regalo de Amazon en un recibo impreso que puede canjear más tarde si su implementación permite este resultado.

• Integración con Carga de saldo de Amazon
• Amazon Top Up in Store
• Incorporación
• Importe mínimo y máximo por transacción por país
• Proceso de carga de equilibrio en dos pasos
• Proceso de carga de equilibrio en un solo paso
• Operaciones con ejemplos
  • Parámetros de solicitud
    • Tipo de cuenta de código de barras
    • Tipo de cuenta de número de teléfono
  • ValidateAccountForAmazonBalanceLoad
    • Ejemplo 1: Solicitud y respuesta positiva para la cuenta de tipo código de barras
    • Ejemplo 2: Solicitud y respuesta positiva para la cuenta de tipo número de teléfono
    • Ejemplo 3: Respuesta de solicitud y Parcial_Success para la cuenta de tipo número de teléfono
    • Ejemplo 4: Respuesta de error
    • Ejemplo 5: Error de reenvío de respuesta
    • Ejemplo 6: Comparación de respuestas (para tipos de códigos de barras y números de teléfono)
  • LoadAmazonBalance
    • Respuesta positiva para el tipo de cuenta de código de barras
    • Respuesta positiva para el tipo de cuenta de número de teléfono
    • Respuesta de error
    • Requisitos adicionales en emplazamientos físicos
  • VoidAmazonBalanceLoad
• Datos de prueba
• Firmas digitales — Proceso de firma
• Ejemplo de firma de AWS V4

Integración con Carga de saldo de Amazon

Puede realizar solicitudes simultáneas a estos puntos de enlace de operación especificando la cantidad de fondos que desea cargar. Las operaciones responden a cada solicitud con un estado que indica si la operación ha se ha realizado correctamente o no.

Estas API están disponibles para los socios que tienen un acuerdo contractual con Amazon para crear una solución (normalmente un sistema de punto de venta) para cargar fondos en el saldo del Cheque regalo de un cliente de Amazon.

Amazon Top Up in Store

El servicio de Amazon Top Up in Store (el nombre puede cambiar según el país) permite a los clientes de Amazon cargar fondos en el saldo de su Cheque regalo de Amazon o obtener un código de reclamación de Cheque regalo en tiempo real desde una ubicación física. Esta transacción se inicia dentro de la red del socio de distribución de sitios físicos, que procesa las solicitudes de carga y enruta esas transacciones directamente a Amazon.

Hay dos métodos disponibles para que un cliente represente su cuenta de Amazon en la ubicación física de un socio:

1. Mostrar un código de barras personalizado generado por Amazon que esté vinculado a la cuenta de Amazon del cliente (los clientes obtienen su código de barras de Amazon Top Up in Store de la aplicación de Amazon o del sitio web de Amazon), o
2. Introducir/proporcionar el número de teléfono vinculado a su cuenta de Amazon, en el punto de venta.

Nota: La compatibilidad con los formatos de identificación de cuenta y otros detalles pueden variar según el país.

Además del método de identificación del cliente (es decir, código de barras o número de teléfono), el cliente comunica la cantidad de fondos que desea cargar en su cuenta al asociado de la tienda (mínimo de 5 $ y máximo de 500 $ por carga en los Estados Unidos). Esta información se recopila y luego se transmite a Amazon, quien posteriormente responde con una confirmación o rechazo de la solicitud de carga. Puede utilizar un proceso de solicitud de carga en dos pasos o en un paso como se detalla a continuación.

Incorporación

Para empezar con la integración, consulte la guía paso a paso que se proporciona en Pasos de incorporación de Amazon Top Up in Store.

Cuando se inscriba, recibirá un ID de socio único que distingue entre mayúsculas y minúsculas. Su código incluirá este identificador en todas las solicitudes a la API de Incentives.

Importe mínimo y máximo por transacción por país

Nota: Si su integración es para un país que no aparece en la lista, consulte con su administrador de cuenta los importes de carga mínima y máxima.

Proceso de carga de equilibrio en dos pasos

El proceso de carga de equilibrio en dos pasos implica el uso de dos API: ValidateAccountForAmazonBalanceLoad y LoadAmazonBalance. El proceso típico se describe a continuación:

1. El cajero de la tienda escanea el código de barras de Amazon Top Up in Store del cliente o introduce el número de teléfono del cliente y pregunta cuánto dinero quiere cargar.
2. El cajero introduce el importe en el terminal POS y confirma con el cliente.
3. El POS envía una solicitud ValidateAccountForAmazonBalanceLoad a Amazon. Amazon comprueba los requisitos del cliente para cargar el importe solicitado en su saldo de Cheque regalo de Amazon.
4. Si la respuesta de ValidateAccountForAmazonBalanceLoad confirma la solicitud, el cajero recibe efectivo del cliente y el POS envía la solicitud LoadAmazonBalance a Amazon a través de la red de distribución del socio. Amazon no recomienda activaciones previas a la licitación (es decir, llamar a LoadAmazonBalance antes de que el cajero de la tienda haya recibido dinero).
5. Amazon procesa la solicitud, verificando primero la elegibilidad del cliente y, si es elegible y si se puede identificar la cuenta de Amazon, carga los fondos solicitados en el saldo del Cheque regalo de Amazon del cliente. Se envía una respuesta de confirmación. Si la cuenta no es apta, se devuelve una respuesta de rechazo. En el caso de que el cliente proporcione un número de teléfono para el proceso de carga de saldo, y si ese número de teléfono no puede asociarse a ninguna cuenta de Amazon, la operación responderá con un código de reclamación de Cheque regalo válido. En este caso, el código de reclamación debe estar impreso en el recibo y entregarse al cliente.

Figura 1. Diagrama de proceso de carga de equilibrio en dos pasos

Proceso de carga de equilibrio en un solo paso

Si no tiene la capacidad de enviar una solicitud ValidateAccountForAmazonBalanceLoad como se describe en las instrucciones de los dos pasos anteriores, puede utilizar directamente la solicitud LoadAmazonBalance. Este proceso de carga de equilibrio en un paso se describe aquí:

1. El cajero de la tienda escanea el código de barras de Amazon Top Up in Store del cliente o introduce el número de teléfono del cliente y pregunta cuánto dinero quiere cargar.
2. El cajero introduce la cantidad en el terminal POS, confirma con el cliente y luego recibe el dinero del cliente.
3. El POS envía una solicitud LoadAmazonBalance a Amazon a través de su red.
4. Para gestionar la solicitud, Amazon comprueba si el cliente es apto. Si lo es y si se puede identificar la cuenta de Amazon, Amazon carga los fondos solicitados en el saldo del Cheque regalo del cliente. Se envía una respuesta de confirmación. Si la cuenta no es apta, se devuelve una respuesta de rechazo. Si el cliente proporciona un número de teléfono, pero ese número no puede asociarse a ninguna cuenta de Amazon, la operación responderá con un código de reclamación de Cheque regalo válido. En este caso, el código de reclamación debe estar impreso en el recibo y entregarse al cliente.

Figura 2. Diagrama de proceso de almacenamiento de carga de equilibrio en un paso

Operaciones con ejemplos

Parámetros de solicitud

cuenta

El parámetro account identifica a un cliente final como cliente activo de Amazon.

Esta es una estructura compuesta que consiste en id y type.

id: Identificador único que puede ayudar a Amazon a localizar la cuenta de Amazon de un cliente (para Amazon Top Up in Store, el identificador es un número de código de barras o el número de teléfono del cliente).

Las operaciones admiten dos valores de tipo:

type: Tipo de identificador de cuenta del cliente final. Admite identificadores de clientes como código de barras, número de teléfono, correo electrónico, etc.

partnerId

El parámetro partnerId es un identificador único proporcionado por Amazon durante el proceso de incorporación. Este valor lo asigna el administrador de integración de socios de Amazon e identifica de forma exclusiva a un socio de distribución. Este valor distingue entre mayúsculas y minúsculas.

loadBalanceRequestId

Identificador único que genera para representar una solicitud. Este valor debe tener como prefijo el valor partnerId y debe tener menos de 40 caracteres.

cantidad

El parámetro amount especifica los fondos que se deben cargar. Es un parámetro compuesto que consiste en código de moneda y valor.

• currencyCode: Código de monedaISO-4217.
• value: Valor de la cantidad solicitada. Este campo es un número entero (Ejemplo: 100,23 como 10023). En una moneda que no admite decimales, no se hace falta rellenarlo. Por ejemplo, en Japón, 231 yenes son 231, NO 23100.

timestamp

Marca de tiempo UTC de UNIX en milisegundos desde 1/1/1970 00:00 UTC cuando inició la solicitud.

Ejemplo: 2018-08-23T 15:34:43 + 00:00 se representaría como 1535038483000

voidIfUsed

Valor booleano para indicar si LoadAmazonBalance debe anularse incluso si el cliente final ya ha utilizado los fondos (total o parcial).

Muestra de caso práctico: Si el cliente ya ha utilizado algunos de sus fondos cargados pero se realiza una solicitud nula, revocaremos los fondos restantes del importe original cargado.

Para el ejemplo de uso de Amazon Top Up in Store, este valor siempre debe ser verdadero.

transactionSource

Datos de ubicación para identificar la ubicación en la que se generó la carga de saldo de Amazon. Este parámetro es obligatorio para el producto de Amazon Top Up in Store.

Este parámetro es una combinación de estos componentes:

El valor sourceDetails debe contener la clave institutionName con el valor como nombre de la fuente (por ejemplo, nombre del comerciante). Debe incluirse otra información, como la ubicación de la fuente, el número de teléfono, etc.

El valor institutionName se mostrará en el correo electrónico de fondos añadidos en esta frase: "Se han añadido fondos a su saldo de Amazon en institutionName".

Existen dos opciones para enviar datos de ubicación de la tienda de Amazon.

1. Formulario largo: usted proporciona datos específicos de ubicación de almacén para cada transacción (debe incluir sourceId, institutionId y sourceDetails).
2. Formulario corto: usted proporciona solo el sourceId y el institutionId en la solicitud de la API. Debe enviarse un archivo de mapeo de ubicación independiente para que Amazon pueda analizar los datos.

Instrucciones del archivo de mapeo de ubicaciones.

Nota: Los sourceDetails deben formatearse como un blob de JSON similar a este ejemplo:

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

Para obtener más ejemplos de transactionSource consulte origen físico de la transacción.

Tipo de cuenta de código de barras

Requisitos previos

Para integrarse con el producto de Amazon Top Up in Store y la cuenta de asistencia técnica tipo 1 (basada en código de barras), su sistema POS (punto de venta) debe tener escáneres de código de barras que puedan escanear códigos de barras en teléfonos móviles y admitir códigos de barras 1D en formato Código 128.

Formato de código de barras

Amazon utiliza su propio código de producto y IIN en la creación del código de barras. El código de barras de Amazon tiene 30 dígitos de longitud, compuesto por:

• 11 dígitos UPC
• 13 dígitos EAN o JAN
• 6 dígitos IIN
• 12 dígitos PAN
• Suma de comprobación de 1 dígito

Amazon utiliza el algoritmo LUHN, que se aplica al IIN + PAN, para generar el dígito de suma de comprobación.

A continuación encontrará el código de producto de Amazon (UPC/EAN/JAN) y el IIN, además de un ejemplo de código de barras. Tenga en cuenta que el código de producto varía según el país.

Código de producto (UPC 11, EAN 13, JAN 13)

1. Número de identificación global del emisor (IIN): 608574

Figura 3.1a Ejemplo de código de barras: 30 dígitos

Figura 4.1b Ejemplo de código de barras: 32 dígitos

Tipo de cuenta de número de teléfono

Requisitos previos

El número de teléfono es otro tipo de cuenta compatible (tipo 4). Para integrarlo con el producto Amazon Top Up in Store y que se admita el tipo de cuenta de número de teléfono, el sistema POS debe permitir que el operador introduzca los dígitos del número de teléfono e imprima un recibo con un código de reclamación dinámico. En determinados escenarios, la transacción de Amazon Top Up in Store debe devolver un recibo en papel que contenga un código de reclamación dinámico que el cliente pueda utilizar en línea más adelante para abonarlo a su cuenta.

Formato de número de teléfono

La entrada del número de teléfono debe cumplir cualquiera de los siguientes formatos:

Los números E.164 pueden tener un máximo de quince dígitos y tienen el siguiente formato:

[ +] [código de país] [número de abonado, incluido el código de área]   

Por ejemplo, +14155552671 (Número EE. UU.), +442071838750 (Número RU).

Es preferible que nos envíe números de teléfono en formato E.164.

Nota: Actualmente, solo aceptamos el uso de un número de teléfono local en la nación correspondiente desde la que se realiza la transacción. Por lo tanto, si un cliente intenta usar un número de teléfono mexicano en un quiosco o tienda de EE. UU., la transacción será rechazada en el POS.

Requisitos de recepción

Los requisitos de recepción difieren en función de la capacidad de los sistemas POS para cambiar el contenido según si la llamada LoadAmazonBalance de la carga basada en el factor de forma del teléfono aplicó los fondos a la cuenta del cliente (número de teléfono verificado) o emitió un código de reclamación (número de teléfono no verificado).

Texto de instrucción predeterminado

Si el sistema POS no puede cambiar el contenido del recibo, debe aparecer este texto:

Guarde este recibo hasta que reciba la confirmación de que se han añadido fondos a su saldo de Amazon. Si los fondos no se han aplicado automáticamente a su cuenta, puede visitar www.amazon.com/gc/redeem para completar la transacción. Las transacciones de Amazon Top Up in Store no son reembolsables, excepto cuando lo exija la ley. Se aplican otras restricciones. Para ver los términos y condiciones completos, consulte www.amazon.com/gc-legal.

ValidateAccountForAmazonBalanceLoad

La operación ValidateAccountForAmazonBalanceLoad se valida si el importe previsto está dentro del intervalo permitido en este país y se comprueba que la cuenta de Amazon de un cliente es apta para el proceso de carga de saldo.

Para el tipo de cuenta de código de barras, se comprueba que el código de barras esté vinculado a una cuenta de cliente de Amazon activa y esté aprobado para añadir fondos al saldo de su Cheque regalo de Amazon.

Para el tipo de cuenta de número de teléfono, se comprueba que el número de teléfono proporcionado sea válido. Si se puede verificar que el número de teléfono está vinculado a una cuenta de cliente de Amazon, también se validará el estado de elegibilidad del cliente. De lo contrario, la validación NO rechazará el número de teléfono no identificado (que no esté vinculado a ningún cliente de Amazon) y lo tratará como una cuenta válida. La operación responderá con un PARTIAL_SUCCESS en este caso. Para estos números de teléfono no verificados, la operación LoadAmazonBalance devolverá un código de reclamación para que el cliente lo canjee más adelante manualmente.

Nota: Se prefiere esta operación, pero NO es un requisito previo para realizar una operación correcta de LoadAmazonBalance más adelante.

  Parámetros de solicitud

Figura 5 Parámetros de solicitud ValidAccountForAmazonBalance

Respuesta positiva, respuesta positiva parcial

Figura 6 Respuesta positiva ValidAccountForAmazonBalanceLoad

Respuesta de error

Estas cadenas obligatorias aparecen en ValidateAccountForAmazonBalanceLoadException:

• errorCode
• errorType
• errorMessage
• status  

  Ejemplo 1: Solicitud y respuesta positiva para la cuenta de tipo código de barras

Solicitud

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>

Respuesta

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

Ejemplo 2: Solicitud y respuesta positiva para la cuenta de tipo número de teléfono

Solicitud

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>

Respuesta

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

Ejemplo 3: Solicitud y respuesta Parcial_Success para la cuenta de tipo número de teléfono

Solicitud

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>

Respuesta

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

Ejemplo 4: Respuesta de error

Respuesta de error

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

Ejemplo 5: Error de reenvío de respuesta

Respuesta de error

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

Un error F400 requiere una gestión cuidadosa de reintentos para garantizar que no se produzcan desembolsos no deseados. Consulte Gestión de errores.

Ejemplo 6: Comparación de respuestas (para tipos de códigos de barras y números de teléfono)

Respuestas para tipo de número de teléfono (valor de tipo 4) cuando el número de teléfono se ha verificado

Teléfono verificado (teléfono vinculado a la cuenta de Amazon y verificado)

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

Teléfono no verificado (teléfono NO verificado/perteneciente a la cuenta de 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>

Respuestas para tipo de código de barras (valor de tipo 1)

Código de barras válido/activo

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

Código de barras invalido/inactivo

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

LoadAmazonBalance

La operación LoadAmazonBalance carga fondos en el saldo del Cheque regalo de Amazon de un cliente o devuelve un código de reclamación de Cheque regalo válido (en el caso de que el número de teléfono especificado no esté verificado, es decir, que no se haya verifique en una cuenta de Amazon). Esta operación es idempotente, en el sentido de que si Amazon recibe varias solicitudes de LoadAmazonBalance con el mismo loadBalanceRequestId con todos los parámetros coincidentes (account, partnerId, amount y transactionSource), se devolverá la misma respuesta de la primera llamada. El loadBalanceRequestId que proporcione puede tener una longitud máxima de 40 caracteres, debe tener el prefijo de partnerId, y debe ser único.

Parámetros de solicitud

Figura 8 Parámetros de LoadBalanceRequest

Respuesta positiva para el tipo de cuenta de código de barras

Figura 9 LoadBalanceResponse positiva

Respuesta positiva para el tipo de cuenta de número de teléfono

Parámetros de respuesta de LoadAmazonBalance

El campo additionalInfo es texto en formato JSON y contiene información un código de reclamación. Consulte el ejemplo para obtener más detalles.

Respuesta de error

LoadAmazonBalanceException incluye 4 parámetros de cadena:

• errorCode
• errorType
• errorMessage
• status

Ejemplo de respuesta de error de LoadAmazonBalance:

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

Ejemplo 1: Solicitud de LoadAmazonBalance y respuesta positiva para la cuenta de tipo código de barras

Solicitud

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>

Respuesta

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

Ejemplo 2: Solicitud de LoadAmazonBalance y respuesta positiva (tipo de cuenta de número de teléfono) con un número de teléfono no verificado (el código de reclamación debe reclamarse manualmente)

Solicitud

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>

Respuesta positiva

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

Respuesta de error

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

Ejemplo 3: Solicitud de LoadAmazonBalance y respuesta positiva (tipo de cuenta de número de teléfono) con un número de teléfono verificado (fondos aplicados/reclamados automáticamente)

Solicitud

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>

Respuesta

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

Ejemplo de respuesta de error de LoadAmazonBalance:

Respuesta de error

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

Ejemplo de respuesta de reenvío de LoadAmazonBalance:

Respuesta de error

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

Requisitos adicionales en emplazamientos físicos

Cada llamada a LoadAmazonBalance que se realice en una ubicación física debe incluir detalles de la ubicación en la que se produjo la transacción. Las solicitudes a estos puntos de enlace pueden incluir un objeto transactionSource que describe la ubicación física del evento.

Nota: LoadAmazonBalance utilizado con Inicio de sesión y recepción no debe incluir un objeto transactionSource.

Existen dos opciones para enviar datos de ubicación de tienda a Amazon:

1. Formulario largo: el socio proporciona datos específicos de ubicación del almacén para cada transacción (debe incluir sourceId, institutionId y sourceDetails)
2. Formulario corto: el socio proporciona solo el sourceId y el institutionId en la solicitud de la API. Debe enviarse un archivo de mapeo de ubicación independiente que asigne estos identificadores a ubicaciones físicas. Consulte las instrucciones del archivo de mapeo de ubicaciones en esta hoja de cálculo.

A continuación se muestra un ejemplo de carga de "formulario largo" para el origen de la transacción en formato XML y JSON. Tenga en cuenta que sourceDetails debe formatearse como un blob de JSON. En el ejemplo JSON, el blob de JSON utiliza la barra invertida para evitar las comillas.

Ejemplo de formulario largo del cuerpo XML (tenga en cuenta que el valor sourceDetails debe formatearse como un blob de 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>

Ejemplo de formulario corto de transactionSource en el cuerpo 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

Cuando un POS no puede garantizar que una solicitud se haya ejecutado correctamente, por ejemplo, debido a un mensaje perdido por problemas de red, el POS y/o el socio de distribución deben ejecutar una solicitud VoidAmazonBalanceLoad para asegurarse de que no se añadirán los fondos. al saldo del Cheque regalo de Amazon del cliente. En caso de error en el POS, el cajero siempre devuelve el efectivo al cliente final. Por lo tanto, la importancia de la anulación consiste en garantizar que los fondos se retiren rápidamente del saldo del Cheque regalo de Amazon del cliente en caso de que los fondos se hayan añadido correctamente pero el POS nunca recibiera el mensaje de confirmación.

La operación VoidAmazonBalanceLoad anulará una solicitud LoadAmazonBalance correcta en un plazo de 15 minutos a partir de la solicitud original. El LoadBalanceRequestID original utilizado para cargar fondos de una solicitud LoadAmazonBalance positiva es necesario para la operación de anulación. Los campos currencyCode, value, sourceId e institutionId deben coincidir con los valores respectivos proporcionados en la solicitud LoadAmazonBalance original. La operación de anulación es idempotente.

Parámetros de solicitud

Figura 12 Diagrama de solicitud VoidAmazonBalanceLoad

Respuesta positiva

Figura 13 Diagrama de respuesta positiva de VoidAmazonBalanceLoad

Respuesta de error

Cuando la solicitud de anulación falla, se devuelve una excepción VoidAmazonBalanceLoad con estos parámetros de cadena:

• errorCode
• errorType
• errorMessage
• status

Ejemplo 1: Solicitud de VoidAmazonBalanceLoad y respuesta positiva (tipo de cuenta de código de barras):

Solicitud

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>

Respuesta

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

  Ejemplo 2: Solicitud de VoidAmazonBalanceLoad y respuesta positiva (tipo de cuenta de número de teléfono):

Solicitud

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>

Respuesta

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

Ejemplo 3: Ejemplo de respuesta de error de VoidAmazonBalanceLoad:

Respuesta de error

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

Ejemplo 4: Ejemplo de respuesta de reenvío de VoidAmazonBalanceLoad:

Respuesta de error

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

Datos de prueba

Para ayudar con las pruebas durante el desarrollo, hemos creado cuentas de prueba (amazon.com). Hay cuentas independientes disponibles para los entornos Sandbox y Production. Vea estos tokens en https://s3.amazonaws.com/AGCOD/tech_spec/amazon-test-tokens.txt.

Consulte también los códigos de simulación que puede usar para probar cómo su código gestiona los errores de solicitud comunes.

Firmas digitales: proceso de firma

Cada solicitud a una operación de la API de Incentives debe estar firmada digitalmente utilizando sus credenciales de seguridad de la API de Incentives y el algoritmo de firma Signature Version 4.

Ejemplo de firma de AWS V4

(en la región us-east-1 )

Carga para firmar:

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

Carga hash

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Solicitud canónica (incluir líneas vacías)

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

Solicitud canónica hash

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Cadena para firmar

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

Clave de firma derivada

 780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Firma

(Su firma será diferente ya que tiene credenciales de AWS diferentes).

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a  

Carga firmada

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