NAV
shell ruby java javascript

Introduction

Welcome to the Regalii API! You can use our API documentation to access Regalii API endpoints, which can get you information on various billers, bills, and transactions.

We have language bindings in Shell and Ruby! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Tools for Testing

Below is a list of tools that you can use to test different endpoints and their responses before you start coding against them. It is recommended that you test a couple of endpoints first to get an idea how to properly construct requests in your application.

Authentication

To authorize, use the following code. Make sure to replace your-api-key and your-secret-key with your real API key and secret keys:

gem install 'regaliator'

# Then require the gem:

require 'regaliator'

Regaliator.configure do |config|
  config.api_key      = 'your-api-key'
  config.secret_key   = 'your-secret-key'
  config.host         = 'api.casiregalii.com'
end

Regaliator.account.info
# Generate checksum
echo -n "application/json,,/account,Wed, 02 Nov 2016 17:26:52 GMT" \
  | openssl dgst -sha1 -binary -hmac "your-secret-key" \
  | base64

# With shell, you can just pass the correct header with each request
curl "https://api.cairegalii.com/account"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"

Regalii uses API and secret keys for authentication. If you don’t have one, you can register a new API key through our contact form.

Regalii expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: APIAuth your-api-key:<checksum>

The above command returns JSON structured like this:

{
  "name": "ACME Company",
  "balance": -10.0,
  "minimum_balance": -30000.0,
  "currency": "USD"
}

Calculating the checksum

Step 1

A checksum string is first created using your HTTP headers containing the Content-Type, Content-MD5, Endpoint and the Timestamp. The checksum string is computed as follows:

checksum_string = 'content-type,content-md5,endpoint,timestamp'

Example: application/json,,/account,Wed, 02 Nov 2016 17:26:52 GMT

Step 2

The checksum string is then used to create the checksum which is a Base64 SHA1 HMAC string encoded using your private secret key.

Step 3

Verify that if you pass application/json,,/account,Wed, 02 Nov 2016 17:26:52 GMT to your checksum function and use verify-secret as secret key, it should return nLet/JEZG9CRXHScwaQ/na4vsKQ=

Account

require 'regaliator'

bills = Regaliator.account.info
curl "https://api.casiregalii.com/account"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getAccount().info();
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.account().then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "name": "ACME Company",
  "balance": -537.5,
  "minimum_balance": -30000.0,
  "currency": "USD"
}

Returns the properties of your account with Regalii. This includes the name of your company, and both the current balance you owe us and the maximum amount of credit allowed to your account in your local currency.

HTTP Request

GET http://api.casiregalii.com/account

Billers

Utilities

require 'regaliator'

bill = Regaliator.biller.utilities
curl "https://api.casiregalii.com/billers/utilities"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBiller().utilities(null);
final Map<String, Object> body = response.body();

The above command returns JSON structured like this:

{
  "billers": [
    {
      "type": "biller",
      "id": 6008,
      "name": "Time Warner Cable",
      "country": "US",
      "currency": "USD",
      "biller_type": "Internet",
      "bill_type": "account_number",
      "can_check_balance": false,
      "mask": null,
      "requires_name_on_account": false,
      "supports_partial_payments": true,
      "hours_to_fulfill": 72,
      "account_number_digits": null
    },
    {
      "type": "biller",
      "id": 35,
      "name": "CFE",
      "country": "MX",
      "currency": "MXN",
      "biller_type": "Electricity",
      "bill_type": "account_number",
      "can_check_balance": true,
      "mask": "999 999 999 999",
      "requires_name_on_account": false,
      "supports_partial_payments": true,
      "hours_to_fulfill": 24,
      "account_number_digits": "12"
    },
    {
      "type": "biller",
      "id": 37,
      "name": "Telmex",
      "country": "MX",
      "currency": "MXN",
      "biller_type": "Landline",
      "bill_type": "phone_number",
      "can_check_balance": true,
      "mask": "(999) 999-9999",
      "requires_name_on_account": false,
      "supports_partial_payments": true,
      "hours_to_fulfill": 48,
      "account_number_digits": "10"
    }
  ]
}

