Tutorial- Arcus APIv3.mx

¡Bienvenido al tutorial de la API de Arcus! Es una guía rápida de la API de Arcus, en donde aprenderás las bases para realizar llamadas a los endpoints de la API de Arcus, donde podrás obtener información de los billers, de las bills y realizar transacciones.

No olvides revisar las secciones de Documentación y Endpoints para tener la referencia completa.

Lenguajes compatibles

¡Tenemos compatibilidad con multiples lenguajes de programación!

• Ruby
• Java
• node.js
• Python
• PHP

Conceptos Básicos

Antes de realizar llamadas a la API de Arcus, es importante familiarizarse con algunos términos:

• Biller o proveedor. Cualquier compañía que ofrezca algún servicio a un usuario final. (Por ejemplo: CFE, Sky, Telmex). Hay dos tipos de billers:
• Utility o de servicios. Es una compañía que ofrece un servicio como: televisión por cable, electricidad, servicios gubernamentales, internet, teléfono, etc.
• Top-up o Pre-Pago. Es una compañía que acepta el pago de montos fijos, como recargas de celular (por ejemplo: Claro, AT&T, Telcel, Movistar).
• Gift card o tarjetas de regalo. Es una compañía que proporciona tarjetas de regalo como Netflix o Uber.
• Arcuspay. Es una compañía que pertenece a la red Arcuspay.
• Bill o estado de Cuenta. Son los gastos que debe pagar el usuario final a un biller los cuáles deben ser cubiertos de forma periódica.
• Transacción. Todos los pagos que fueron procesados por Arcus.

Para todas las llamadas:

• Necesitas un par de llaves para cada ambiente
• Los Headers o encabezados son obligatorios
• Los parámetros se especifican en JSON dentro del body o cuerpo de la llamada.

Ambientes, credenciales y herramientas

Arcus proporcionará dos llaves de API o API Keys de manera separada para nuestros dos ambientes:

• Sandbox. Ambiente de prueba con datos simulados.
• Production o Producción. Credenciales y datos reales.

Para efectos de este tutorial, realizaras llamadas a nuestro Sandbox usando la siguiente URL: https://api.staging.arcusapi.com

Podrás encontrar más información acerca de los ambientes dentro de nuestra documentación..

El par de llaves proporcionadas por Arcus son una llave para autenticarse en la API y una clave secreta, en este tutorial las llamaremos <your-api-key> y <your-secret-key> respectivamente.

Herramientas de Prueba

Para este tutorial, únicamente necesitarás una terminal Shell, nuestra herramienta de endpoints y las siguientes dos herramientas para probar los endpoints y sus respuestas. Revisa la documentación de cada herramienta para más información sobre cómo instalarlas.

• OpenSSL (Generar cadena de autenticación)
• curl (Hacer peticiones a la API)

Flujo Básico

El flujo básico de la API de Arcus consiste en 4 sencillos pasos que se deben realizar para llevar a cabo tu integración con nuestra API.

1. 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:

Como habrás adivinado, el encabezado Authorization es la forma de autenticarte en la API de Arcus, y está compuesto de la siguiente forma: tu llave API (API Key) y una suma de verificación mejor conocida como checksum, la cual se compone del endpoint, los encabezados HTTP y tu clave secreta (secret Key).

En la siguiente sección aprenderás como generar el <checksum> para todas tus llamadas a la API.

Calculando la suma de verificación (checksum)

Paso 1

Primero hay que crear la cadena o string (la cual llamaremos<checksum-string>) con los encabezados o headers Content-Type, Content-MD5 , Date y el Endpoint al que quieres acceder, en el siguiente orden:

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

Nuestro checksum quedaría de la siguiente manera:

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

Paso 2

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.

2. Crear un bill

Antes de poder realizar cualquier tipo de pago, es necesario crear un Bill. Esto se realiza en el endpoint POST /bills.

Para poder crear un bill se requieren por lo menos dos parámetros:

• biller_id El ID del biller o servicio que se va a pagar.
• account_number El número de cuenta del cliente. La longitud de este número depende del biller o servicio que se vaya a pagar.

Para más información acerca de los parámetros, revisa la documentación relacionada con el endpoit POST /bills

Ejemplo:

En POST /bills endpoint, el cuerpo de la solicitud debe seguir la siguiente estructura. Para este ejemplo: 13621 Y la solicitud de URL al servidor sandbox será::

{
  "biller_id": 13621,
  "account_number": "256863285"
}

Reemplaza el número de cuenta contenido en account_number id , lo necesitarás para realizar un pago. Por ejemplo, este id será: 01CCXHE663RJ55CBJPDK2N86C3.

3. Realiza un pago

Después de que hayas creado un bill, podrás realizar pagos concernientes a ese bill. Si quieres realizar pagos usando la API de Arcus, usa el endpoint POST /bill/{id}/pay, para ello, necesitarás al menos, indicar los siguientes parámetros:

