NAV undefined
undefined
bash javascript csharp

Introduction

This API documentation contains technical information about the integration with Instarem to make international payments via the Instarem API.

API endpoints are grouped as below :

Authentication API

The API user must first obtain an authentication token by specifying the client_key and client_secret. This token must be present in the Authorization HTTP header when making other API calls.

Account API

Allows the API user to get details and available balance for all or specific accounts.

Balance API

Allows the API user to get available balance for all multiple currency accounts.

Book FX API

The BookFX API is used for making FX conversions within the multi-currency accounts. Payments instruction can be sent in the converted currency once a Book FX request is confirmed. If the available balance is sufficient, then conversion through Book FX is not required. Incase of Auto Book FX agreements, Instarem automatically books FX conversion from the pre-specified accounts basis the FX account sequence setup.

Payment API

The Payment API is for making payments from the client’s multi-currency account by specifying the currency, amount, beneficiary details, remitter details & purpose of the payment.

Errors

The Instarem API uses the following error codes:

Error Code Meaning
400 Bad Request -- The request could not be understood by the server due to malformed syntax
401 Unauthorized -- The request requires user authentication
403 Forbidden -- The server understood the request, but is refusing to fulfill it.
404 Not Found -- The server has not found anything matching the Request-URI.
405 Method Not Allowed -- The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
429 Too Many Requests -- Request counts exceed our limit. Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarially offline for maintanance. Please try again later.

Authentication API

Obtain Access token

Definition

POST https://api-test.instarem.com:4803/api/v1/authentication

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/authentication" \

--header 'client_key: 646328ryCV1T1Qb230681S1g0N1ayQZ' \
--header 'client_secret: 0dfc9110-51a1-11e7-9c6a-efd0a4ece369' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("post", "https://api-test.instarem.com:4803/api/v1/authentication")
xhr.setRequestHeader("client_key", "646328ryCV1T1Qb230681S1g0N1ayQZ");
xhr.setRequestHeader("client_secret", "0dfc9110-51a1-11e7-9c6a-efd0a4ece369");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/authentication");
var request = new RestRequest(Method.POST);
request.AddHeader("client_key", "646328ryCV1T1Qb230681S1g0N1ayQZ");
request.AddHeader("client_secret", "0dfc9110-51a1-11e7-9c6a-efd0a4ece369");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzczMjksImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA1MDkyOX0.RJGjVrOiP_jYvVniAVxmLnyym2Ue4FwvBTz1wRbFoiM"
}

Obtain an access_token by specifying the client_key and client_secret. A token is required for calling any of the API endpoints.

Header Parameters

ParameterDescription
client_key
REQUIRED
string
Client Key provided by Instarem
client_secret
REQUIRED
string
Client Secret provided by Instarem

Response (200)

token
string
Authentication token returned

Account API

Get accounts

Definition

GET https://api-test.instarem.com:4803/api/v1/account

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/account" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/account")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/account");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

[
    {
        "account_number": 101950173983,
        "currency": "USD",
        "auto_bookfx_sequence": 5,
        "active": true,
        "default": true,
        "label": "USD Currency"
    }
]

Get all the accounts and currencies details.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Response (200) - Multiple Values

account_number
number
Returns 12 digit account number generated by Instarem.
currency
string
Returns currency.
auto_bookfx_sequence
number
If returns <> 0, this account is used for Auto Book FX and its priority is set accordingly.
active
boolean
Returns true if account is active otherwise false.
default
boolean
Returns true if account is default otherwise false.
label
string
Returns label name for account.

Balance API

Get balance for all the accounts

Definition

GET https://api-test.instarem.com:4803/api/v1/balance/all

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/balance/all" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/balance/all")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/balance/all");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

[
    {
        "account_number": 101950173983,
        "currency": "USD",
        "balance": 50000,
        "auto_bookfx_sequence": 5,
        "active": true,
        "default": true,
        "label": "USD Currency"
    }
]

Get available balance for all the accounts.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Response (200) - Multiple Values

account_number
number
Returns 12 digit account number generated by Instarem.
currency
string
Returns currency (3-letter ISO-4217 code).
balance
number
Returns available balance of the account.
auto_bookfx_sequence
number
If returns <> 0, this account is used for Auto Book FX and its priority is set accordingly.
active
boolean
Returns true if account is active otherwise false.
default
boolean
Returns true if account is default otherwise false.
label
string
Returns label name as defined for account.

Get balance by currency

Definition

GET https://api-test.instarem.com:4803/api/v1/balance/currency/{currency}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/balance/currency/{currency}" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/balance/currency/{currency}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/balance/currency/{currency}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

[
    {
        "account_number": 101950173983,
        "currency": "USD",
        "balance": 50000,
        "auto_bookfx_sequence": 5,
        "active": true,
        "default": true,
        "label": "USD Currency"
    }
]

Get available balance for a specific currency.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Path Parameters

ParameterDescription
currency
REQUIRED
string
Currency to retrieve available balance.

Response (200) - Multiple Values

account_number
number
Returns 12 digit account number generated by Instarem.
currency
string
Returns currency (3-letter ISO-4217 code).
balance
number
Returns available balance of the account.
auto_bookfx_sequence
number
If returns <> 0, this account is used for Auto Book FX and its priority is set accordingly.
active
boolean
Returns true if account is active otherwise false.
default
boolean
Returns true if account is default otherwise false.
label
string
Returns label name as defined for account.

Get balance by account

Definition

