Documentación - Arcus APIv3.mx

Bienvenido a la API de Arcus, aquí encontrarás la documentación completa donde podrás consultar información detallada acerca de la API de Arcus. La presente documentación se complementa con la sección de endpoints. Contiene información de todos los endpoints y es la mejor forma de saber que se necesita enviar y qué se va a recibir en cada llamada que se realice.

Ambientes

Arcus proporcionará llaves API separadas para nuestros dos ambientes disponibles:

• Sandbox. Arcus mantiene un Sandbox que permite a los desarrolladores probar la API utilizando datos simulados. Recomendamos tener en cuenta que la lista de billers o proveedores del Sandbox no está sincronizada con la lista de billers en producción.

  Para realizar llamadas al ambiente Sandbox, se debe usar la siguiente URL: https://api.staging.arcusapi.com

• Producción. Una vez que se hayan realizado todas las pruebas necesarias en el Sandbox, contáctenos para recibir sus llaves de producción.

  Para realizar llamadas al ambiente de producción, se debe usar la siguiente URL: https://api.arcusapi.com

Seguridad

Para realizar llamadas a nuestros endpoints, se debe utilizar el protocolo HTTPS , independientemente del ambiente que se esté utilizando.

Cabeceras HTTP de Seguridad

Todas las respuestas regresan las siguientes cabceras de seguridad.

• X-Frame-Options
• X-Content-Type-Options
• Strict-Transport-Security
• Content-Security-Policy
• Referrer-Policy
• Cache-Control
• Feature-Policy
• Cross-Origin-Embedder-Policy
• Cross-Origin-Resource-Policy
• Cross-Origin-Opener-Policy

Autenticación

La API de Arcus tiene una forma muy específica de autenticación, la cual se basa en la dirección y los encabezados o headers HTTP de cada llamada que se realiza. Cada llamada debe contener los siguientes encabezados:

• Accept: El tipo de MIME que es aceptado en la respuesta. (MIME: Multipurpose Internet Mail Extensions o Extensiones Multipropósito de Correo de Internet)
  Para todas las llamadas, siempre se deberá mandar como: application/vnd.regalii.v3.mx+json
• Content-Type Indica el tipo de MIME del cuerpo enviado al recipiente.
  Siempre se deberá mandar como: application/json.
• Date Representa la fecha y hora en la que el mensaje fue creado. El formato de este encabezado se especifica en RFC 822 Sección 5.
  Por ejemplo: Wed, 01 Aug 2018 17:26:52 GMT
• Authorization Credenciales de autenticación Este encabezado tiene el siguiente formato:
  APIAuth <your-api-key>:<checksum>
• Content-MD5 (Opcional). Es la suma de verificación del cuerpo de la llamada, el cual tiene el propósito verificar la integridad del mensaje (MIC) de endpoint a endpoint del cuerpo de la llamada.

Como lo indica su descripción, el encabezado de Autenticación es la forma de identificarse en la API de Arcus, y está compuesto de la siguiente forma: la llave de API (API Key) y una suma de verificación (checksum) la cual se compone del endpoint, los encabezados HTTP y la clave secreta (secret Key).

En la siguiente sección, aprenderá a calcular el <checksum> el cual deberá usarse en todas las llamadas a la API.

Calculando la suma de verificación (checksum)

Paso 1

La suma de verificación o (<checksum-string>) se genera usando los siguientes encabezados HTTP:

• Content-Type
• Content-MD5
• Date

Y el Endpoint al que quieres acceder. El checksum se conforma de la siguiente forma:

<checksum-string> = "<Content-Type>,<Content-MD5>,<Endpoint>,<Date>"

Por ejemplo, si tenemos los siguientes datos:

<Content-Type> = "application/json"
<Content-MD5>  = ""
<Endpoint>     = "/account"
<Date>         = "Wed, 01 Aug 2018 17:26:52 GMT"

Entonces el checksum quedaría:

<checksum-string> = "application/json,,/account,Wed, 01 Aug 2018 17:26:52 GMT"

Paso 2

<checksum> es un HMAC codificado en Base64. El HMAC usa un SHA-1 como función hash y <your-secret-key> como llave criptográfica.

