Tutorial- Arcus APIv3.mx

Welcome to Arcus API Tutorial! This is a quick start to Arcus API, you will learn the basics about how to make calls to Arcus API endpoints, you can get information of billers, bills, and transactions.

Don not forget to take a look at documentation and endpoints sites for full reference.

Language bindings

We have language bindings in multiple languages!

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

Basics

Before perform any call to Arcus API, it is important that you learn about a few terms:

• Biller. Any company that offers an end user service (e.g.: CFE, Sky, Telmex). There are two types of billers:
• Utility. Is a company that provides a service as: Cable, Electricity, Government, Internet, Landline, etc.
• Top-up. Is a company that accepts fixed amounts, like prepaid cell (e.g. Claro, AT&T, Telcel, Movistar).
• Gift card. Is a company that provides gift cards like Netflix or Uber.
• Arcuspay. Is a company that is integrated with Arcuspay product.
• Bill. Expenses owed by an end user to a biller which need to be paid on a recurring basis.
• Transaction. All bills payment that Arcus has processed for you.

For all requests:

• You need a couple of keys for each environment.
• Headers are mandatory.
• The parameters are specified as JSON in request body.

Environments, credentials and tools

Arcus will provide you with separate API keys for our two existing environments:

• Sandbox. Testing with mocking data.
• Production. Real credentials and real data.

For this tutorial, you will make calls to Sandbox in the following URL: https://api.staging.arcusapi.com

More information about environments is available in our documentation.

Pair of keys provided by Arcus are a key for authentication in API with its secret key, in this tutorial they are called <your-api-key> and <your-secret-key> respectively.

Tools for testing

For this tutorial, you will need only a shell terminal, our endpoints tool and the following two tools to test the main endpoints and their responses. Check tool's documentation to install it.

• OpenSSL (Generate authentication string)
• curl (Make API requests)

Essential flow

The essential flow of Arcus API consists of the main things to do your integration with our API. It consists of only 4 very simple steps.

1. Authentication

The Arcus API has a special way of authentication, which is based on the path and HTTP headers of every request that is performed. Each request must contain the following headers:

As you will have guessed, Authorization header is the way to authenticate in the Arcus API, it is composed of the following pair: your API key and a checksum built from the endpoint, the HTTP headers and your secret key.

In the next section, you will learn how to calculate <checksum> for all your API requests.

Calculating the checksum

Step 1

First build the checksum string (<checksum-string>) with Content-Type, Content-MD5 and Date HTTP headers; and additionally the Endpoint that you want to access. This checksum string has the following form:

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

For example:

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

then it produces:

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

Step 2

You can use OpenSSL to calculate the checksum. In shell:

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

For example. If:

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

then it produces: PbYMLSKsXhplSStqyySn63UFEc8=

Make a call to /account endpoint to check your credentials.

2. Create a bill

Before perform any type of payment, it’s mandatory create a bill. These are created in the endpoint POST /bills.

For all bill creation, it’s required to set at least 2 parameters:

• biller_id
• account_number (its length will depend on the biller)

For more information about the parameters, check out the POST /bills endpoint.

Example:

In POST /bills endpoint, let a biller with ID 13621 and account number length of 9 digits, the request body must follow the following structure:

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

Replace account_number id property, you going to need it for perform a payment. For example, this id will be 01CCXHE663RJ55CBJPDK2N86C3.

3. Make a payment

After you have created a bill, you can now execute payments for that bill. If you want to execute payments with the Arcus API, use the endpoint POST /bill/{id}/pay, you will need at least the following parameters:

• id Placed in path, this correspond to bill id.
• amount Payment amount to this bill. If the biller does not accept partial payments, then full balance must be covered.
• currency The amount currency of the payment being performed.
• external_id Your own id to this transactions. UUID recommended.

Highly recommended, you can set an additional parameter, these correspond to an internal identifier under your own control:

• pos_number Id to identify where this transaction is performed, like a point of sale or a branch.

See endpoint POST /bills/{id}/pay for more information about these parameters.

Example

In POST /bills/{id}/pay endpoint, with the id of the account created in the previous step, now execute a payment, the body of the request must follow the following structure. For this example:

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

And the URL request to sandbox server will be:

You will receive all associated info about this transaction, you must save this properties. For reconciliation step, you will need id, created_at and external_id properties. For this this tutorial, these will be 36875, 2018-08-01T16:51:17Z and 84bce950-c878 respectively.

4. Reconciliation

To reconcile your transactions with Arcus, you must upload a file to us EACH MORNING BETWEEN 4AM EST and 5AM EST with the list of the previous day’s transactions.

In essence, the reconciliation file consists of three parts:

• Header: Contains the date of the day when you are reconciling.
• Records: Zero or more records, every record corresponds to each transaction information (account payment) that was performed previous day.
• Footer: Indicates the total number of records to be reconciled.

Furthermore, the file's name must contain the name of your chain and the file's creation date.

For this tutorial, we will build the reconciliation's file of previous transaction. To simplify the format of this file, in the following example, move your cursor over each field to view a short description.

File's name:

Descriptions:

• chain: Name of your business.
• 20180802: Date of file creation.

File's content:

Descriptions:

• 20180802: Date of creation of the file, must be the same as the file name.
• 2018-08-01T16:51:17: Value of the created_at parameter.
• 13621: Value of the biller_id parameter.
• 36875: Value of the transaction_id parameter.
• 256863285: Value of the account_number parameter.
• 52.45:
• MXN: Value of the currency parameter
• S12C03: Value of the pos_number parameter (POS terminal id)
• 84bce950-c878: External_id parameter value
• 1: Number of records

When you don't provide pos_number in a payment execution, its field in register must be empty (no whitespace). For example

If you don't have transactions to reconcile, your file would content:

HEADER|20180803
FOOTER|0

3. Cash out

If you want to execute a Cash out with Arcus API, use the endpoint POST /single/cash_out, you will need at least the following parameters:

• biller_id: This correspond to biller id.
• account_number: Account number of this cash_out
• amount: Payment amount to this cash_out.
• currency: The amount currency of the deposit being performed.
• pos_number: Id to identify where this transaction is performed, like a point of sale or a branch.
• cashier_id: Id or name to the person in the PoS whos make the transaction.
• external_id: Your own id to this transactions. UUID recommended.

See endpoint POST /single/cash_out .

Example

REGULATED FINANCIAL ENTITIES - Specifics Operating Parameters

According to the law and the regulations established by Banco de México though the Comisión Nacional Bancaria y de Valores, it is necessary considerate as a mandatory transaction information to share the next parameters:

Request body

• pos_number
• cashier_id

Response body

ticket_text: It is necessary to receive and print (no modifications) this information into the payment receipt to the user. This information is send it by the Regulated Financial Entity Example: Para cualquier duda o aclaración comunicarse al (phone number) o al correo (support email)

In POST /single/cash_out endpoint, the body of the request must follow the following structure. For this example:

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

And the URL request to sandbox server will be:

You will receive all associated info about this transaction, you must save this properties. For reconciliation step, you will need id, created_at and external_id properties. For this this tutorial, these will be 36875, 2018-08-01T16:51:17Z and 84bce950-c878 respectively.