Provides the current list of utility billers and their associated properties.

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.

HTTP Request

GET https://api.casiregalii.com/billers/utilities

Parameters

Parameter Description
page If set, it allows you to display any page of billers
q[country_eq] If set, it allows you to filter billers by country code

You may query this listing by country by passing in a query parameter. For to query for just the utilities billers in Mexico, in the body of your request, pass in the country code as a query parameter https://api.casiregalii.com/billers/utilities?q[country_eq]=MX.

Properties

The properties for each utilities biller are as follows:

Property Description
type A value of “biller”
id Unique identifier of the biller in the Regalii system
name Utility Biller’s name
country Utility Biller’s ISO 2 digit country code
currency The 3 digit ISO currency code of the utility biller’s country.
bill_type Specifies the bill identifier that is used to perform consults and payments. Values can be account_number, phone_number or barcode.
biller_type Specifies the utility type of the bill being paid. For example Electricity, Landline, or Cell.
mask A string representing the format of the bill_type. For example 999-999-99_99
account_number_digits The number of digits in the account number of the biller. This can either be a fixed number or a range. In the case of a range, the format is ‘min_number’..’max_number’
can_check_balance Boolean value specifying if the biller supports /bill/consult or not
supports_partial_payments Boolean value indicating if the biller supports paying of arbitrary amounts. When supports partial payments is false the full balance of the account must be paid, or the payment will be rejected. See payment types for info.
requires_name_on_account Boolean value specifying if the name of the account owner must be passed in for payments of this type. When requires_name_on_account is true, payments that do not include the name on the account, will be rejected. See payment types for info.
hours_to_fulfill Specifies maximum number of hours for a successful payment to be reflected on the customer’s bill. This number can vary from 0 to 72

Topups

require 'regaliator'

bill = Regaliator.biller.topups
curl "https://api.casiregalii.com/billers/topups"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBiller().topups(null);
final Map<String, Object> body = response.body();

The above command returns JSON structured like this:

{
  "billers": [
    {
      "type": "biller",
      "id": 1591,
      "name": "Telcel",
      "country": "MX",
      "currency": "MXN",
      "biller_type": "Cell",
      "bill_type": "phone_number",
      "available_topup_amounts": ["2.00","3.00","5.00","10.00","15.00","20.00","30.00","50.00"],
      "topup_fxrate": 10.0,
      "mask": "(999) 999-9999",
      "topup_commission": 25.0,
      "account_number_digits": "10"
    },
    {
      "type": "biller",
      "id": 1691,
      "name": "Tigo",
      "country": "HN",
      "currency": "HNL",
      "biller_type": "Cell",
      "bill_type": "phone_number",
      "available_topup_amounts": "6..50",
      "topup_fxrate": 18.0,
      "mask": "9999-9999",
      "topup_commission": 7.0,
      "account_number_digits": "8"
    }
  ]
}

Provides the current list of topup billers and their associated properties.

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.

HTTP Request

GET https://api.casiregalii.com/billers/topups

Parameters

Parameter Description
page If set, it allows you to display any page of billers
q[country_eq] If set, it allows you to filter billers by country code

You may query this listing by country by passing in a query parameter. For to query for just the topup billers in Mexico, in the body of your request, pass in the country code as a query parameter: https://api.casiregalii.com/billers/topups?q[country_eq]=MX.

Properties

The properties for each topup biller are as follows:

Property Description
type A value of “biller”
id Unique identifier of the biller in the Regalii system
name Topup Biller’s name
country Topup Biller’s ISO 2 digit country code
currency The ISO currency of the destination country.
bill_type Every topup biller’s bill type will be ‘Cell’
biller_type Every topup biller will be of type “topups”
mask A string representing the format of phone number, without country code. For a US company, this will often be ‘999-999-9999’
account_number_digits The number of digits in the phone number for this biller
available_topup_amounts A value or range of US dollar topup amounts available for a biller. For a range, the format will be min_amount..max_amount. In the case of preset values, the format is: ["4.00","7.00","13.00","24.00"].
topup_fxrate The fx_rate provided for doing a US topup payment with this biller. The amount received, excluding bonuses from the carrier, for a payment is amount(in USD) * topup_fxrate.