Puedes usar OpenSSL para calcular el checksum. En shell:

echo -n "<checksum-string>" \
  | openssl dgst -sha1 -binary -hmac "<your-secret-key>" \
  | base64

Por ejemplo. Si tenemos los siguientes datos:

<checksum-string> = "application/json,,/account,Wed, 01 Aug 2018 17:26:52 GMT"
<your-secret-key> = "your-secret-key"

Quedaría de la siguiente manera: PbYMLSKsXhplSStqyySn63UFEc8=

Realiza una llamada al endpoint de /account para verificar tus credenciales.

Llave de Idempotencia

Descripción

Los métodos PUT y DELETE están definidos para ser idempotentes, también los métodos GET, HEAD, OPTIONS y TRACE están definidos como seguros, lo que significa que sólo están destinados a recuperar datos. Esto los hace también idempotentes ya que múltiples peticiones idénticas se comportarán igual.

Por otro lado, POST intrínsecamente no es idempotente, generalmente (no necesariamente) POST se utiliza para crear un nuevo recurso en el servidor. Así que cuando se invoca la misma solicitud POST N veces, tendrá N nuevos recursos en el servidor. Por lo tanto, POST no es idempotente por definición.

Sin embargo, la API de Arcus admite la idempotencia de POST, lo que le permite reintentar una solicitud varias veces mientras sólo realiza la acción una vez. Esto ayuda a evitar la duplicación no deseada en caso de fallos y reintentos.

Por ejemplo, en el caso de un error de tiempo de espera, es posible reintentar con seguridad el envío de la misma llamada de pago de la API varias veces con la garantía de que el pago sólo se cobrará una vez.

Use cases

Arcus API supports idempotency allowing you to retry a request multiple times while only performing the action once. This helps to avoid unwanted duplication in case of failures and retries.

Por ejemplo, en el caso de un error de tiempo de espera, es posible reintentar con seguridad el envío de la misma llamada de pago de la API varias veces con la garantía de que el pago sólo se cobrará una vez.

Implementación

La API de Arcus V3.mx, soporta la idempotencia en las solicitudes POST, el uso de esta característica es opcional, para habilitar esta funcionalidad solo deberá agregar un nuevo encabezado a su solicitud POST llamada. Idempotency-Key

Reglas que implementan la llave de idempotencia para la API de Arcus:

• La longitud máxima admitida para la llave de idempotencia será de 36 dígitos
• La longitud mínima admitida para la llave de idempotencia será de 12 dígitos
• Recomendamos utilizar el UUID de la versión 4 para dicha llave de idempotencia
• La llave de idempotencia expirará después de 24 horas de haber sido creada

Haciendo una llamada a la API

El endpoint /account obtendrá la información de tu cuenta. Es una excelente manera de aprender como mandar solicitudes a Arcus. En el siguiente ejemplo, haremos uso de la herramienta curl

En un script de Shell escribe el paso 1 y 2:

1. Genera la suma de comprobación o checksum reemplazando <your-secret-key> con la clave secreta proporcionada por Arcus.

CURRENT_DATE=`date -Ru | sed 's/+0000/GMT/'`
CHECKSUM=$(echo -n "application/json,,/account,$CURRENT_DATE" \
  | openssl dgst -sha1 -binary -hmac "<your-secret-key>" \
  | base64)

2. Envía tu solicitud al entorno deseado. Reemplaza <your-api-key> con la llave API proporcionada por Arcus.

curl -X GET "https://api.staging.arcusapi.com/account" \
  -H "Accept: application/vnd.regalii.v3.mx+json" \
  -H "Content-Type: application/json" \
  -H "Content-MD5:" \
  -H "Date: $CURRENT_DATE" \
  -H "Authorization: APIAuth <your-api-key>:$CHECKSUM"

3. Ejecuta el script. El servidor responderá con un objeto JSON. Utiliza esta información de acuerdo a tus necesidades.

{
  "name" : "John Smith",
  "balance" : 956.33,
  "minimum_balance" : 81645.24
}

Códigos de país, códigos de moneda y formato de fecha y hora

