Introduction

What is ArcusPay?

The new payment systems are changing the dynamics that consumers follow to buy products and services, by moving from cash to credit and debit cards, at the same time that mobile devices, such as smartphones are being used to make payments.

ArcusPay is a proprietary payment rail that allows converting cash-to-digital at the same time that facilitates cash-out functionalities from digital wallets into physical retail stores.

How does it work?

ArcusPay is a RESTfull API payments network specifically designed for payees that want to receive payments for their businesses. ArcusPay supports a variety of use cases that can be seen throughout this documentation. The network defines a set of APIs and processes that joining payees will need to develop in their back-end environment. After the development is done by the newly joined participant, Arcus will run a certification period, after which, the payee will be available to the whole Arcus network.

If your current use case is not covered by our documentation, do not hesitate to contact us to get more information, we will analyze how we could collaborate.

Quickstart

Want to join the ArcusPay network?

Read the documentation and decide if this is the product you are looking for;
Get in touch with us at contact@arcusfi.com
Get a sandbox key to start integrating
Get your service up and rolling

Idempotency

Every API call will need to include a unique idempotency key. This unique key will be used to avoid duplicate posting of funds, duplicated charges, or any kind of issues generated due to timeouts. Once a network participant has received an idempotency key, if a subsequent API call is received with the same idempotence key then the original response object should be returned and no new resources should be created.

Idempotence will be managed by the use of Idempotency-Key header within each API request. This key value will be a unique UUID v4 per each request.

ArcusPay Retry Policy

Timeouts

ArcusPay will expect a response from the network partner within the timeframe defined (during the certification period) from the request. If no response is obtained the network will retry the petition, including the same idempotency-key header, following ArcusPay's retry policy.

ArcusPay's retry policy will re-send the original request as many times as needed to either:

Receive a valid, acceptable response
Meet the timeout defined with the payer.

Should a network partner receive a request with a previously provided idempotency-key then it would be expected to return the originally generated resource. If ArcusPay receives no response, within the defined response timeout, then ArcusPay network will deem the request as failed.

Authentication API & Security

POST /v1/arcuspay/authentication

Network participants will need to develop an Authentication API that arcus will utilize to authenticate itself. The authentication API will provide Arcus a bearer token that will be utilized for any subsequent API call as authentication method.

HTTPS Basic Authentication will be used for this endpoint as specified within the RFC 7617 standard. Arcus' will need to get their credentials provided by the merchant during the integration process.

All endpoints will be processed through HTTPS
Enddoints domains will need to be SSL certified
Access to the endpoints will be restricted to Arcus provided IPs
Arcus will use the provided token in all API calls as authentication method

Body parameter

{
  "user": "example USER",
  "pwd": "*********",
}

Body

Name	Type	Required	Description
user	string	true	User provided to Arcus by the network participant
password	string	true	Pasword provided to Arcus by the network participant

Example responses

Succesful authentication

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expiresIn": 3600
}

Failed authentication

{
  "message": "unathorized"
}

Responses

Status	Meaning	Description	Schema
200	OK	Succesful authentication	Inline
401	Unathorized Entity	Unathorized	Inline

Response Schema

Status Code 200

Name	Type	Required	Description
token	string	true	JWT bearer token to be used as authentication method
expiresIn	string	true	Expiration time in seconds of the provided token

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (Unathorized)

Deposits API

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string'
  'Authorization' : 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