Credentials

require 'regaliator'

bill = Regaliator.biller.credentials
curl "https://api.casiregalii.com/billers/credentials"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBiller().credentials(null);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.account().then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "billers": [
    {
      "type": "biller",
      "id": 6510,
      "name": "Con Edison",
      "country": "US",
      "currency": "USD",
      "biller_type": "Electricity",
      "bill_type": "credentials",
      "required_parameters": ["login","password"],
      "returned_parameters": ["balance","due_date","account_number","name_on_account","xdata"],
      "can_migrate": false,
      "charge_user": true,
      "has_xdata": false
    },
    {
      "type": "biller",
      "id": 6526,
      "name": "Time Warner",
      "country": "US",
      "currency": "USD",
      "biller_type": "Utility",
      "bill_type": "credentials",
      "required_parameters": ["login","password"],
      "returned_parameters": ["balance","due_date","account_number","name_on_account","xdata"],
      "can_migrate": false,
      "charge_user": true,
      "has_xdata": false
    },
    {
      "type": "biller",
      "id": 12201,
      "name": "T-Mobile",
      "country": "US",
      "currency": "USD",
      "biller_type": "Phone",
      "bill_type": "credentials",
      "required_parameters": ["login","password"],
      "returned_parameters": ["balance","due_date","account_number","name_on_account","xdata"],
      "can_migrate": true,
      "charge_user": true,
      "has_xdata": true
    }
  ]
}

Provides the current list of credentials billers and their associated properties.

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.

HTTP Request

GET https://api.casiregalii.com/billers/credentials

Parameters

Parameter Description
page If set, it allows you to display any page of billers

Properties

The properties for each credential biller are as follows:

Property Description
type A value of “biller”
id Unique identifier of the biller in the Regalii system
name Utility Biller’s name
country Utility Biller’s ISO 2 digit country code
currency The 3 digit ISO currency code of the utility biller’s country.
bill_type Specifies the bill identifier that is used to perform consults and payments. Values can be account_number, phone_number or barcode.
biller_type Specifies the utility type of the bill being paid. For example Electricity, Landline, or Cell.
required_parameters List of parameters required to add a bill with this biller
returned_parameters List of returned parameters by this biller

Bills

Create with Account Number

require 'regaliator'

bill = Regaliator.bill.create(biller_id: 37, account_number: '4222422244')
curl "https://api.casiregalii.com/bills"
  -X POST
  -d '{"biller_id":37,"account_number":"4222422244"}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Object> params = new HashMap<>(2);
params.put("biller_id", 37);
params.put("account_number", "4222422244");
final Response response = client.getBill().create(params);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.createAccountNumberBill(37, "4222422244").then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 674125,
  "biller_id": 1,
  "account_number": "1234567",
  "name_on_account": "Jose Bautista",
  "due_date": null,
  "balance": 400.0,
  "balance_currency": "RD",
  "balance_updated_at": "2017-01-17T21:47:19Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "migrated_at": null,
  "mfa_challenges": []
}

This endpoint creates a bill for billers with account_number, phone_number, bar_code bill identifier.

HTTP Request

POST https://api.casiregalii.com/bills

Parameters

Parameter Description
biller_id The ID of the biller
account_number The account number

Create with Credentials

require 'regaliator'

bill = Regaliator.bill.create(biller_id: 6510, login: 'username', password: 'secret')
curl "https://api.casiregalii.com/bills"
  -X POST
  -d '{"biller_id":6510,"login":"username", "password":"secret"}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Object> params = new HashMap<>(3);
params.put("biller_id", 6510);
params.put("login", "username");
params.put("password", "secret");
final Response response = client.getBill().create(params);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.createCredentialsBill(6510, "username", "secret").then((args) => {
  console.log(args.body)
});