Los códigos de país y moneda, así como el formato de fecha y hora utilizados en esta API, están especificados de acuerdo con los estándares ISO.

• Códigos de país: ISO 3166-1 alpha-2. Por ejemplo, el códigoMX coincide con México.
• Códigos de moneda: ISO 4217. Por ejemplo, el códigoMXN coincide con el peso mexicano.
  Nota: ISO publica los códigos de moneda en formato XML y XLS.
• Formato de fecha y hora: La fecha y hora se almacenan en formato ISO/WD 8601 YYYY-MM-DDThh:mm:ssZ (Esto de acuerdo a la representación completa ampliada del formato de fecha y hora del día).
  Ejemplo: Si se realiza un pago el 16 de julio de 2018 a las 12:47:57 en la Ciudad de México, se guarda como 2018-07-16T17:47:57Z.

Almacenamiento de datos en caché

Para asegurarte de que tus clientes puedan aprovechar las últimas actualizaciones que se van implementando, debes almacenar en caché la lista completa de billers y actualizarla semanalmente. Para realizar esta tarea, Arcus proporciona una lista de billers en los endpoints proporcionados. Sincroniza periódicamente esta información con tu base de datos local.

Endpoints:

• GET /billers/utilities
• GET /billers/topups
• GET /billers/gift_cards
• GET /billers/arcuspay

El tipo de cambio que se aplicará al bill o factura será proporcionado por nosotros. Estas tarifas cambian diariamente a las 5 a.m. EST. Es necesario que almacenes esta información en caché todas las mañanas entre las 6 y las 7 a.m. EST.

Endpoints:

• GET /rates

Paginación