r = requests.post('/v1/arcuspay/deposit', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

result = RestClient.post '/v1/arcuspay/deposit',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /v1/arcuspay/deposit \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string'\
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

const inputBody = '{
  "id": "ap_114441265464",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Idempotency-Key':'string',
  'Authorization':'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

fetch('/v1/arcuspay/deposit',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("/v1/arcuspay/deposit");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Idempotency-Key' => 'string',
    'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/v1/arcuspay/deposit', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

New Deposit

POST /v1/arcuspay/deposit

Arcus Digital Wallet realtime deposit endpoint

Deposit endpoint to be used to post funds into the end customer's account. The ArcusPay partner should return a 201 response within the defined timeout, where the deposit should have been authorized. The actual posting could occur later, if the internal operations are slower than the time needed within an API response.

QR Codes for Deposits

Partners that offer deposit functionalities are encouraged to facilitate to their customers a QR code in order to provide a consolidated, seamless end 2 end experience for their customers.

Deposit1

The end customer of the network participant can walk-in into any of the POS that are connected into Arcus, and by providing the QR code, they will be able to deposit the desired amount.

Payment Reference

Field	Length	Description
Prefix	5	Version of PAYMENT REFERENCE. Version AP001: Five numbers.
PayeeID	7	Unique identifier provided by Arcus to a PAYEE. If the id length is less than 7 characters, right justify the Biller ID and pad it with 0.
Account Reference	18	Account reference of PAYEE. it identifies an account or unique reference of the PAYEE. If the account length is less than 18 characters, right justify the Biller ID and pad it with 0
DV	2	The verification sum of the remaining of PAYMENT REFERENCE.

Body parameter

{
  "id": "56412",
  "account_reference": "000236541258745213",
  "amount": 10000,
  "amount_currency": "MXN",
  "payer_id": 711
}

Headers

Name	Type	Required	Description
Idempotency-Key	string (UUID v4)	true	Every API call will include a unique idempotency key. In order to avoid duplicate posting of funds and timeouts errors, if a subsequent API call is received with the same idempotentcy ID then the original response object should be returned.
Authorization	string	true	Bearer "participant_rovided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Body

Name	Type	Required	Description
id	string	true	Unique deposit identifier created by Arcus. It will follow the format of "ap_<string>"
account_reference	string	true	Account reference (as provided by the payee) which will be used to reference the account into which funds will be deposited. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code"). The payment reference will be obtained from the payment reference originally generated by the payee for their clients to make payments (i.e. When Arcus receives a payment with arcus pay reference AP001004871200023654125874521311 Arcus will run the necessary validation and send the payee the following payment reference in the body request:000236541258745213).
amount	integer	true	Amount of the deposit in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the deposit. (i.e. MXN for Mexican Pesos)
payer_id	integer	true	Reference of the payer that initiated the deposit transaction

Example responses

Succesful deposit

{
  "id": "ap_123441231",
  "account_reference": "000236541258745213",
  "payer_id": 711,
  "amount": 10000,
  "authorized": "2020-04-01T23:59:60Z",
  "verification_code": "dep_2223441"
}

Unprocessable deposit

{
  "code": "A001",
  "message": "ID already used"
}

{
  "code": "A010",
  "message": "Empty reference"
}

{
  "code": "A101",
  "message": "Maximum daily amount have been reached"
}

{
  "code": "A042",
  "message": "Invalid amount, maximum amount is XX"
}

{
  "code": "A041",
  "message": "Invalid amount, minimum amount is XX"
}

{
  "code": "A011",
  "message": "Invalid reference"
}

Responses

Status	Meaning	Description	Schema
201	Created	Succesful deposit	Inline
401	Unathorized Entity	Unathorized	Inline
422	Unprocessable Entity	Unprocessable deposit	Inline

Response Schema

Status Code 201

The following fields id , account_reference, payer_id and amount will be the same parameters as provided in the original request. On the other hand, verification_code and authorized will be generated by the depositary institution or neoBank with the needed information.

Name	Type	Required	Description
id	string	true	Unique deposit identifier created by Arcus. It will follow the format of "ap_<string>"
account_reference	string	true	Account reference (as provided by the payee) which will be used to deposit the funds. This reference could be either the payee's internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the deposit in local currency. In cents. (i.e. 100MXN will be represented as 10000)
verification_code	string	true	Verification code. Code generated by the depository institution as means to verify the deposit
payer_id	integer	true	Reference of the payeer that initiated the deposit transaction
authorized	string(date-time)	true	Timestamp when the deposit was authorized. RFC 3339 section 5.6.

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Status Code 422

Name	Type	Required	Description
code	string	true	Code for the error type
message	string	true	Descriptive message of the error cause (see examples)

Cash-Out API

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string'
  'Authorization' : 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

r = requests.post('/v1/arcuspay/cashout', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

result = RestClient.post '/v1/arcuspay/cashout',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /v1/arcuspay/cashout \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string'\
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

const inputBody = '{
  "id": "ap_114441265464",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Idempotency-Key':'string',
  'Authorization':'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

fetch('/v1/arcuspay/cashout',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("/v1/arcuspay/cashout");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Idempotency-Key' => 'string',
    'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/v1/arcuspay/cashout', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

New Cash Out

POST /v1/arcuspay/cashout

Arcus Digital Wallet realtime Cash Out endpoint

Cash Out endpoint to be used to withdraw funds from the end customer's account. The ArcusPay partner should return a 201 response within the defined timeout, where the cash out transaction should have been authorized. The actual posting could occur later, if the internal operations are slower than the time needed within an API response.

QR Codes for Cash Out

Partners that offer cashout functionalities are encouraged to facilitate to their customers a QR code in order to provide a consolidated, seamless end 2 end experience for their customers.

Cashout1

The end customer of the network participant can walk-in into any of the POS that are connected into Arcus, and by providing the QR code, they will be able to cash-out the desired amount.

Body parameter

{
  "id": "ap_114441265464",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}

Headers

Name	Type	Required	Description
Idempotency-Key	string(uuid)	true	Every API call will include a unique idempotency key. In order to avoid duplicate posting of funds and timeouts errors, if a subsequent API call is received with the same idempotentcy ID then the original response object should be returned.
Authorization	string	true	Bearer "participant_provided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Body

Name	Type	Required	Description
id	string	true	Unique cash out identifier created by Arcus. It will follow the format of "ap_########" where # represents a digit 0-9
account_reference	string	true	Account reference (originally generated by the participant) which will be used to reference the account into which funds will be cashouted. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the cash out in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the cashout. (i.e. MXN for Mexican Pesos)
payer_id	integer	true	Reference of the payer that initiated the cashout transaction request

Example responses

Succesful cash out

{
  "id": "ap_123441231",
  "account_reference": "000236541258745213",
  "payer_id": 711,
  "amount": 10000,
  "authorized": "2020-04-01T23:59:60Z",
  "verification_code": "CO_2223441"
}

Unprocessable cashout

{
  "code": "A001",
  "message": "ID already used"
}

{
  "code": "A010",
  "message": "Empty reference"
}

{
  "code": "A101",
  "message": "Maximum daily amount have been reached"
}

{
  "code": "A042",
  "message": "Invalid amount, maximum amount is XX"
}

{
  "code": "A041",
  "message": "Invalid amount, minimum amount is XX"
}

{
  "code": "A011",
  "message": "Invalid reference"
}

Responses

Status	Meaning	Description	Schema
201	Created	Succesful cashout	Inline
401	Unathorized Entity	Unathorized	Inline
422	Unprocessable Entity	Unprocessable cashout	Inline

Response Schema

Status Code 201

The following fields id , account_reference, payer_id and amount will be the same parameters as provided in the original request. On the other hand, verification_code and authorized will be generated by the financial institution or neoBank with the needed information.

Name	Type	Required	Description
id	string	true	Unique cashout identifier created by Arcus. It will follow the format of "ap_"
account_reference	string	true	Account reference (as provided by the payee) which will be used to cashout the funds. This reference could be either the payee's internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the cashout in local currency. In cents. (i.e. 100MXN will be represented as 10000)
verification_code	string	true	Verification code. Code generated by the financial institution as means to verify the cashout
payer_id	integer	true	Reference of the payeer that initiated the cashout transaction
authorized	string(date-time)	true	Timestamp when the cashout was authorized. RFC 3339 section 5.6.

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Status Code 422

Name	Type	Required	Description
code	string	true	Code for the error type
message	string	true	Descriptive message of the error cause (see examples)

Checkout API

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string'
  'Authorization' : 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

r = requests.post('/v1/arcuspay/checkout', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

result = RestClient.post '/v1/arcuspay/checkout',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /v1/arcuspay/checkout \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string'\
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

const inputBody = '{
  "id": "ap_114441265464",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Idempotency-Key':'string',
  'Authorization':'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

fetch('/v1/arcuspay/checkout',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("/v1/arcuspay/checkout");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Idempotency-Key' => 'string',
    'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/v1/arcuspay/checkout', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

New checkout Payment

POST /v1/arcuspay/checkout

Arcus Digital Wallet realtime checkout endpoint

Checkout endpoint to be used for an eCommerce checkout. The use case intended for this endpoint will entitle an eCommerce like store where at the point of checkout an ArcusPay possibility will be given where via any usable method (QR Code, Bar Code or reference) the customer will be able to make a payment in any payer connected to the arcuspay network.

The ArcusPay partner should return a 201 response within the defined timeout where the payment should have been authorized. The actual posting could occur later, if the internal operations are slower than the time needed within an API response.

Body parameter

{
  "id": "ap_114441265464",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}

Headers

Name	Type	Required	Description
Idempotency-Key	string(uuid)	true	Every API call will include a unique idempotency key. In order to avoid duplicate posting of funds and timeouts errors, if a subsequent API call is received with the same idempotentcy ID then the original response object will be returned.
Authorization	string	true	Bearer "participant_provided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Body

Name	Type	Required	Description
id	string	true	Unique checkout identifier created by Arcus. It will follow the format of "ap_"
checkout_reference	string	true	Checkout reference (as provided by the eCommerce payee) which will be used to reference the invoice into which funds will be used. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the checkout in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the checkout. (i.e. MXN for Mexican Pesos)
payer_id	integer	true	Reference of the payer that initiated the checkout transaction (i.e. 7eleven chain)

Example responses Succesful checkout payment

{
  "id": "ap_123441231",
  "account_reference": 1234567890,
  "payer_id": 711,
  "amount": 10000,
  "authorized": "2020-04-01T23:59:60Z",
  "verification_code": "co_2223441"
}

Unprocessable checkout payment

{
  "code": "A001",
  "message": "ID already used"
}

{
  "code": "A010",
  "message": "Empty reference"
}

{
  "code": "A101",
  "message": "Maximum daily amount have been reached"
}

{
  "code": "A042",
  "message": "Invalid amount, maximum amount is XX"
}

{
  "code": "A041",
  "message": "Invalid amount, minimum amount is XX"
}

{
  "code": "A011",
  "message": "Invalid reference"
}

Responses

Status	Meaning	Description	Schema
201	Created	Succesful checkout	Inline
401	Unathorized Entity	Unathorized	Inline
422	Unprocessable Entity	Unprocessable checkout	Inline

Response Schema

Status Code 201

The following fields id , checkout_reference, payer_id and amount will be the same parameters as provided in the original request. On the other hand, verification_code and authorized will be generated by the Financial institution or neoBank with the needed information.

Name	Type	Required	Description
id	string	true	Unique checkout identifier created by Arcus. It will follow the format of "ap_"
checkout_reference	string	true	Checkout reference (as provided by the eCommerce payee) which will be used to reference the invoice into which funds will be used. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the checkout in local currency. In cents. (i.e. 100MXN will be represented as 10000)
verification_code	string	true	Verification code. Code generated by the eCommerce institution as means to verify the checkout
payer_id	integer	true	Reference of the payeer that initiated the checkout transaction
authorized	string(date-time)	true	Timestamp when the checkout payment was authorized. RFC 3339 section 5.6.

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Status Code 422

Name	Type	Required	Description
code	string	true	Code for the error type
message	string	true	Descriptive message of the error cause (see examples)

Checkout Payment Information

GET /v1/arcuspay/checkout/{checkout_reference}

Arcus Digital Wallet realtime checkout endpoint

This endpoint will be used to request the needed information about a specific checkout payment. The network participant will be expected to return the information described below.

Headers

Name	Type	Required	Description
Authorization	string	true	Bearer "participant_provided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Parameters

Name	Type	Required	Description
checkout_reference	string	true	Checkout reference to be used to pull the information about the payment

Example responses Succesful GET checkout payment

{
  "checkout_date": "2020-08-01T23:59:60Z",
  "payment_due_date": "2020-08-05T23:59:60Z",
  "payment_status": "TO_BE_PAID",
  "checkout_reference": "2224441-12322",
  "amount": 10000,
  "amount_currency": "MXN"
}

Responses

Status	Meaning	Description	Schema
200	OK	Succesful checkout	Inline
401	Unathorized Entity	Unathorized	Inline

Response Schema

Status Code 200

Name	Type	Required	Description
checkout_date	date	true	Date when the checkout was made
payment_due_date	date	true	Due date by when the payment should have been done
payment_date	date	false	Optional field that tracks when the payment was done
payment_status	string	true	Status in which the checkout payment is currently. Possible statuses: [TO_BE_PAID, CANCELLED, EXPIRED, PAID]
checkout_reference	string	true	Checkout reference (as provided by the eCommerce payee) which will be used to reference the invoice into which funds will be used. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the checkout in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the checkout. (i.e. MXN for Mexican Pesos)

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Bill Pay API

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Idempotency-Key': 'string'
  'Authorization' : 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

r = requests.post('/v1/arcuspay/billpay', headers = headers)

print(r.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Idempotency-Key' => 'string',
  'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
}

result = RestClient.post '/v1/arcuspay/billpay',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /v1/arcuspay/billpay \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: string'\
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

const inputBody = '{
  "id": "ap_114441265111",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Idempotency-Key':'string',
  'Authorization':'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
};

fetch('/v1/arcuspay/billpay',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

URL obj = new URL("/v1/arcuspay/billpay");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Idempotency-Key' => 'string',
    'Authorization' => 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/v1/arcuspay/billpay', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

New Bill Payment

POST /v1/arcuspay/billpay

Bill pay endpoint to be used by bill processing or service providing companies. Partners can join arcusPay network by utilizing this endpoint in order to be paid for their services.

The ArcusPay partner should return a 201 response within the defined timeout where the bill payment should have been authorized. The actual posting could occur later, if the internal operations are slower than the time needed within an API response.

Body parameter

{
  "id": "ap_114441265111",
  "reference": "1234567890",
  "payer_id": 711,
  "amount": 10000
}

Headers

Name	Type	Required	Description
Idempotency-Key	string(uuid)	true	Every API call will include a unique idempotency key. In order to avoid duplicate posting of funds and timeouts errors, if a subsequent API call is received with the same idempotentcy ID then the original response object will be returned.
Authorization	string	true	Bearer "participant_provided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Body

Name	Type	Required	Description
id	string	true	Unique billpay identifier created by Arcus. It will follow the format of "ap_#######"
billpay_reference	string	true	billpay reference (as provided by the payee) which will be used to reference the bill. This reference could be either the billers' internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the billpay in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the billpay. (i.e. MXN for Mexican Pesos)
payer_id	integer	true	Reference of the payer that initiated the billpay transaction (i.e. 7eleven chain)

Example responses Succesful bill payment

{
  "id": "ap_123441231",
  "account_reference": "000236541258745213",
  "payer_id": 711,
  "amount": 10000,
  "authorized": "2020-04-01T23:59:60Z",
  "verification_code": "co_2223441"
}

Unprocessable bill payment

{
  "code": "A001",
  "message": "ID already used"
}

{
  "code": "A010",
  "message": "Empty reference"
}

{
  "code": "A101",
  "message": "Maximum daily amount have been reached"
}

{
  "code": "A042",
  "message": "Invalid amount, maximum amount is XX"
}

{
  "code": "A041",
  "message": "Invalid amount, minimum amount is XX"
}

{
  "code": "A011",
  "message": "Invalid reference"
}

Responses

Status	Meaning	Description	Schema
201	Created	Succesful billpay	Inline
401	Unathorized Entity	Unathorized	Inline
422	Unprocessable Entity	Unprocessable bill payment	Inline

Response Schema

Status Code 201

The following fields id , billpay_reference, payer_id and amount will be the same parameters as provided in the original request. On the other hand, verification_code and authorized will be generated by the Biller institution with the needed information.

Name	Type	Required	Description
id	string	true	Unique billpay identifier created by Arcus. It will follow the format of "ap_#######"
billpay_reference	string	true	billpay reference (as provided by the payee) which will be used to reference the bill. This reference could be either the billers' internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount	integer	true	Amount of the billpay in local currency. In cents. (i.e. 100MXN will be represented as 10000)
verification_code	string	true	Verification code. Code generated by the biller institution as means to verify the bill payment
payer_id	integer	true	Reference of the payeer that initiated the bill payment transaction
authorized	string(date-time)	true	Timestamp when the bill payment was authorized. RFC 3339 section 5.6.

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Status Code 422

Name	Type	Required	Description
code	string	true	Code for the error type
message	string	true	Descriptive message of the error cause (see examples)

Obtain Bill Information

GET /v1/arcuspay/billpay/{bill_reference}

This endpoint will be used to request the information about a specific bill payment. The response should include the latest available bill and a list of all the previous bills. The network participant will be expected to return the information described below.

Headers

Name	Type	Required	Description
Authorization	string	true	Bearer "participant_provided_token"
Accept	string	true	Accepted value: 'application/json'
Content-Type	string	true	Accepted value: 'application/json'

Parameters

Name	Type	Required	Description
billpay_reference	string	true	Bill reference to be used to pull the information about the payment

Example responses Succesful GET bill pay data

{
  "payment_due_date": "2020-08-05T23:59:60Z",
  "payment_status": "TO_BE_PAID",
  "billpay_reference": "4-421-2442--12322",
  "amount_due": 10000,
  "amount_currency": "MXN"
}

Responses

Status	Meaning	Description	Schema
200	OK	Succesful Bill Pay data	Inline
401	Unathorized Entity	Unathorized	Inline

Response Schema

Status Code 200

Name	Type	Required	Description
payment_due_date	date	true	Due date by when the payment should have been done
payment_date	date	false	Optional field that tracks when the payment was done
payment_status	string	true	Status in which the bill pay payment is currently. Possible statuses: [TO_BE_PAID, CANCELLED, EXPIRED, PAID]
billpay_reference	string	true	Billpay reference (as provided by the Biller payee) which will be used to reference the bill into which funds will be used. This reference could be either the merchants internal account reference or the CLABE (Clave Bancaria Estandarizada, Spanish for "standardized banking cipher" or "standardized bank code")
amount_due	integer	true	Amount of the bill pay in local currency. In cents. (i.e. 100MXN will be represented as 10000)
amount_currency	string	true	ISO4217 value of the currency used for the bill pay. (i.e. MXN for Mexican Pesos)
pdf_bill	base64	false	base64 formatted PDF document with the branded bill to the customer
previous_bills	list	true	A list of all the previous bills that were processed for this client with the same format that the rest of the items

Status Code 401

Name	Type	Required	Description
message	string	true	Descriptive message of the error cause (see examples)

Errors

The ArcusPay API uses the following error codes:

Code	Http Code	Message
A021	201	Succesful transaction
A020	200	Successful authentication
A001	422	Invalid account number
A003	422	Invalid deposit amount
A004	422	Invalid token
A005	422	Account number does not resolve with payee
A006	422	Invalid prefix
A007	422	Deposits with this payee are currently unavailable
A008	422	Payee maintenance in progress, please try again later
A009	422	The biller returned an error. Please check the account number
A010	422	Unexpected error (everything entered was correct)
A011	422	ID already used
A012	422	Invalid or missing parameters
A013	422	Maximum daily amount have been reached
A014	422	Invalid amount, minimum amount is XX
A015	422	Invalid amount, maximum amount is XX
A016	422	Token expired
A017	422	Configuration issue between us and our payee
A018	422	Error decrypting token
A019	422	Invalid check digit
A041	401	Invalid credentials
A046	406	There was an error in the parameters
A044	404	The request resource doesn't exist
A043	403	No permisions to perform the request
A048	408	Timeout
A099	422	General fallback error