This endpoint creates a bill for billers with credentials bill identifier.

HTTP Request

POST https://api.casiregalii.com/bills

Parameters

Parameter Description
biller_id The ID of the biller
login account login
password account password

Successful Request

The above command returns JSON structured like this:

HTTP Status Code: 200 OK, Bill Status: linked

{
  "type": "bill",
  "id": 674117,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": []
}

MFA Challenge

HTTP Status Code: 201 Created, Bill Status: mfa

Example of bill status with MFA:

{
  "type": "bill",
  "id": 188,
  "status": "mfa",
  "mfa_challenges": [
    {
      "type": "question",
      "id": 1,
      "prompt": "What is 4 + 4",
      "expires_at": "2016-03-14T19:43:44Z"
    }
  ]
}

Slow Response

Example of bill which is still fetching because it did not finish in 60 seconds.

HTTP Status Code: 202 Accepted, Bill Status: fetching

{
  "type": "bill",
  "id": 674120,
  "biller_id": 6510,
  "account_number": null,
  "name_on_account": null,
  "due_date": null,
  "balance": null,
  "balance_currency": "USD",
  "balance_updated_at": null,
  "error_code": null,
  "error_message": null,
  "status": "fetching",
  "migrated_at": null,
  "mfa_challenges": []
}

Invalid Credentials

HTTP Status Code: 420 Unprocessable Entity

{
  "code": "R120",
  "message": "Please ensure your username and password are correct and try again."
}

Error Codes

Code Message
R120 Invalid username or password
R121 Balance lookup issue
R122 Balance not yet available for this biller
R123 The identification answer answered was incorrect

Handling Multi-factor Authentication

This is the JSON response when bill status is queried and it contains MFA

{
  "type": "bill",
  "id": 188,
  "status": "mfa",
  "mfa_challenges": [
    {
      "type": "question",
      "id": 1,
      "prompt": "What is 4 + 4",
      "expires_at": "2016-03-14T19:43:44Z"
    }
  ]
}

Next, solve the challenge question

require 'regaliator'

bill = Regaliator.bill.update(188,
  mfa_challenges: [
    {id: 1, type: 'question', response: '8'}
  ]
)
curl "https://api.casiregalii.com/bills/188"
  -X PATCH
  -d '{"mfa_challenges":[{"id": 1, "type": "question", "response": "8"}]}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Object> params = new HashMap<>(3);
params.put("id", 1);
params.put("type", "question");
params.put("response", "8");
final Response response = client.getBill().update(params);
final Map<String, Object> body = response.body();

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 188,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": []
}

Some billers require more than just a username/password to log in. In those situations, Regalii with associate one or more MFA challenges with a bill. An MFA challenge can be a verification code sent to a phone or a question which only the user would know the answer. When Regalii refreshes a bill, it will be put into a status of waiting with a challenge the customer must respond to.

GET https://api.casiregalii.com/bills/<ID>

In order to answer an MFA challenge, have the customer provide their response and update the bill’s MFA challenges. The type and id attributes of the answer must match the challenge given, and the response attribute contains the value. mfa_challenges is an array in case multiple challenges are given by the biller.

PATCH https://api.casiregalii.com/bills/<ID>

Once the challenge has been updated, Regalii will be able to update the bill balance, and the bill’s status will be set back to updating. Once the bill balance has been updated, the bill’s status will be set to updated.

Secret questions

Secret questions are often asked in addition to a users password. Their type attribute is question. Answers to secret questions will be stored between bill refreshes.

Verification codes

Verification codes are sometimes sent to a customer’s mobile phone before they are able to log in. Their type attribute is code. Verification codes cannot be re-used.

Errors

If a incorrect response is provided or the expires_at time passes before a response has been given, an error will be given and the bill will be put in the failed status.

List

require 'regaliator'