Las consultas a algunos endpoints como /billers/*, /bills y /transactions tienen bastantes resultados, por lo que estos resultados se dividen en páginas. Puedes gestionar la paginación utilizando el encabezado X-Pagination y solicitando las páginas siguientes. Para obtener más información, consulta el modelo de paginación en la sección de endpoints.

Flujos de pago

Existen 4 flujos de pago dependiendo de las siguientes características del biller:

• can_check_balance: Permite consultar un saldo
• supports_partial_payment: Acepta pagos parciales.

Webhooks

Arcus ofrece webhooks que pueden usarse para recibir notificaciones cuando hay actualizaciones en algún estado de cuenta (bill) o una transacción.

¿Cuándo se envían los webhooks?

Los webhooks se envían cuando hay cambios en un objeto bill:

• Arcus ha vuelto a reenviar el bill debido a un error previo o una interrupción del servicio.

¿Cómo registrar un webhook?

Los webhooks se envían cuando hay cambios en un objeto bill:

Información en los Webhook

Los webhooks regresan la misma información que se recibe al momento de crear una factura (bil) o una transacción.

Lidiar con timeouts

Un timeout es cuando se realiza una llamada a la API y no se recibe ninguna respuesta del servidor después del tiempo estipulado (60 segundos). Es raro experimentar un timeout al llamar a nuestro servidor, pero puede llegar a ocurrir. Se pueden lidiar con los timeouts durante la creación y el pago de bills (estados de cuenta).

Timeout en la creación

Los bills no se pueden duplicar, por lo que cualquier solicitud para volver a crear un bill responderá con el bill creado anteriormente.

Timeout durante el pago

Todas las llamadas a POST /bills/{id}/pay deben incluir un identificador externo o external_id el cual deberá contener un identificador único generado en tu sistema, este se almacenará junto con la información de la transacción en caso de que se haya procesado con éxito. Recomendamos utilizar UUID para este parámetro.

Si se llegara a experimentar un timeout, se puede realizar una llamada a GET /transactions con el parámetro de consulta q[external_id_eq], el cual debe incluir elexternal_id enviado al endpoint de pago. Si al realizar esta llamada se obtienen datos de regreso, quiere decir que Arcus recibió la solicitud de pago de manera exitosa. De lo contrario, habrá que volver a realizar el pago.

Integración

Se puede la integración haciendo llamadas a nuestro sandbox.

Todas las llamadas realizadas al entorno de Sandbox son de simulación, por lo que hay un resultado previsto para todos los escenarios. Debido a que todas las respuestas en el servidor Sandbox son simuladas, se pueden realizar todas las llamadas necesarias para completar las pruebas que se requieran.

El objetivo de esta sección es asegurarnos de que se han manejado todos los diferentes escenarios que pueden surgir.

Autenticación y Primera Solicitud

Objetivo

Obtener información sobre su cuenta.

Referencias:

• Autenticación
• Endpoint GET/account

Se requieren los encabezados de autenticación correspondientes para obtener acceso a la API de Arcus. Se puede generar un comando curl correctamente estructurado en nuestro sitio de endpoints.

Sin embargo, si se desea implementar manualmente, se deberán seguir los pasos descritos en la sección Autenticación.

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Proporciona el saldo devuelto.

Sincronización de billers

Objetivo

Almacenar en la memoria caché la información sobre los billers que proporciona Arcus. Se deberán actualizar los billers que figuran en tu base de datos utilizando los endpoints correspondientes.

Referencias:

• Utility billers
• Top-up billers
• Gift card billers
• Arcuspay billers

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Verifica que el número de billers en tu base de datos local corresponda con el número de registros devueltos en el feed de billers.
• Verifica que todos los billers sean accesibles para el cliente desde tu interfaz de usuario.
• Verifica que haya una forma rápidasencilla de filtrar la lista de billers.
• Gestiona la paginación utilizando el encabezado X-Pagination y solicitando las páginas subsecuentes.

Creación de un bill

Objetivo

Crear una factura en Arcus ligada a un número de cuenta. Los números de cuenta se solicitan principalmente para realizar pagos sin proporcionar información personal.

Referencias:

• Billers endpoints

Ejecución:

{
  "biller_id": 8925,
  "account_number": "1234567"
}

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Recibir un código de respuesta: 200
• Recibir el id del Bill
• Recibir el estado de un Bill (vinculado)

Obtener todos los bills

Objetivo

Obtener la información de todos los bills.

Referencias:

• Endpoint GET /bills

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Gestionar la paginación utilizando el encabezado X-Pagination y solicitando las páginas subsecuentes.

Mostrar un bill

Objetivo

Obtener información de un bill en específico

Referencias:

• Endpoint GET /bills/{id}

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Obtener la información del bill que se está consultando.

Información adicional de un bill

Objetivo

Obtener información adicional de un bill, este endpoint se puede utilizar si el parámetro has_xdata del bill así lo indica. has_xdata.

Referencias:

• Endpoint GET /bills/{id}/xdata

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Obtener la información adicional del bill que se está consultando

Actualizar un bill

Objetivo

Actualizar la información del balance de un bill existente (o de uno nuevo).

Referencias:

• Endpoint POST /bills/{id}/refresh

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Verificar que el balance ha cambiado (recuerda que estos datos son aleatorios en el ambiente de pruebas)

Eliminar un bill

Objetivo

Eliminar un bill usando su ID como referencia.

Referencias:

• Endpoint DELETE /bills/{id}

Ejecución:

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Obtener toda la información del bill
• Realizar una llamada posterior al endpoint GET /bills donde se corrobore que ya no aparece este bill

Pagos

Esta sección solo debe realizarse si se planea realizar el pago de bills a través de la API de Arcus.

Objetivo

Realizar el pago exitoso del bill de un cliente.

Referencias:

• Endpoint POST /bills/{id}/pay

Ejecución:

{
  "amount": <amount>,
  "currency": "<currency>",
  "external_id": "<uuid>"
}

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

Obtener un código de respuesta 200 y la confirmación del pago

Pagos Únicos

Adicionalmente, se pueden realizar operaciones simples con bills como: pago de bills, y en el caso de estados de cuenta de servicios, se puede consultar la información de estos bills.

Consultar un bill

Objetivo

Consultar un bill de servicios públicos en Arcus utilizando un número de cuenta como referencia. Los números de cuenta se solicitan principalmente para realizar pagos sin proporcionar información personal.

Referencias:

• Endpoint GET /billers/utilities
• Endpoint POST /single/consult

Ejecución:

{
  "biller_id": 1471,
  "account_number": "127892"
}

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200
• Obtener el balance del bill contenida en el parámetro bill_amount
• Obtener la divisa del bill contenida en el parámetro bill_amount_currency

Pagar un bill

Objetivo

Realizar un Cash out a una cuenta.

Referencias:

• Endpoint POST /single/cash_out

Ejecución:

{
  "biller_id": 1471,
  "account_number": "127892",
  "amount": <amount>,
  "currency": "MXN",
  "external_id": "<uuid>"
}

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200

Conciliación

Transacciones

Para realizar el proceso de conciliación de tus transacciones con las registradas por Arcus, necesitas mandarnos un archivo CADA DÍA ENTRE LAS 4 AM CST y 5 AM CST con la lista de las transacciones realizadas el día anterior, incluso si no se realizó ningún pago.

Instrucciones

1. Se deberá subir el archivo en el formato especificado a continuación, a nuestro servidor SFTP a las 4 AM CST. Se procesará dicho registro, conciliándolo con los registros que tenemos en nuestro propio servidor y se enviarán los resultados a las 5 AM CST.
2. El archivo deberá tener un registro por cada transacción realizada por tu negocio o comercio, se deben incluir las transacciones desde la medianoche del día en curso hasta la medianoche CST del día anterior. Es muy importante tener en cuenta el horario de verano debido a que Arcus se ajusta automáticamente a CDT.
   Las diferencias en las zonas horarias al generar archivos de transacciones pueden dar lugar a diferencias de reconciliación. El archivo debe cargarse todos los días de la semana, incluyendo fines de semana.
3. En caso de no tener transacciones, el archivo solo contendrá el encabezado y el pie de página indicando que hay 0 registros.
4. Se enviará un correo electrónico con los resultados de la conciliación, describiendo las diferencias entre nuestros registros indicando cuáles transacciones incluidas en el archivo cargado estaban presentes en nuestros registros, y cuáles transacciones que se encontraron en nuestros registros no se incluyeron en el archivo.
5. Las credenciales para ingresar al servidor SFTP se proporcionarán durante el proceso de certificación.

Formato del archivo

A continuación se muestra un ejemplo de cómo debe quedar el archivo de conciliación. El archivo describe las transacciones realizadas por un negocio con el nombre “chain”, que realizó 2 transacciones el 8 de agosto de 2018:

HEADER|20180809
REGISTER|2018-08-08T17:09|40|177467|501000000007|185.00|MXN|S12C03|bcc2263d-9918-4df9-b948-035c60c81cce
REGISTER|2018-08-08T19:25|40|177468|501000000008|968.00|MXN|S12C03|635f468c-0dc1-4f50-83c6-04471bdf726f
FOOTER|2

Nombre del archivo

El nombre del archivo de conciliación debe tener el siguiente formato:

En dónde:

• chainname: es el nombre de tu negocio.
• YYYYMMDD: fecha de creación del archivo en zona horaria UTC. La fecha se representa de la siguiente manera:
  • YYYY: año en 4 dígitos
  • MM: mes del año a dos dígitos
  • DD: día del mes a dos dígitos

Formato de archivo

El archivo de conciliación es un archivo separado por pipe con el formato descrito a continuación. Utilice una barra vertical (pipe) | como separador de campo.

1. La primera línea debe ser un header o encabezado, con la fecha de creación.

2. Después de la línea de encabezado, debe incluir cero o más líneas de registro, cada línea debe contener la información de una transacción en el siguiente diseño.

3. La última línea del archivo es el footer o pie de página, y contiene un resumen de todas las transacciones con el siguiente formato.

Cash Out

Objetivo

Realizar un pago único de cualquier bill.

Referencias:

• Endpoint POST /single/pay

Ejecución:

{
  "biller_id": 13621,
  "account_number": "256863285",
  "amount": 12.21,
  "currency": "MXN",
  "external_id": "84bce950-c878",
  "pos_number": "S12C03",
  "cashier_id": "CASH956"
}

Llamada exitosa:

Para confirmar que la llamada fue exitosa se deben validar los siguientes puntos:

• Obtener un código de respuesta: 200

Códigos de error

Códigos de error HTTP

La API de Arcus utiliza los siguientes códigos de estado de respuesta HTTP.

Códigos de error de la API de Arcus