GET https://api-test.instarem.com:4803/api/v1/balance/account/{account_number}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/balance/account/{account_number}" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/balance/account/{account_number}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/balance/account/{account_number}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

[
    {
        "account_number": 101950173983,
        "currency": "USD",
        "balance": 50000,
        "auto_bookfx_sequence": 5,
        "active": true,
        "default": true,
        "label": "USD Currency"
    }
]

Get available balance for a specific account.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Path Parameters

ParameterDescription
account_number
REQUIRED
number
Account number to retrieve available balance.

Response (200) - Multiple Values

account_number
number
Returns 12 digit account number generated by Instarem.
currency
string
Returns currency (3-letter ISO-4217 code).
balance
number
Returns available balance of the account.
auto_bookfx_sequence
number
If returns <> 0, this account is used for Auto Book FX and its priority is set accordingly.
active
boolean
Returns true if account is active otherwise false.
default
boolean
Returns true if account is default otherwise false.
label
string
Returns label name as defined for account.

Book FX API

Get FX rates

Definition

GET https://api-test.instarem.com:4803/api/v1/bookfx/rate

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/bookfx/rate?sell_currency=&buy_currency=" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/bookfx/rate?sell_currency=&buy_currency=")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/bookfx/rate?sell_currency=&buy_currency=");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "sell_currency": "USD",
    "buy_currency": "INR",
    "fx_rate": 64.5132,
    "margin": 0.5,
    "instarem_fx_rate": 64.1874
}

Get FX rates for a particular currency pair.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Query Parameters

ParameterDescription
sell_currency
REQUIRED
string
Return sell currency (3-letter ISO-4217 code).
buy_currency
REQUIRED
string
Return buy currency (3-letter ISO-4217 code).

Response (200)

sell_currency
string
Return sell currency (3-letter ISO-4217 code).
buy_currency
string
Return buy currency (3-letter ISO-4217 code).
fx_rate
number
Returns real time FX provider rate
margin
number
Returns margin percent as specified in the agreement for the book FX pair.
instarem_fx_rate
number
Returns Instarem FX rate.

Create Book FX by currency

Definition

POST https://api-test.instarem.com:4803/api/v1/bookfx/currency/create

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/bookfx/currency/create" \
--data {
    "sell_amount": 3478.7,
    "request_id": "1XkQkI34DA",
    "description": "Low balance in account.",
    "buy_currency": "MYR",
    "sell_currency": "USD",
    "book_fx_type": ""
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "sell_amount": 3478.7,
    "request_id": "1XkQkI34DA",
    "description": "Low balance in account.",
    "buy_currency": "MYR",
    "sell_currency": "USD",
    "book_fx_type": ""
})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("post", "https://api-test.instarem.com:4803/api/v1/bookfx/currency/create")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/bookfx/currency/create");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{
    ""sell_amount"": 3478.7,
    ""request_id"": ""1XkQkI34DA"",
    ""description"": ""Low balance in account."",
    ""buy_currency"": ""MYR"",
    ""sell_currency"": ""USD"",
    ""book_fx_type"": """"
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "confirmation_id": "USD-MYR-SJtfvAOQb",
    "buy_amount": 14921.71,
    "sell_amount": 3478.7,
    "from_account": 101950173983,
    "to_account": 101950173170,
    "buy_currency": "MYR",
    "sell_currency": "USD",
    "instarem_fx_rate": 4.2556,
    "fx_rate": 4.277,
    "margin_percent": 0.5,
    "margin_value": 0.17323,
    "created_at": "2017-06-22T05:35:13.387Z",
    "expiry_at": "2017-04-12T06:33:30.887Z"
}

Create a Book FX using a currency pair of default accounts.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Body Parameters

ParameterDescription
buy_amount
CONDITIONAL
number
Currency amount that the client buys. Must be specified if sell_amount is not specified.
sell_amount
CONDITIONAL
number
Currency amount that the client sells. Must be specified if buy_amount is not specified. Otherwise this is the amount sold by buying the exact buy_amount as specified in the request.
request_id
REQUIRED
string
A unique request ID specified by the client in the request.
description
REQUIRED
string
Narration for this Book FX request.
buy_currency
REQUIRED
string
Currency that the client buys (3-letter ISO-4217 code).
sell_currency
REQUIRED
string
Currency that the client sells (3-letter ISO-4217 code).
book_fx_type
OPTIONAL
string
One of [NOW, SCHEDULED] required

Response (200)

confirmation_id
string
Returns the unique confirmation ID generated by Instarem for successful Book Fx.
buy_amount
number
Returns a requested amount or a computed amount.
sell_amount
number
Returns a requested amount or a computed amount.
from_account
number
Returns 12 digit account number for a specified buy currency generated by Instarem.
to_account
number
Returns 12 digit account number for a specified sell currency generated by Instarem.
buy_currency
string
Return buy currency (3-letter ISO-4217 code).
sell_currency
string
Return sell currency (3-letter ISO-4217 code).
instarem_fx_rate
number
Returns Instarem FX rate.
fx_rate
number
Returns real time FX provider rate
margin_percent
number
Returns margin percent as specified in the agreement for the book FX pair.
margin_value
number
Returns computed margin value for the book FX pair.
created_at
string
Date and time (UTC) of book FX.
expiry_at
string
Date and time (UTC) when book FX expires.

Create Book FX by account

Definition

POST https://api-test.instarem.com:4803/api/v1/bookfx/account/create

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/bookfx/account/create" \
--data {
    "sell_amount": 3478.7,
    "request_id": "1XkQkI34DA",
    "description": "Low balance in account.",
    "from_account": 101760138799,
    "to_account": 101760782169,
    "book_fx_type": ""
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "sell_amount": 3478.7,
    "request_id": "1XkQkI34DA",
    "description": "Low balance in account.",
    "from_account": 101760138799,
    "to_account": 101760782169,
    "book_fx_type": ""
})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("post", "https://api-test.instarem.com:4803/api/v1/bookfx/account/create")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/bookfx/account/create");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{
    ""sell_amount"": 3478.7,
    ""request_id"": ""1XkQkI34DA"",
    ""description"": ""Low balance in account."",
    ""from_account"": 101760138799,
    ""to_account"": 101760782169,
    ""book_fx_type"": """"
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "confirmation_id": "USD-MYR-SJtfvAOQb",
    "buy_amount": 14921.71,
    "sell_amount": 3478.7,
    "from_account": 101950173983,
    "to_account": 101950173170,
    "buy_currency": "MYR",
    "sell_currency": "USD",
    "instarem_fx_rate": 4.2556,
    "fx_rate": 4.277,
    "margin_percent": 0.5,
    "margin_value": 0.17323,
    "created_at": "2017-06-22T05:35:13.387Z",
    "expiry_at": "2017-04-12T06:33:30.887Z"
}