bills = Regaliator.bill.list
curl "https://api.casiregalii.com/bills"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBill().list(null);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.bills().then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "bills": [
    {
      "type": "bill",
      "id": 674124,
      "biller_id": 6510,
      "account_number": "87249256",
      "name_on_account": "Rita Sporer",
      "due_date": "2017-01-29T05:00:00Z",
      "balance": 62.38,
      "balance_currency": "USD",
      "balance_updated_at": "2017-01-17T19:57:56Z",
      "error_code": null,
      "error_message": null,
      "status": "linked",
      "migrated_at": null,
      "mfa_challenges": []},
    {
      "type": "bill",
      "id": 674125,
      "biller_id": 1,
      "account_number": "1234567",
      "name_on_account": "Jose Bautista",
      "due_date": null,
      "balance": 400.0,
      "balance_currency": "RD",
      "balance_updated_at": "2017-01-17T21:47:19Z",
      "error_code": null,
      "error_message": null,
      "status": "linked",
      "migrated_at": null,
      "mfa_challenges": []
    }
  ]
}

This endpoint retrieves all bills.

HTTP Request

GET http://api.casiregalii.com/bills

Query Parameters

Parameter Description
page If set, it allows you to display any page of bills
q[created_at_gteq] If set, it’ll return results after the specified timestamp.
q[created_at_lteq] If set, it’ll return results before the specified timestamp.

Example URL: https://api.casiregalii.com/bills?page=2

Get Status

require 'regaliator'

bill = Regaliator.bill.show(110)
curl "https://api.casiregalii.com/bills/110"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBill().show(110);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.showBillXdata(110).then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 674117,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": []
}

This endpoint retrieves a specific bill.

HTTP Request

GET https://api.casiregalii.com/bills/<ID>

Parameters

Parameter Description
ID The ID of the bill

Bill Status

Status Description
unlinked Bill was just created but not yet linked
fetching Bill is being linked or balance is currently being fetched
linked Bill was successfully linked and balance has been updated
mfa We are waiting for you to solve the challenge - check mfa_challenges field
failed We ran into a problem while updating your bill. Check error_code and error_message for further details.

Get xData

require 'regaliator'

bill = Regaliator.bill.show(674117)
curl "https://api.casiregalii.com/bills/622403871"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBill().show(674117);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.showBillXdata(674117).then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 674117,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": [],

  "address": {
    "street": "2651 Some St West, Unit 1A",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },

  "payment_method": {
    "type": "Credit",
    "identifier": "Visa - 1234",
    "autopay": true
  },

  "statements": [
    {
      "amount": 228.82,
      "period_start_date": "2016-08-07",
      "period_end_date": "2016-09-06"
    }
  ],

  "payments": [
    {
      "amount": 1.11,
      "confirmation": "ABCD12345",
      "date": "2016-09-29",
      "method": "CreditCard",
      "source": "Visa - 1234"
    }
  ],

  "subordinates": [
    {
      "number": "1112223333",
      "name": "John Doe",
      "device": {
        "name": "Nexus 5",
        "contract_start_date": "2015-01-01",
        "contract_end_date": "2017-01-01"
      },
      "plan": {
        "name": "Plan60"
      },
      "usage": {
        "data_available": 6000,
        "data_used": 560,
        "minutes_available": -1,
        "minutes_used": 107,
        "sms_available": -1,
        "sms_used": 202
      }
    }
  ]
}

This endpoint retrieves extended bill data.

HTTP Request

GET https://api.casiregalii.com/bills/<ID>/xdata

Parameters

Parameter Description
ID The ID of the bill

Pay Bill

require 'regaliator'

transaction = Regaliator.bill.pay(110, amount: 5568.00, currency: 'MXN')
curl "https://api.casiregalii.com/bills/110/pay"
  -X POST
  -d '{"amount":5568.00, "currency":"MXN"}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Object> params = new HashMap<>(2);
params.put("amount", 5568.00);
params.put("currency", "MXN");
final Response response = client.getBill().pay(110, params);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.xpayBill(110, { amount: 5568.00, currency: 'MXN' }).then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "type": "transaction",
  "id": 59335549,
  "amount": 5568.00,
  "amount_currency": "MXN",
  "fx_rate": 18.2569,
  "amount_usd": 304.98,
  "transaction_fee": 3.0,
  "total_usd": 307.98,
  "hours_to_fulfill": 48,
  "status": "fulfilled"
}

