Documentation - Arcus APIv3.3

Welcome to Arcus API, this is its full documentation. Here, you will find detailed information about Arcus API. This documentation goes hand in hand with the endpoints site. It contains information about each endpoint and it is the best way to know what you have to send and what you will receive for every request you perform.

Environments

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

• Sandbox. Arcus maintains a Sandbox which allows developers to test the API using mocked data. We recommend keeping in mind the following: The list of billers is not in sync with the billers in production.

  To make requests to sandbox environment, use the following URL: https://api.staging.arcusapi.com

• Production. Once you have completed all the necessary tests on the sandbox, contact us to receive your production keys.

  To make requests to the production environment, use the following URL: https://api.arcusapi.com

Security

To make requests to our endpoints, you must use the HTTPS protocol, regardless of the environment you're using.

Security HTTP Headers

All responses return the following security headers.

• 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

Authentication

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

• Accept MIME type which is acceptable for the response.
  For all your requests, you will always send application/vnd.regalii.v3.3+json
• Content-Type Indicates the MIME type of the entity-body sent to the recipient.
  You will always send application/json.
• Date Represents the date and time at which the message was originated. This header format is specified in RFC 822 Section 5.
  For example: Wed, 01 Aug 2018 17:26:52 GMT
• Authorization Authentication credentials, this header has the following form:
  APIAuth <your-api-key>:<checksum>
• Content-MD5 (optional). It's an MD5 digest of the entity-body for the purpose of providing an end-to-end message integrity check (MIC) of the entity-body.

As it is indicated by its description, Authentication header is the way to authenticate in the Arcus API, it's 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

A checksum string (<checksum-string>) is first created using the following HTTP request headers

• Content-Type
• Content-MD5
• Date

And 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

<checksum> is an HMAC encoded in Base64. The HMAC uses SHA-1 as hash function and <your-secret-key> as cryptographic key.

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.

How to make an API call

The endpoint /account will retrieve your account information. It is an excellent way to learn how to make requests to Arcus For this example, we are going to use curl tool.

In a shell script file write step 1 and 2:

1. Generate the checksum replacing <your-secret-key> with the secret key provided by 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. Send you request to desired environment. Replace <your-api-key> with the API key provided by Arcus.

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

3. Execute the script. The server will respond with a JSON object. Use this information in according your needs.

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

Country codes, currency codes and date-time format conventions

Country and currency codes as well as date-time form used throughout this API are standardized in accordance with ISO Standards.

• Country codes: ISO 3166-1 alpha-2. For example,MX code matches with Mexico.
• Currency codes: ISO 4217. For example,MXN code matches with Mexican Peso.
  Note: ISO publishes the currency codes in XML and XLS form.
• Date-time form: Date-time is stored in ISO/WD 8601 YYYY-MM-DDThh:mm:ssZ format (This matches to Extended complete representation of Date and time of day format).
  Example: If you execute a payment on July 16th, 2018 at 12:47:57 in Mexico City, it's saved as 2018-07-16T17:47:57Z.

Caching data

To ensure that your customers are able to leverage the enhancements that we make over time, you are required to cache the full list of billers and update it on a weekly basis. To perform this task, Arcus provides a list of billers in the endpoints provided. Sync this information with your local database.

Endpoints:

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

We disclose to you the exchange rates that will be applied for the bill. These rates change on a daily basis at 5AM EST. You are required to cache them each morning between 6-7AM EST.

Endpoints:

• GET /rates

Pagination