Create Book FX for given accounts.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Body Parameters

ParameterDescription
buy_amount
CONDITIONAL
number
Currency amount that the client buys. Must be specified if sell_amount is not specified.
sell_amount
CONDITIONAL
number
Currency amount that the client sells. Must be specified if buy_amount is not specified. Otherwise this is the amount sold by buying the exact buy_amount as specified in the request.
request_id
REQUIRED
string
A unique request ID specified by the client in the request.
description
REQUIRED
string
Narration for this Book FX request.
from_account
REQUIRED
number
Account from the client buys.
to_account
REQUIRED
number
Account from the client sells.
book_fx_type
OPTIONAL
string
One of [NOW, SCHEDULED] required

Response (200)

confirmation_id
string
Returns the unique confirmation ID generated by Instarem for successful Book Fx.
buy_amount
number
Returns a requested amount or a computed amount.
sell_amount
number
Returns a requested amount or a computed amount.
from_account
number
Returns 12 digit account number for a specified buy currency generated by Instarem.
to_account
number
Returns 12 digit account number for a specified sell currency generated by Instarem.
buy_currency
string
Return buy currency (3-letter ISO-4217 code).
sell_currency
string
Return sell currency (3-letter ISO-4217 code).
instarem_fx_rate
number
Returns Instarem FX rate.
fx_rate
number
Returns real time FX provider rate
margin_percent
number
Returns margin percent as specified in the agreement for the book FX pair.
margin_value
number
Returns computed margin value for the book FX pair.
created_at
string
Date and time (UTC) of book FX.
expiry_at
string
Date and time (UTC) when book FX expires.

Get Book FX

Definition

GET https://api-test.instarem.com:4803/api/v1/bookfx/{confirmation_id}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/bookfx/{confirmation_id}" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/bookfx/{confirmation_id}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/bookfx/{confirmation_id}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "confirmation_id": "USD-MYR-SJtfvAOQb",
    "buy_amount": 14921.71,
    "sell_amount": 3478.7,
    "from_account": 101950173983,
    "to_account": 101950173170,
    "buy_currency": "MYR",
    "sell_currency": "USD",
    "instarem_fx_rate": 4.2556,
    "fx_rate": 4.277,
    "margin_percent": 0.5,
    "margin_value": 0.17323,
    "created_at": "2017-06-22T05:35:13.387Z",
    "expiry_at": "2017-04-12T06:33:30.887Z"
}

Get Book FX details by confirmation id.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Path Parameters

ParameterDescription
confirmation_id
REQUIRED
string
Confirmation ID created at the time of Book fx.

Response (200)

confirmation_id
string
Returns the unique confirmation ID generated by Instarem for successful Book Fx.
buy_amount
number
Returns a requested amount or a computed amount.
sell_amount
number
Returns a requested amount or a computed amount.
from_account
number
Returns 12 digit account number for a specified buy currency generated by Instarem.
to_account
number
Returns 12 digit account number for a specified sell currency generated by Instarem.
buy_currency
string
Return buy currency (3-letter ISO-4217 code).
sell_currency
string
Return sell currency (3-letter ISO-4217 code).
instarem_fx_rate
number
Returns Instarem FX rate.
fx_rate
number
Returns real time FX provider rate
margin_percent
number
Returns margin percent as specified in the agreement for the book FX pair.
margin_value
number
Returns computed margin value for the book FX pair.
created_at
string
Date and time (UTC) of book FX.
expiry_at
string
Date and time (UTC) when book FX expires.

Payment API

Create a new payment

Definition