This endpoint issues a payment for a bill.

HTTP Request

POST https://api.casiregalii.com/bills/<ID>/pay

Parameters

Parameter Description
ID The ID of the bill
amount amount to pay
currency amount currency

Refresh Bill

require 'regaliator'

bill = Regaliator.bill.refresh(110)
curl -X "POST" "https://api.casiregalii.com/bills/110/refresh" \
     -H "Content-Type: application/json" \
     -H "Accept: application/vnd.regalii.v3.1+json" \
     -H "Authorization: APIAuth your-api-key:<checksum>" \
     -H "Date: Wed, 21 Dec 2016 16:29:32 GMT" \
     -H "Content-MD5: " \
     -d "{}"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getBill().refresh(110);
final Map<String, Object> body = response.body();

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 110,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": []
}

This endpoint retrieves a specific bill. This endpoint responds in the same way that the bill creation endpoint responds.

HTTP Request

POST https://api.casiregalii.com/bills/<ID>/refresh

Parameters

Parameter Description
ID The ID of the bill

Update Bill

require 'regaliator'

bill = Regaliator.bill.update(110, account_number: '4888488844')
curl "https://api.casiregalii.com/bills/110"
  -X PATCH
  -d '{"account_number":"11124123"}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Object> params = new HashMap<>(1);
params.put("account_number", "4888488844");
final Response response = client.getBill().udpate(110, params);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.updateBill(110, { account_number: '4888488844' }).then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "type": "bill",
  "id": 110,
  "biller_id": 6510,
  "account_number": "4222422244",
  "name_on_account": "Jose Bautista",
  "due_date": "2016-11-30",
  "balance": 56.43,
  "balance_currency": "USD",
  "balance_updated_at": "2017-01-16T20:12:58Z",
  "error_code": null,
  "error_message": null,
  "status": "linked",
  "mfa_challenges": []
}

HTTP Request

PATCH https://api.casiregalii.com/bills/<ID>

Parameters

Parameter Description
ID The ID of the bill
account_number The account number

Exchange Rates

require 'regaliator'

bills = Regaliator.rates.list
curl "https://api.casiregalii.com/rates"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getRate().list(null);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.rates().then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "GBP": 0.7889,
  "CAD": 1.2748,
  "MXN": 18.2569,
  "RD": 44.3413,
  "NIO": 27.8915,
  "GTQ": 7.1805,
  "HNL": 21.9706,
  "COP": 2796.9696,
  "BRL": 3.0717,
  "PEN": 3.2663,
  "BOB": 6.6444,
  "PHP": 46.5328,
  "INR": 64.2373,
  "JMD": 122.8474,
  "NGN": 300.2918
}

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

HTTP Request

GET http://api.casiregalii.com/rates

Transactions

Transactions List

require 'regaliator'

bills = Regaliator.transaction.list
curl "https://api.casiregalii.com/transactions"
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Response response = client.getTransaction().list(null);
final Map<String, Object> body = response.body();
const Regaliator = require('regaliator');

const client = new Regaliator('api.casiregalii.com', 'api_key', 'secret_key');

client.transactions().then((args) => {
  console.log(args.body)
});

The above command returns JSON structured like this:

{
  "transactions": [
    {
      "id": 59335549,
      "amount": 5568.00,
      "amount_currency": "MXN",
      "fx_rate": 18.2569,
      "amount_usd": 304.98,
      "transaction_fee": 3.0,
      "total_usd": 307.98,
      "hours_to_fulfill": 48,
      "status": "fulfilled"
    }
  ]
}

Returns a list of bill payments Regalii has processed for you in a page of 100 results. You may provide various search criteria, including id and timestamp.

Dealing with Timeouts

Timeouts from calling our server are rare but happen periodically. This is why all calls to /bill/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.

HTTP Request

GET http://api.casiregalii.com/transactions

Query Parameters