• id: Es el bill id correspondiente, se coloca en la dirección o path.
• amount: Cantidad a pagar de este bill. Si el biller no acepta pagos parciales, entonces de deberá cubrir el monto del adeudo por completo.
• currency: La divisa o el tipo de moneda que se está usando al realizar el pago.
• external_id: Tu id propio para identificar estas transacciones. Es recomendable usar UUID.

Se puede agregar un parámetro adicional de manera opcional, con el fin de agregar un identificador interno controlable por ustedes:

• pos_number: Tu id único para identificar la terminal o la sucursal en donde se realizó la transacción.

Para más información de estos parámetros, consulta la documentación correspondiente al endpoint POST /bills/{id}/pay

Ejemplo

En POST /bills/{id}/pay endpoint, realiza un pago con el id de la cuenta que creamos en el paso anterior, el cuerpo de la llamada deberá tener la estructura que se muestra en el siguiente ejemplo, el cuál quedaría de la siguiente forma:

{
  "amount": 52.45,
  "currency": "MXN",
  "external_id": "84bce950-c878",
  "pos_number": "S12C03"
}

Y la solicitud URL al servidor Sandbox sería:

Recibirás toda la información asociada con esta transacción. Para el proceso de reconciliación vas a necesitar los parámetros id, created_at y external_id Para efectos de este tutorial, los valores serán: 36875, 2018-08-01T16:51:17Z y 84bce950-c878 respectivamente.

4. Conciliación

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.

En esencia, el archivo de reconciliación se divide en 3 partes:

• Header o encabezado: Contiene la fecha del día que estás conciliando.
• Records o registros: Puede contener cero o más registros, y cada registro corresponde a cada una de las transacciones (pago de cuenta o bill) realizadas el día anterior.
• Footer o pié de página: Indica el número total de registros a conciliar.

Además, el nombre del archivo debe contener el nombre de tu empresa o negocio y la fecha de creación del archivo.

Para efectos de este tutorial, crearemos el archivo de conciliación de la transacción creada en los pasos anteriores. Para simplificar el formato de este archivo, en el siguiente ejemplo, coloque el cursor sobre cada uno de los campos para ver una breve descripción.

Nombre del archivo:

Descripciones:

• chain: Nombre de tu negocio.
• 20180802: Fecha de creación del archivo.

Contenido del archivo:

Descripciones:

• 20180802: Fecha de creación del archivo, debe ser la misma que la del nombre del archivo.
• 2018-08-01T16:51:17: Valor del parámetro created_at.
• 13621: Valor del parámetro biller_id.
• 36875: Valor del parámetro transaction_id.
• 256863285: Valor del parámetro account_number (número de cuenta).
• 52.45:
• MXN: Valor del parámetro currency (divisa).
• S12C03: Valor del parámetro pos_number (id de la terminal punto de venta).
• 84bce950-c878: Valor del parámetro external_id.
• 1: Número de registros.

Cuando no se manda ningún pos_number al realizar un pago, no se deberá incluir este campo (no se debe poner ningún espacio en blanco). Ejemplo:

En caso de que no exista ninguna transacción registrada que se deba conciliar, el archivo deberá verse de la siguiente forma:

HEADER|20180803
FOOTER|0

3. Realiza un Cash Out

Si desea ejecutar un Cash Out con Arcus API, use el endpoint POST /single/cash_out, para ello, necesitarás al menos, indicar los siguientes parámetros:

• biller_id: Es el biller id correspondiente.
• account_number: Número de cuenta de éste movimiento.
• amount: La divisa del importe que se está usando al recibir el pago.
• currency: La divisa o el tipo de moneda que se está usando al realizar el pago.
• pos_number: Tu id único para identificar la terminal o la sucursal en donde se realizó la transacción.
• cashier_id: Identificador o nombre de la persona en el punto de venta que realiza la transacción.
• external_id: Tu id propio para identificar estas transacciones. Es recomendable usar UUID.

Para más información de estos parámetros, consulta la documentación correspondiente al endpoint POST /single/cash_out .

Ejemplo

ENTIDADES FINANCIERAS REGULADAS - Parámetros Operativos Específicos

De acuerdo con la ley y los reglamentos establecidos por el Banco de México a través de la Comisión Nacional Bancaria y de Valores, es necesario considerar como información transaccional obligatoria compartir los siguientes parámetros:

Request body

• pos_number
• cashier_id

Response body

ticket_text: Es necesario recibir e imprimir (sin modificaciones) esta información en el comprobante de pago al usuario. Esta información la envía la Entidad Financiera Regulada Ejemplo: Para cualquier duda o aclaración comunicarse al (phone number) o al correo (support email)

En POST /single/cash_out endpoint, realiza un pago con el id de la cuenta que creamos en el paso anterior, el cuerpo de la llamada deberá tener la estructura que se muestra en el siguiente ejemplo, el cuál quedaría de la siguiente forma:

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

Y la solicitud URL al servidor Sandbox sería:

Recibirás toda la información asociada con esta transacción. Para el proceso de reconciliación vas a necesitar los parámetros id, created_at y external_id Para efectos de este tutorial, los valores serán: 36875, 2018-08-01T16:51:17Z y 84bce950-c878 respectivamente.