POST https://api-test.instarem.com:4803/api/v1/payments/create

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/payments/create" \
--data {
    "request_id": "1XkQkI34DA",
    "account_number": 101950173983,
    "transaction_number": "ZQ1101",
    "destination_currency": "USD",
    "destination_amount": 1000,
    "local_conversion_currency": "USD",
    "statement_narrative": "Salary",
    "remitter_name": "Instarem",
    "remitter_account_type": "Company",
    "remitter_identification_type": "Company Registration No",
    "remitter_identification_number": "IN1244654",
    "remitter_country_code": "IN",
    "remitter_address": "Sakinaka Mumbai India",
    "remit_purpose_code": "IR001",
    "remitter_source_of_income": "Cross border remittence",
    "remitter_beneficiary_relationship": "Employee",
    "remitter_contact_number": "1234567890",
    "remitter_dob": "",
    "remitter_city": "Mumbai",
    "remitter_postcode": "4703101",
    "remitter_state": "Maharashtra",
    "beneficiary_name": "Mark Jobs",
    "beneficiary_address": "New york city USA",
    "beneficiary_city": "New York",
    "beneficiary_country_code": "US",
    "beneficiary_email": "mark@abc.com",
    "beneficiary_account_type": "Individual",
    "beneficiary_contact_number": "1234567891",
    "beneficiary_state": "New York",
    "beneficiary_postcode": "10005",
    "beneficiary_account_number": "12342346545123",
    "beneficiary_bank_account_type": "",
    "beneficiary_bank_name": "Bank of America",
    "beneficiary_bank_code": "",
    "beneficiary_identification_type": "Company Organization Code",
    "beneficiary_identification_value": "12345678-X",
    "routing_code_type_1": "SWIFT",
    "routing_code_value_1": "WSD12345",
    "routing_code_type_2": "ACH CODE",
    "routing_code_value_2": "222333123",
    "routing_code_type_3": "",
    "routing_code_value_3": ""
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "request_id": "1XkQkI34DA",
    "account_number": 101950173983,
    "transaction_number": "ZQ1101",
    "destination_currency": "USD",
    "destination_amount": 1000,
    "local_conversion_currency": "USD",
    "statement_narrative": "Salary",
    "remitter_name": "Instarem",
    "remitter_account_type": "Company",
    "remitter_identification_type": "Company Registration No",
    "remitter_identification_number": "IN1244654",
    "remitter_country_code": "IN",
    "remitter_address": "Sakinaka Mumbai India",
    "remit_purpose_code": "IR001",
    "remitter_source_of_income": "Cross border remittence",
    "remitter_beneficiary_relationship": "Employee",
    "remitter_contact_number": "1234567890",
    "remitter_dob": "",
    "remitter_city": "Mumbai",
    "remitter_postcode": "4703101",
    "remitter_state": "Maharashtra",
    "beneficiary_name": "Mark Jobs",
    "beneficiary_address": "New york city USA",
    "beneficiary_city": "New York",
    "beneficiary_country_code": "US",
    "beneficiary_email": "mark@abc.com",
    "beneficiary_account_type": "Individual",
    "beneficiary_contact_number": "1234567891",
    "beneficiary_state": "New York",
    "beneficiary_postcode": "10005",
    "beneficiary_account_number": "12342346545123",
    "beneficiary_bank_account_type": "",
    "beneficiary_bank_name": "Bank of America",
    "beneficiary_bank_code": "",
    "beneficiary_identification_type": "Company Organization Code",
    "beneficiary_identification_value": "12345678-X",
    "routing_code_type_1": "SWIFT",
    "routing_code_value_1": "WSD12345",
    "routing_code_type_2": "ACH CODE",
    "routing_code_value_2": "222333123",
    "routing_code_type_3": "",
    "routing_code_value_3": ""
})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("post", "https://api-test.instarem.com:4803/api/v1/payments/create")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/payments/create");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", @"{
    ""request_id"": ""1XkQkI34DA"",
    ""account_number"": 101950173983,
    ""transaction_number"": ""ZQ1101"",
    ""destination_currency"": ""USD"",
    ""destination_amount"": 1000,
    ""local_conversion_currency"": ""USD"",
    ""statement_narrative"": ""Salary"",
    ""remitter_name"": ""Instarem"",
    ""remitter_account_type"": ""Company"",
    ""remitter_identification_type"": ""Company Registration No"",
    ""remitter_identification_number"": ""IN1244654"",
    ""remitter_country_code"": ""IN"",
    ""remitter_address"": ""Sakinaka Mumbai India"",
    ""remit_purpose_code"": ""IR001"",
    ""remitter_source_of_income"": ""Cross border remittence"",
    ""remitter_beneficiary_relationship"": ""Employee"",
    ""remitter_contact_number"": ""1234567890"",
    ""remitter_dob"": """",
    ""remitter_city"": ""Mumbai"",
    ""remitter_postcode"": ""4703101"",
    ""remitter_state"": ""Maharashtra"",
    ""beneficiary_name"": ""Mark Jobs"",
    ""beneficiary_address"": ""New york city USA"",
    ""beneficiary_city"": ""New York"",
    ""beneficiary_country_code"": ""US"",
    ""beneficiary_email"": ""mark@abc.com"",
    ""beneficiary_account_type"": ""Individual"",
    ""beneficiary_contact_number"": ""1234567891"",
    ""beneficiary_state"": ""New York"",
    ""beneficiary_postcode"": ""10005"",
    ""beneficiary_account_number"": ""12342346545123"",
    ""beneficiary_bank_account_type"": """",
    ""beneficiary_bank_name"": ""Bank of America"",
    ""beneficiary_bank_code"": """",
    ""beneficiary_identification_type"": ""Company Organization Code"",
    ""beneficiary_identification_value"": ""12345678-X"",
    ""routing_code_type_1"": ""SWIFT"",
    ""routing_code_value_1"": ""WSD12345"",
    ""routing_code_type_2"": ""ACH CODE"",
    ""routing_code_value_2"": ""222333123"",
    ""routing_code_type_3"": """",
    ""routing_code_value_3"": """"
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "status": "IN_PROCESS",
    "sub_status": "",
    "status_description": "Payment in internal process",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30"
}

Send a payment to a beneficiary.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token
content-type
REQUIRED
string
The Content-Type entity header is used to indicate the media type of the resource. Expected value is application/json.

Body Parameters

ParameterDescription
request_id
REQUIRED
string
A unique request ID specified by the client in the request.
account_number
REQUIRED
number
12 digit account number as provided by Instarem.
transaction_number
REQUIRED
string
A unique transaction number specified by the client. Duplicate transaction number will be rejected.
destination_currency
REQUIRED
string
Currency the payment to be made to beneficiary (3-letter ISO-4217 code).
destination_amount
REQUIRED
number
Amount to be paid to beneficiary
local_conversion_currency
OPTIONAL
string
Beneficiary's country local currency
equivalent_amount
CONDITIONAL
number
This is the amount used for converting destination currency's amount, i.e. 100 EUR equivalent is converted to 120 USD destination amount and beneficiary is paid 120 USD. It Must be specified if destination_amount is 0
equivalent_currency
CONDITIONAL
string
This is the currency used for converting destination currency, i.e. EUR equivalent is converted to USD destination currency. Must be specified if equivalent amount is present.
statement_narrative
REQUIRED
string
Payment Narration
remitter_name
REQUIRED
string
Remitter name
remitter_account_type
REQUIRED
string
Remitter account type either Individual or Company
remitter_identification_type
REQUIRED
string
One of Registration Number, Registration ID, ACRA,Travel agent License number,Company Registration No,License No
remitter_identification_number
REQUIRED
string
Remitter identification number is the document identifier i.e. IN1244654
remitter_country_code
REQUIRED
string
Remitter country code (2-letter ISO 3166-2 country code)
remitter_address
REQUIRED
string
Remitter address
remit_purpose_code
REQUIRED
string
The purpose for the payment, i.e. IR001. Use Instarem's data reference for purpose code.
remitter_source_of_income
OPTIONAL
string
Remitter source of income.
remitter_beneficiary_relationship
OPTIONAL
string
Remitter beneficiary relationship
remitter_contact_number
OPTIONAL
string
Remitter contact number
remitter_dob
OPTIONAL
string
Remitter Date of birth (YYYY-MM-DD)
remitter_city
OPTIONAL
string
Remitter city
remitter_postcode
OPTIONAL
string
Remitter postcode
remitter_state
OPTIONAL
string
Remitter state
beneficiary_name
REQUIRED
string
Beneficiary name
beneficiary_address
REQUIRED
string
Beneficiary address
beneficiary_city
OPTIONAL
string
Beneficiary city
beneficiary_country_code
REQUIRED
string
Beneficiary country code (2-letter ISO 3166-2 country code)
beneficiary_email
OPTIONAL
string
Beneficiary email
beneficiary_account_type
REQUIRED
string
Beneficary account type either Individual or Company
beneficiary_contact_number
OPTIONAL
string
Beneficiary contact number
beneficiary_state
OPTIONAL
string
Beneficiary state
beneficiary_postcode
OPTIONAL
string
Beneficiary postcode
beneficiary_account_number
REQUIRED
string
Beneficiary account number
beneficiary_bank_account_type
OPTIONAL
string
Beneficiary Bank Account Type can be one of Checking, Saving or Maestra
beneficiary_bank_name
REQUIRED
string
Beneficiary bank name
beneficiary_bank_code
OPTIONAL
string
Beneficiary bank code
beneficiary_identification_type
OPTIONAL
string
One of Company Organization Code, Company Social Credit Code, Passport, Company Registration No., CUIT, CUIL, CPF, CNPJ, RUT, CC, NIT, CE, PASS, DNI, RUC, CI.
beneficiary_identification_value
OPTIONAL
string
Value corresponding to Beneficiary Identification Type
routing_code_type_1
OPTIONAL
string
Routing code type 1 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BSB CODE for Australia, BANK CODE for HongKong)
routing_code_value_1
OPTIONAL
string
Routing code value 1 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE)
routing_code_type_2
OPTIONAL
string
Routing code type 2 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BSB CODE for Australia, BANK CODE for HongKong)
routing_code_value_2
OPTIONAL
string
Routing code value 2 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE)
routing_code_type_3
OPTIONAL
string
Routing code type 3 (eg SWIFT for all Countries, IFSC for India, SORT CODE for UK, ACH CODE for USA, BSB CODE for Australia, BANK CODE for HongKong)
routing_code_value_3
OPTIONAL
string
Routing code value 3 (eg ADCBINBB or ADCBINBB123 for SWIFT, SBIN0000058 for IFSC, 100000 for SORT CODE, 111000025 for ACH CODE, 012515 for BSB CODE, 151 for BANK CODE)

Response (200)

reference_number
string
payment_id
string
status
string
sub_status
string
status_description
string
created_at
string
updated_at
string

Get payment by ID

Definition

GET https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/payments/id/{payment_id}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "status": "PAID",
    "autobookfx_confirmation_id": "USD-MYR-SJtfvAOQb",
    "sub_status": "",
    "status_description": "Payment successfully done",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30"
}

Get details for a specific payment by payment_id

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token

Path Parameters

ParameterDescription
payment_id
REQUIRED
string
This is the confirmation unique payment ID generated by Instarem.

Response (200)

reference_number
string
payment_id
string
status
string
autobookfx_confirmation_id
string
Returns the unique confirmation ID generated by Instarem for successful AutoBook Fx.
sub_status
string
status_description
string
created_at
string
updated_at
string

Get payment by Reference

Definition

GET https://api-test.instarem.com:4803/api/v1/payments/reference/{reference_number}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/payments/reference/{reference_number}" \

--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
var data = JSON.stringify({})
var xhr = new XMLHttpRequest();
xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});
xhr.open("get", "https://api-test.instarem.com:4803/api/v1/payments/reference/{reference_number}")
xhr.setRequestHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
xhr.send(data);
var client = new RestClient("https://api-test.instarem.com:4803/api/v1/payments/reference/{reference_number}");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM");
request.AddParameter("application/json", @"{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "reference_number": "ZQ1101",
    "payment_id": "PY10001485",
    "autobookfx_confirmation_id": "USD-MYR-SJtfvAOQb",
    "status": "PAID",
    "sub_status": "",
    "status_description": "Payment successfully paid",
    "created_at": "2017-06-16T17:25:52.136+05:30",
    "updated_at": "2017-06-16T17:26:20.670+05:30"
}

Get details for a specific payment by reference_number

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token

Path Parameters

ParameterDescription
reference_number
REQUIRED
string
This is the unique transaction number as requested by the client.

Response (200)

reference_number
string
payment_id
string
autobookfx_confirmation_id
string
Returns the unique confirmation ID generated by Instarem for successful AutoBook Fx.
status
string
sub_status
string
status_description
string
created_at
string
updated_at
string

Data Reference

Payment Status

Payment status response and its description

Status Description
IN_PROCESS Payment in internal process
COMPLIANCE_VERIFICATION Payment with compliance for further verification
COMPLIANCE_REJECTED Payment rejected by compliance
COMPLIANCE_APPROVED Payment approved by compliance
INFO_REQUESTED Additional Remitter / Beneficiary information requested for compliance verification
PG_PROCESSING Payment sent to benefiary bank
PAID Payment successfully paid
RETURNED Payment returned from benefiary bank
CANCELLED Payment cancelled
ERROR Payment instruction erroroneous, appended by exact error response from beneficiary bank

Purpose Code

Payment purpose code is used to identify the purpose of each and every payment.

Purpose Code Description
IR001 Transfer to own account
IR002 Family Maintenance
IR003 Education-related student expenses
IR004 Medical Treatment
IR005 Hotel Accomodation
IR006 Travel
IR007 Utility Bills
IR008 Repayment of Loans
IR009 Tax Payment
IR010 Purchase of Residential Property
IR011 Payment of Property Rental
IR012 Insurance Premium
IR013 Product indemnity insurance
IR014 Insurance Claims Payment
IR015 Mutual Fund Investment
IR016 Investment in Shares
IR017 Donations
IR01801 Information Service Charges
IR01802 Advertising & Public relations-related expenses
IR01803 Royalty fees, trademark fees, patent fees, and copyright fees
IR01804 Fees for brokers, front end fee, commitment fee, guarantee fee and custodian fee
IR01805 Fees for advisors, technical assistance, and academic kpurpose_code_numberwledge, including remuneration for specialists
IR01806 Representative office expenses
IR01807 Construction costs/expenses
IR01808 Transportation fees for goods
IR01809 For payment of exported goods
IR01810 Delivery fees for goods
IR01811 General Goods Trades - Offine trade

Source of Income

Default value of remitter_source_of_income is "Business Relations".

InstaFIX

Description

FIX messages are used to fetch MassPay Live FX rates.

Authentication

Obtain an Authentication token by specifying the MPFClientKey and MPFClientSecret. An Authentication token is required for requesting FX rates.

Request

<message name="MassPayAuthenticateRequest" msgtype="MPA" msgcat="app">
<field name="MPFClientKey" required="Y"/>
<field name="MPFClientSecret" required="Y"/>
</message>

Response

<message name="MassPayAuthenticateResponse" msgtype="MPa" msgcat="app">
<field name="MPFAuthToken" required="Y"/>
</message>

Get FX rates

Get FX rates for a particular currency pair.

Request

<message name="MassPayGetFXRateRequest" msgtype="MPX" msgcat="app">
<field name="MPFAuthToken" required="Y"/>
<field name="MPFSellCurrency" required="Y"/>
<field name="MPFBuyCurrency" required="Y"/>
</message>

Response

<message name="MassPayGetFXRateResponse" msgtype="MPx" msgcat="app">
<field name="MPFSellCurrency" required="Y"/>
<field name="MPFBuyCurrency" required="Y"/>
<field name="MPFFXRate" required="Y"/>
<field name="MPFMargin" required="Y"/>
<field name="MPFInstaremFXRate" required="Y"/>
</message>

Create Book FX By Currency 

Create a Book FX using a currency pair of default accounts.

Request

<message name="MassPayCreateBookFXRequestByCurrency" msgtype="MPG" msgcat="app"> <field name="MPFAuthToken" required="Y"/> <field name="MPFRequestId" required="Y"/> <field name="MPFDescription" required="Y"/> <field name="MPFBuyCurrency" required="Y"/> <field name="MPFSellCurrency" required="Y"/> <field name="MPFBuyAmount" required="N"/> Currency amount that the client buys. Must be specified if sell amount is not specified. <field name="MPFSellAmount" required="N"/> Currency amount that the client sells. Must be specified if buy amount is not specified. </message>

Response

<message name="MassPayBookFXResponse" msgtype="MPfgh" msgcat="app"> <field name="MPFConfirmationId" required="Y"/> <field name="MPFBuyAmount" required="Y"/> <field name="MPFSellAmount" required="Y"/> <field name="MPFFromAccount" required="Y"/> <field name="MPFToAccount" required="Y"/> <field name="MPFBuyCurrency" required="Y"/> <field name="MPFSellCurrency" required="Y"/> <field name="MPFInstaremFXRate" required="Y"/> <field name="MPFFXRate" required="Y"/> <field name="MPFMarginPercent" required="Y"/> <field name="MPFMarginValue" required="Y"/> <field name="MPFCreatedAt" required="Y"/> </message>

Create Book FX By Account 

Create Book FX for given accounts

Request

<message name="MassPayCreateBookFXRequestByAccount" msgtype="MPH" msgcat="app"> <field name="MPFAuthToken" required="Y"/> <field name="MPFRequestId" required="Y"/> <field name="MPFDescription" required="Y"/> <field name="MPFFromAccount" required="Y"/> <field name="MPFToAccount" required="Y"/> <field name="MPFBuyAmount" required="N"/> Currency amount that the client buys. Must be specified if sell amount is not specified. <field name="MPFSellAmount" required="N"/> Currency amount that the client sells. Must be specified if buy amount is not specified. </message> </message>

Response

<message name="MassPayBookFXResponse" msgtype="MPfgh" msgcat="app"> <field name="MPFConfirmationId" required="Y"/> <field name="MPFBuyAmount" required="Y"/> <field name="MPFSellAmount" required="Y"/> <field name="MPFFromAccount" required="Y"/> <field name="MPFToAccount" required="Y"/> <field name="MPFBuyCurrency" required="Y"/> <field name="MPFSellCurrency" required="Y"/> <field name="MPFInstaremFXRate" required="Y"/> <field name="MPFFXRate" required="Y"/> <field name="MPFMarginPercent" required="Y"/> <field name="MPFMarginValue" required="Y"/> <field name="MPFCreatedAt" required="Y"/> </message>

Error Message

<message name="MassPayReject" msgtype="MPR" msgcat="app">
<field name="MPFStatusCode" required="Y"/>
<field name="MPError" required="Y"/>
<field name="MPFMessage" required="Y"/>
</message>

InstaFIX Fields

Fields

<field number="10000" name="MPFClientKey" type="STRING"/>
<field number="10001" name="MPFClientSecret" type="STRING"/>
<field number="10002" name="MPFAuthToken" type="STRING"/>
<field number="10003" name="MPFStatusCode" type="STRING"/>
<field number="10004" name="MPFError" type="STRING"/>
<field number="10005" name="MPFMessage" type="STRING"/>
<field number="10006" name="MPFAccountNumber" type="STRING"/>
<field number="10007" name="MPFCurrency" type="STRING"/>
<field number="10008" name="MPFAutoBookFXSequence" type="STRING"/>
<field number="10009" name="MPFActive" type="BOOLEAN"/>
<field number="10010" name="MPFDefault" type="BOOLEAN"/>
<field number="10011" name="MPFNumberOfEntries" type="INT"/>
<field number="10012" name="MPFBuyAmount" type="PRICE"/>
<field number="10013" name="MPFSellAmount" type="PRICE"/>
<field number="10014" name="MPFFromAccount" type="STRING"/>
<field number="10015" name="MPFToAccount" type="STRING"/>
<field number="10016" name="MPFBuyCurrency" type="STRING"/>
<field number="10017" name="MPFSellCurrency" type="STRING"/>
<field number="10018" name="MPFInstaremFXRate" type="PRICE"/>
<field number="10019" name="MPFFXRate" type="PRICE"/>
<field number="10020" name="MPFMarginPercent" type="FLOAT"/>
<field number="10021" name="MPFMarginValue" type="FLOAT"/>
<field number="10022" name="MPFCreatedAt" type="STRING"/>
<field number="10023" name="MPFUpdatedAt" type="STRING"/>
<field number="10024" name="MPFRequestId" type="STRING"/>
<field number="10025" name="MPFDescription" type="STRING"/>
<field number="10026" name="MPFPaymentId" type="STRING"/>
<field number="10027" name="MPFReferenceId" type="STRING"/>
<field number="10028" name="MPFStatus" type="STRING"/>
<field number="10029" name="MPFSubStatus" type="STRING"/>
<field number="10030" name="MPFAutoBookFxConfirmationId" type="STRING"/>
<field number="10031" name="MPFStatusDescription" type="STRING"/>
<field number="10032" name="MPFTransactionNumber" type="STRING"/>
<field number="10033" name="MPFDestinationCurrency" type="STRING"/>
<field number="10034" name="MPFDestinationAmount" type="PRICE"/>
<field number="10035" name="MPFLocalConversionCurrency" type="PRICE"/>
<field number="10036" name="MPFEquivalentCurrency" type="PRICE"/>
<field number="10037" name="MPFEquivalentAmount" type="STRING"/>
<field number="10038" name="MPFStatementNarrative" type="STRING"/>
<field number="10039" name="MPFLabel" type="STRING"/>
<field number="10040" name="MPFRemitterName" type="STRING"/>
<field number="10041" name="MPFRemitterAccountType" type="STRING"/>
<field number="10042" name="MPFRemitterIdentificationType" type="STRING"/>
<field number="10043" name="MPFRemitterIdentificationNumber" type="STRING"/>
<field number="10044" name="MPFRemitterCountryCode" type="STRING"/>
<field number="10045" name="MPFRemitterAddress" type="STRING"/>
<field number="10046" name="MPFRemitPurposeCode" type="STRING"/>
<field number="10047" name="MPFRemitterSourceOfIncome" type="STRING"/>
<field number="10048" name="MPFRemitterBeneficiaryRelationship" type="STRING"/>
<field number="10049" name="MPFRemitterContactNumber" type="STRING"/>
<field number="10050" name="MPFRemitterDob" type="STRING"/>
<field number="10051" name="MPFRemitterCity" type="STRING"/>
<field number="10052" name="MPFRemitterPostcode" type="STRING"/>
<field number="10053" name="MPFRemitterState" type="STRING"/>
<field number="10054" name="MPFBeneficiaryName" type="STRING"/>
<field number="10055" name="MPFBeneficiaryAddress" type="STRING"/>
<field number="10056" name="MPFBeneficiaryCity" type="STRING"/>
<field number="10057" name="MPFBeneficiaryCountryCode" type="STRING"/>
<field number="10058" name="MPFBeneficiaryEmail" type="STRING"/>
<field number="10059" name="MPFBeneficiaryAccountType" type="STRING"/>
<field number="10060" name="MPFBeneficiaryContactNumber" type="STRING"/>
<field number="10061" name="MPFBeneficiaryState" type="STRING"/>
<field number="10062" name="MPFBeneficiaryPostcode" type="STRING"/>
<field number="10063" name="MPFBeneficiaryAccountNumber" type="STRING"/>
<field number="10064" name="MPFBeneficiaryBankName" type="STRING"/>
<field number="10065" name="MPFBeneficiaryBankCode" type="STRING"/>
<field number="10066" name="MPFRoutingCodeType1" type="STRING"/>
<field number="10067" name="MPFRoutingCodeValue1" type="STRING"/>
<field number="10068" name="MPFRoutingCodeType2" type="STRING"/>
<field number="10069" name="MPFRoutingCodeValue2" type="STRING"/>
<field number="10070" name="MPFRoutingCodeType3" type="STRING"/>
<field number="10071" name="MPFRoutingCodeValue3" type="STRING"/>
<field number="10073" name="MPFConfirmationId" type="STRING"/>
<field number="10074" name="MPFMargin" type="FLOAT"/>

Field numbers and data type for FIX message.

Field number Name Data type
10000 MPFClientKey STRING
10001 MPFClientSecret STRING
10002 MPFAuthToken STRING
10003 MPFStatusCode STRING
10004 MPFError STRING
10005 MPFMessage STRING
10006 MPFAccountNumber STRING
10007 MPFCurrency STRING
10008 MPFAutoBookFXSequence STRING
10009 MPFActive BOOLEAN
10010 MPFDefault BOOLEAN
10011 MPFNumberOfEntries INT
10012 MPFBuyAmount PRICE
10013 MPFSellAmount PRICE
10014 MPFFromAccount STRING
10015 MPFToAccount STRING
10016 MPFBuyCurrency STRING
10017 MPFSellCurrency STRING
10018 MPFInstaremFXRate PRICE
10019 MPFFXRate PRICE
10020 MPFMarginPercent FLOAT
10021 MPFMarginValue FLOAT
10022 MPFCreatedAt STRING
10023 MPFUpdatedAt STRING
10024 MPFRequestId STRING
10025 MPFDescription STRING
10026 MPFPaymentId STRING
10027 MPFReferenceId STRING
10028 MPFStatus STRING
10029 MPFSubStatus STRING
10030 MPFAutoBookFxConfirmationId STRING
10031 MPFStatusDescription STRING
10032 MPFTransactionNumber STRING
10033 MPFDestinationCurrency STRING
10034 MPFDestinationAmount PRICE
10035 MPFLocalConversionCurrency PRICE
10036 MPFEquivalentCurrency PRICE
10037 MPFEquivalentAmount STRING
10038 MPFStatementNarrative STRING
10039 MPFLabel STRING
10040 MPFRemitterName STRING
10041 MPFRemitterAccountType STRING
10042 MPFRemitterIdentificationType STRING
10043 MPFRemitterIdentificationNumber STRING
10044 MPFRemitterCountryCode STRING
10045 MPFRemitterAddress STRING
10046 MPFRemitPurposeCode STRING
10047 MPFRemitterSourceOfIncome STRING
10048 MPFRemitterBeneficiaryRelationship STRING
10049 MPFRemitterContactNumber STRING
10050 MPFRemitterDob STRING
10051 MPFRemitterCity STRING
10052 MPFRemitterPostcode STRING
10053 MPFRemitterState STRING
10054 MPFBeneficiaryName STRING
10055 MPFBeneficiaryAddress STRING
10056 MPFBeneficiaryCity STRING
10057 MPFBeneficiaryCountryCode STRING
10058 MPFBeneficiaryEmail STRING
10059 MPFBeneficiaryAccountType STRING
10060 MPFBeneficiaryContactNumber STRING
10061 MPFBeneficiaryState STRING
10062 MPFBeneficiaryPostcode STRING
10063 MPFBeneficiaryAccountNumber STRING
10064 MPFBeneficiaryBankName STRING
10065 MPFBeneficiaryBankCode STRING
10066 MPFRoutingCodeType1 STRING
10067 MPFRoutingCodeValue1 STRING
10068 MPFRoutingCodeType2 STRING
10069 MPFRoutingCodeValue2 STRING
10070 MPFRoutingCodeType3 STRING
10071 MPFRoutingCodeValue3 STRING
10073 MPFConfirmationId STRING
10074 MPFMargin FLOAT
bash javascript csharp