Parameter Description
page If set, it allows you to display any page of bills
q[created_at_gteq] If set, it’ll return results after the specified timestamp.
q[created_at_lteq] If set, it’ll return results before the specified timestamp.
q[id_eq] Query transactions using the id
q[external_id_eq] Query transactions using the external_id you supplied

Example URL: https://api.casiregalii.com/transactions?page=2

Transactions Cancel

curl "https://api.casiregalii.com/transaction/cancel"
  -X POST
  -d '{"id":59334631}'
  -H "Accept: application/vnd.regalii.v3.1+json"
  -H "Content-Type: application/json"
  -h "Content-MD5:"
  -H "Date: Wed, 02 Nov 2016 17:26:52 GMT"
  -H "Authorization: APIAuth your-api-key:<checksum>"
final Configuration config = new Configuration(Version.v3_1, "api.casiregalii.com", "api_key", "secret_key");
config.setUseSSL(true);

final Client client = (Client) config.buildClient();
final Map<String, Integer> params = new HashMap<>(1);
params.put("id", 59334631);
final Response response = client.getTransaction().cancel(params);
final Map<String, Object> body = response.body();

The above command returns JSON structured like this:

{
  "code": "R0",
  "message": "Transaction successful"
}

Allows you to cancel a bill payment from the same day for certain billers using the id returned from the bill/pay endpoint. If the bill has already been cancelled, the biller does not support cancelling, or the allowed time period has already elapsed, the response will contain an error.

HTTP Request

POST https://api.casiregalii.com/transaction/cancel

Completing Integration

Getting Started

Please test your integration by making calls to our sandbox server.

All calls made to the sandbox environment are mocked so that 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 document is to ensure that you have handled all of the different scenarios that may arise. Please complete all of the “Success” scenarios found below.

Authentication + First Request

Goal: Grab information about your account.

References:

Correct authentication headers are required to gain access to the Regalii API. This is handled automatically in our official client libraries.

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

Perform:

Success:

Syncing Billers

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

References:

Perform:

Success:

Linking Bill: Credentials

Goal: Create a bill in Regalii in order to get data from the account. Linking a bill enables you to get the balance and optionally make payments.

References:

Perform:

Success:

Linking Bill: Account Number

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

References: Creating with account number

Perform:

Success:

Linking Bill: Slow

Goal: Trigger a slow response which will need to be polled.

References

Sometimes a biller can take longer to deploy the response. In this case it is necessary to poll Regalii for the status of the bill.

Perform:

Success:

Linking Bill: MFA Question

Goal: Trigger a mfa-question response which will need to be answered after.

References

Some billers require additional security questions in order to authenticate. Pay attention to the expires_at date, some billers only give a pair of minutes to answer or you will need to start the process again.

Perform:

Success:

{
  "type": "bill",
  "id": 123,
  "status": "mfa",
  "mfa_challenges": [
    {
      "id": 1,
      "prompt": "What is 4 + 4",
      "expires_at": "2016-03-14T19:43:44Z",
      "type": "question"
    }
  ]
}

Linking Bill: MFA Code

Goal: Trigger a mfa-code response which will need to be answered after.

References

Some billers require an additional code as security in order to authenticate. Pay attention to the expires_at date, some billers only give a pair of minutes to answer or you will need to start the process again.

Perform:

Success:

{
  "type": "bill",
  "id": 123,
  "status": "mfa",
  "mfa_challenges": [
    {
      "id": 1,
      "prompt": "Enter the code sent to the phone number ending with 5555",
      "expires_at": "2016-03-14T19:43:44Z",
      "type": "code"
    }
  ]
}

Linking Bill: Invalid Credentials

Goal: Trigger an invalid-credentials response to simulate an error.

References

Perform:

Success:

Refreshing a Bill

Goal: Take the bill from the “Linking Bill: Credentials” step (or link a new one) and refresh its balance.

Reference:

Perform:

Success:

Getting xData

Goal: Get additional information from one account.

References:

Perform:

Success:

Payments (optional)

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

Goal: Succesfully pay a bill for a client.