Some endpoints like /billers/*, /bills and /transactions have large results and these results are partitioned in pages. Handle pagination by using the X-Pagination header and requesting subsequent pages. For more information, consult pagination model in endpoints site.

Payment Types

There are 4 payment workflows based on the biller’s options:

• can_check_balance
• supports_partial_payment

Webhooks

Arcus offers webhooks which can be used to notify you when there are updates to a bill or transaction.

When are Webhooks Sent?

Webhooks are sent when there are changes in a bill object:

• the bill has been re-run by Arcus due to an earlier error or outage

How to Register a Webhook?

You can set up a webhook URL with Arcus by contacting us.

Data in Webhook

Webhooks return the same data returned when you create a bill or transaction.

Dealing with timeouts

Timeouts from calling our server are rare but can happen periodically. You can deal with timeouts in bill's creation and payment.

Creation timeout

Bills can't be duplicated, so any request to create again a bill is going to response with the previous bill created.

Payment timeout

All calls to POST /bills/{id}/pay should include an external_id parameter that corresponds to a generated unique id in your system, which will be stored with a successfully processed transaction. We recommend use UUID for this field.

If a timeout happens, make a call to GET /transactions with query parameter q[external_id_eq], include the sent external_id to payment endpoint. If you get data, the request was received by Arcus. Otherwise, perform the payment again.

Integration

Please test your integration by making calls to our sandbox.

All calls made to the sandbox environment are mocked so there is an expected outcome for all scenarios. Because all responses on the sandbox server are fake, feel free to make every possible request that you need to test.

The goal of this section is to ensure that you have handled all of the different scenarios that may arise.

Authentication + First Request

Goal

Grab information about your account.

References:

• Authentication
• Account endpoint.

Correct authentication headers are required to gain access to the Arcus API. You can build a well-formed curl command in our endpoints site.

However, if you want to implement it by yourself, follow the steps described in the Authentication section.

Perform:

Success:

• Provide the balance returned.

Syncing billers

Goal

Cache the information about the billers that Arcus provides. Update the billers listed in your database with the endpoints provided.

References

• Utility billers
• Top-up billers
• Arcuspay billers

Perform

Success

• Verify that the number of billers in your local database is the same number of records returned in the billers feed.
• Verify that all billers are accessible for the client in the UI.
• Verify that there is a quick way to filter the billers listing.
• Handle pagination by using the X-Pagination header and requesting subsequent pages.

Linking bill: Creation

Goal

Create a bill in Arcus with an account number. Account number bills are mostly to make payments without providing personal information.

References:

• Bill creation endpoint

Perform:

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

Success:

• Receive a 200 response
• Get the id of the Bill
• Get the status of the Bill (linked)

Retrieve all bills

Goal

Retreive data of all bills

References:

• Bills get endpoint

Perform:

Success:

• Response has 200 status code.
• Handle pagination by using the X-Pagination header and requesting subsequent pages.

Show a bill

Goal

Retreive data of a specific bill

References:

• Bill show endpoint

Perform:

Success:

• Response has 200 status code.
• Bill data.

Bill's extended data

Goal

Get additional info of a bill, use this endpoint according with bill's field has_xdata.

References:

• Bill xData endpoint

Perform:

Success:

• Response has 200 status code
• Bill with extra info.

Refreshing a bill

Goal

Take a bill (or link a new one) and refresh its balance.

References:

• Bill refresh endpoint

Perform:

Success:

• Response has 200 status code
• Verify balance has changed (remember numbers are random on staging)

Destroy a bill

Goal

Destroy a bill given its ID.

References:

• Bill delete endpoint

Perform:

Success:

• Response has 200 status code.
• All data associated with the bill.
• A call to GET /bills will not show this bill.

Payments (optional)

This section only needs to be completed if you plan to pay bills via the Arcus API.

Goal

Successfully pay a bill for a client.

References

• Pay bill

Perform:

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

Success:

You receive a 200 response and the payment confirmation.

Reconciliation

Payments

To reconcile your transactions with Arcus, you must upload a file to us EACH MORNING BETWEEN 4 AM CST and 5 AM CST with the list of the previous day’s transactions, even if you didn't perform payments.

Directions

1. Upload a file of the format specified below to our SFTP server at 4 AM CST. We will process the record and reconcile it against the records that we have on our own server and send you back the results at 5 AM CST.
2. The file should have 1 entry for every transaction performed by your chain from midnight to midnight CST of the previous day. It’s very important to take daylight saving times into consideration, as Arcus adjusts automatically to CDT.
   Differences in timezones when generating transaction files might result in reconciliation differences. The file should be uploaded every day of the week, including weekends.
3. If you don't have transactions, the file will only contain the header and the footer with 0 registers count.
4. The conciliation results’ email will describe the differences between our records calling out the transactions included in the uploaded file that were present in our records and the transactions in our records that were not included in your file.
5. The credentials for the SFTP server will be provided during certification process.

File specification

This is an example of a reconciliation file. The file describes the transactions performed by a chain of name chain, that did 2 transactions on Aug 8 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

File name

Reconciliation filename should be on the following layout:

Where:

• chainname: Chain name
• YYYYMMDD: DateTime when the file is created in UTC. Where:
  • YYYY: year in 4 digits
  • MM: Month of the year, zero-padded
  • DD: Day of the month, zero-padded

File format

The conciliation file, is a pipe separated file with the following format. Use a vertical bar | as field separator.

1. First line should be a header, with the date of creation.

2. After the Header line, you should include zero or more Register lines, each line should contain the information of one transaction in the following layout.

3. The last line of the file is Footer line, it contains a summary of all transactions with the following format.

Cash out

Goal

Perform a Cash out to an account.

Perform:

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

Success:

• Receive a 200 response

Error codes

HTTP Error codes

The Arcus API uses the following HTTP status error codes.

Arcus API error codes