References

Perform:

Success:

Reconciliation

There are two methods to reconcile your transactions with those of Regalii. They are:

  1. You can query for the list of transactions,
  2. you can upload a file to us each morning at 5AM EST with the list of the previous’ day’s transactions.

The notes below describe FTP reconcilation.

Directions

Upload a file of the format specified below to our FTP server at 5AM EST. 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 6AM EST.

The archive should have 1 entry for every transaction performed by your chain from midnight to midnight EST of the previous day. The file should be uploaded every day of the week, including weekends.

The conciliation results’ email will contain describe the differences between our records calling out the transactions included in the uploaded archive that were present in our records and the transactions in our records that were not included in your archive.

The credentials for the SFTP server will be provided during certification process

File example

This is an example of a reconciliation example file. The file describes the transactions performed by a chain of name chain, that did 2 transactions on Feb 9, 2016.

File name

Example: customer "Chain" create a file at Feb 9, 2016 5:07 AM

file name will be:
chain_20160209.txt

Reconciliation filename should be on the following layout:

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

File format

Example: File created in Feb 9, 2016 at 4:02:05 UTC

Header line will be
HEADER|20160209

Example:

  - Transaction on Feb 9, 2016 at 5:09:57 PM UTC
  - biller_id: 40
  - account number: 501000000007
  - amount: 185 MXN
  - id returned by /bill/pay: 177467
  - external_id: 54321
  - pos_number: 7

Register line will be:
REGISTER|2016-02-09T17:09:57|40|177467|501000000007|185.00|MXN|7|54321

Example: As pos_number and external_id are optional in /bill/pay request, there are also opional on the conciliation file, please, see the following example

  - Transaction on Feb 9, 2016 at 5:09:57 PM UTC
  - biller_id: 40
  - account number: 501000000007
  - amount: 185 MXN
  - id returned by /bill/pay: 177467
  - external_id: 54321
  - pos_number: 7

Register line will be:
REGISTER|2016-02-09T17:09:57|40|177467|501000000007|185.00|MXN||

Example: File with 10 transactions

Footer line will be:
FOOTER|10

The conciliation file, is a pipe separated file with the following format

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

HEADER Indicate this is a header line
YYYYMMDD Date when the file is created:
YYYY: Year in 4 digits
MM: Month of the year, zero-padded
DD: Day of the month, zero-padded

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

REGISTER Indicate this is a register line
creation DateTime Transaction’s creation DateTime in UTC in format yyyy-MM-ddTHH:mm:ss
biller id (SKU) Transaction’s biller id
authorization Transaction’s authorization, this is the field “id” returned on a successful /bill/pay request
account number Transaction account number
amount Transactions amount in local currency, same amount sent on /bill/pay request
It should include decimal point and 2 decimals
amount currency Transaction’s currency, same send at /bill/pay request
pos number post_number send on /bill/pay request
external id external id send on /bill/pay request
FOOTER Indicate this is a footer line
Transactions count Number of transactions included on the file, should be the same number of “Register” lines

Upgrading From v3.0

Here are the scenarios that need to be updated when going from v3.0 to v3.1 of the Regalii API:

Bill Creation Responses

The bill creation process is now synchronous. The only time polling is required is if the bill takes longer than 60 seconds. This should allow most bills to be created without the need to poll.

HTTP statuses on bill creation now indicate the result instead of relying only on status field.

Bill Status Codes

Bill statuses have been streamlined:

Gem Updates

Please refer to the gem README for further details: https://github.com/regalii/regaliator

Errors

The Regalii API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized – Your API key or checksum is wrong
403 Forbidden – You are not authorized to access the resource requested
404 Not Found – The specified resource could not be found
429 Too Many Requests – You’re sending too many requests! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – Please try again later.

Document Revision History

Revision Author Date Status and Description
1.2 Rodrigo Treviño 15 November 2016 Translation to Spanish
1.1 Hesham El-Nahhas 01 November 2016 Style and format update
1.0 Naysawn Naji 01 January 2016 First version