NAV undefined
bash javascript csharp

API Version

img

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.

Getting Started

In this example, we want to pay a $10,000 invoice in AUD to Australia, funded by your available account balance in CNY. The following examples demonstrate how this is achieved using the Instarem Client API.

1. Authentication

First, login using your Client ID and API Key through the Authentication API endpoint. On success, you will be granted an access token that allows you to access all API features.

3. Book FX

Once you are happy with the provided AUD/CNY Quote, you may create a Conversion to sell CNY to receive $10,000 AUD. Conversion will happen in two-business days for most currencies unless settlement_date is specified.

4. Make Payment

Finally we want to create a payment to send AUD $10,000 to the beneficiary.

5. Check Payment status

Check the status of the payment by calling the Get payment by ID endpoint

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.
409 Duplicate Transaction -- Transaction with the given number is already in process.
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.

Versioning

Nium API supports versioing when API signature is updated and not backward compatible with old API

When do we update the API versions?

We update the API version whenever new API is not compatible with the old API due to following reasons

How do we handle new versions?

We update the version number in the API URL. Following is the format we follow for the API versions

https://<domain>/api//v<number>/<path>

/v<number> number could be any whole number starting from 1 and increament by 1 with every subsequent backward incompatible change

What precautions to take before upgrading to latest versions?

Changelog

The following section list all the API updates with the date of the release (yyyy-MM-dd)
We strongly recommend to check the API updates before committing the API migration

2020-04-14 (latest)

2017-05-31

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, Token is valid for 24 hrs.

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=&type=" \

--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=&type=")
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=&type=");
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,
    "expiry_at": ""
}

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
Source currency (3-letter ISO-4217 code).
buy_currency
REQUIRED
string
Destination currency (3-letter ISO-4217 code).
type
OPTIONAL
string
One of ["", PREFUNDING, SCHEDULED1, SCHEDULED2]. If left empty, this field defaults to PREFUNDING

Response (200)

sell_currency
string
Source currency (3-letter ISO-4217 code).
buy_currency
string
Destination currency (3-letter ISO-4217 code).
fx_rate
number
Real time FX provider rate
margin
number
Margin percentage as specified in the agreement for the book FX pair.
instarem_fx_rate
number
Instarem FX rate.
expiry_at
string
Expiry time of the 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.",
    "book_fx_type": "",
    "buy_currency": "MYR",
    "sell_currency": "USD"
}
--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.",
    "book_fx_type": "",
    "buy_currency": "MYR",
    "sell_currency": "USD"
})
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."",
    ""book_fx_type"": """",
    ""buy_currency"": ""MYR"",
    ""sell_currency"": ""USD""
}", 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.
book_fx_type
OPTIONAL
string
One of ["", PREFUNDING, SCHEDULED1, SCHEDULED2]. Defaults to the client's default FX type if left empty.
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).

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.",
    "book_fx_type": "",
    "from_account": 101760138799,
    "to_account": 101760782169
}
--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.",
    "book_fx_type": "",
    "from_account": 101760138799,
    "to_account": 101760782169
})
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."",
    ""book_fx_type"": """",
    ""from_account"": 101760138799,
    ""to_account"": 101760782169
}", 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.
book_fx_type
OPTIONAL
string
One of ["", PREFUNDING, SCHEDULED1, SCHEDULED2]. Defaults to the client's default FX type if left empty.
from_account
REQUIRED
number
Account from the client buys.
to_account
REQUIRED
number
Account from the client sells.

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.

Funding API

Create Funding entry

Definition

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

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/fund/create" \
--data {
    "account_number": 101950173983,
    "amount": 1000,
    "instarem_deposit_account": "CIMB-2000496328-USD",
    "payment_reference": "Funding for transactions in USD"
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "account_number": 101950173983,
    "amount": 1000,
    "instarem_deposit_account": "CIMB-2000496328-USD",
    "payment_reference": "Funding for transactions in USD"
})
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/fund/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/fund/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", @"{
    ""account_number"": 101950173983,
    ""amount"": 1000,
    ""instarem_deposit_account"": ""CIMB-2000496328-USD"",
    ""payment_reference"": ""Funding for transactions in USD""
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "account_number": "101950173983",
    "amount": 1000,
    "currency": "USD",
    "gl_reference_number": "1527252825722",
    "status": "PENDING",
    "created_at": "2018-05-28T06:12:48.216+05:30",
    "updated_at": "2018-05-28T06:12:48.216+05:30"
}

Create a funding entry.

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
account_number
REQUIRED
number
12 digit account number as provided by Instarem.
amount
REQUIRED
number
Amount to be funded
instarem_deposit_account
REQUIRED
string
Instarem account used for depositing funds. (Format: BankName-AccountNumber-Currency )
payment_reference
REQUIRED
string
Description for the funding entry

Response (200)

account_number
string
12 digit account number as provided by Instarem.
amount
number
Amount for which the funding was made
currency
string
Currency in which the funding was done
gl_reference_number
string
Ledger reference number generated by Instarem.
status
string
Current status of the funding entry
created_at
string
Date and time (UTC) of funding.
updated_at
string
Date and time (UTC) of funding.

Get Funding entry by Reference

Definition

GET  https://api-test.instarem.com:4803/api/v1/fund/reference/{gl_reference_number}

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/fund/reference/{gl_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/fund/reference/{gl_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/fund/reference/{gl_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

{
    "gl_reference_number": "1527766007875",
    "status": "PENDING",
    "amount": 1000.78,
    "currency": "SGD",
    "created_at": "2018-05-31T11:26:47.949+05:30",
    "updated_at": "2018-05-31T11:26:47.949+05:30"
}

Get funding by reference number.

Header Parameters

ParameterDescription
authorization
REQUIRED
string
Authentication token

Path Parameters

ParameterDescription
gl_reference_number
REQUIRED
string
This is the ledger reference number generated by Instarem.

Response (200)

gl_reference_number
string
Ledger reference number generated by Instarem.
status
string
Current status of the funding entry
amount
number
Amount for which the funding was made
currency
string
Currency in which the funding was done
created_at
string
Date and time (UTC) of funding.
updated_at
string
Date and time (UTC) of funding.

Payment API

Create a new payment v2

Definition

POST  https://api-test.instarem.com:4803/api/v2/payouts

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v2/payouts" \
--data {
    "request_id": "1XkQkI34DA",
    "transaction_number": "ZQ1101",
    "destination_account": 1024501739830,
    "destination_currency": "USD",
    "local_conversion_currency": "USD",
    "statement_narrative": "Salary",
    "original_remitter_fi": "",
    "source_account": 101950173983,
    "source_amount": 1000,
    "fee_payer": "BEN",
    "beneficiary": {
        "name": "Mark Jobs",
        "address": "New york city USA",
        "city": "New York",
        "country_code": "US",
        "email": "example@mail.com",
        "account_type": "Individual",
        "contact_number": "1234567891",
        "state": "New York",
        "postcode": "10005",
        "wallet_id": "64000000003",
        "account_number": "12342346545123",
        "bank_account_type": "Checking",
        "bank_name": "Bank of America",
        "bank_code": "545343545345354",
        "identification_type": "Company Organization Code",
        "identification_value": "12345678-X",
        "card_number": "1234123412341234",
        "card_expiry_date": "2020-12",
        "relationship": "Employee"
    },
    "remitter": {
        "name": "Instarem",
        "given_name": true,
        "account_type": "Company",
        "bank_account_number": "10022206393",
        "identification_type": "Company Registration No",
        "identification_number": "IN1244654",
        "country_code": "IN",
        "address": "Sakinaka Mumbai India",
        "purpose_code": "IR001",
        "source_of_income": "Cross border remittence",
        "contact_number": "1234567890",
        "dob": "1980-01-01",
        "city": "Mumbai",
        "postcode": "4703101",
        "state": "Maharashtra",
        "source_of_funds": "",
        "place_of_birth": "IN",
        "nationality": "IN",
        "occupation": "EXECUTIVE"
    },
    "payout_options": {
        "fx_hold_id": "5aa22016-10da-11ea-9a9f-362b9e155667",
        "deduct_amount": 100
    },
    "additional_info": {
        "trade_order_id": "",
        "trade_time": "",
        "trade_currency": "",
        "trade_amount": "",
        "trade_name": "",
        "trade_count": "",
        "goods_carrier": "",
        "service_detail": "",
        "service_time": "",
        "cash_pickup": ""
    },
    "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": "",
    "payout_method": "CASH_PAYOUT"
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "request_id": "1XkQkI34DA",
    "transaction_number": "ZQ1101",
    "destination_account": 1024501739830,
    "destination_currency": "USD",
    "local_conversion_currency": "USD",
    "statement_narrative": "Salary",
    "original_remitter_fi": "",
    "source_account": 101950173983,
    "source_amount": 1000,
    "fee_payer": "BEN",
    "beneficiary": {
        "name": "Mark Jobs",
        "address": "New york city USA",
        "city": "New York",
        "country_code": "US",
        "email": "example@mail.com",
        "account_type": "Individual",
        "contact_number": "1234567891",
        "state": "New York",
        "postcode": "10005",
        "wallet_id": "64000000003",
        "account_number": "12342346545123",
        "bank_account_type": "Checking",
        "bank_name": "Bank of America",
        "bank_code": "545343545345354",
        "identification_type": "Company Organization Code",
        "identification_value": "12345678-X",
        "card_number": "1234123412341234",
        "card_expiry_date": "2020-12",
        "relationship": "Employee"
    },
    "remitter": {
        "name": "Instarem",
        "given_name": true,
        "account_type": "Company",
        "bank_account_number": "10022206393",
        "identification_type": "Company Registration No",
        "identification_number": "IN1244654",
        "country_code": "IN",
        "address": "Sakinaka Mumbai India",
        "purpose_code": "IR001",
        "source_of_income": "Cross border remittence",
        "contact_number": "1234567890",
        "dob": "1980-01-01",
        "city": "Mumbai",
        "postcode": "4703101",
        "state": "Maharashtra",
        "source_of_funds": "",
        "place_of_birth": "IN",
        "nationality": "IN",
        "occupation": "EXECUTIVE"
    },
    "payout_options": {
        "fx_hold_id": "5aa22016-10da-11ea-9a9f-362b9e155667",
        "deduct_amount": 100
    },
    "additional_info": {
        "trade_order_id": "",
        "trade_time": "",
        "trade_currency": "",
        "trade_amount": "",
        "trade_name": "",
        "trade_count": "",
        "goods_carrier": "",
        "service_detail": "",
        "service_time": "",
        "cash_pickup": ""
    },
    "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": "",
    "payout_method": "CASH_PAYOUT"
})
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/v2/payouts")
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/v2/payouts");
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"",
    ""transaction_number"": ""ZQ1101"",
    ""destination_account"": 1024501739830,
    ""destination_currency"": ""USD"",
    ""local_conversion_currency"": ""USD"",
    ""statement_narrative"": ""Salary"",
    ""original_remitter_fi"": """",
    ""source_account"": 101950173983,
    ""source_amount"": 1000,
    ""fee_payer"": ""BEN"",
    ""beneficiary"": {
        ""name"": ""Mark Jobs"",
        ""address"": ""New york city USA"",
        ""city"": ""New York"",
        ""country_code"": ""US"",
        ""email"": ""example@mail.com"",
        ""account_type"": ""Individual"",
        ""contact_number"": ""1234567891"",
        ""state"": ""New York"",
        ""postcode"": ""10005"",
        ""wallet_id"": ""64000000003"",
        ""account_number"": ""12342346545123"",
        ""bank_account_type"": ""Checking"",
        ""bank_name"": ""Bank of America"",
        ""bank_code"": ""545343545345354"",
        ""identification_type"": ""Company Organization Code"",
        ""identification_value"": ""12345678-X"",
        ""card_number"": ""1234123412341234"",
        ""card_expiry_date"": ""2020-12"",
        ""relationship"": ""Employee""
    },
    ""remitter"": {
        ""name"": ""Instarem"",
        ""given_name"": true,
        ""account_type"": ""Company"",
        ""bank_account_number"": ""10022206393"",
        ""identification_type"": ""Company Registration No"",
        ""identification_number"": ""IN1244654"",
        ""country_code"": ""IN"",
        ""address"": ""Sakinaka Mumbai India"",
        ""purpose_code"": ""IR001"",
        ""source_of_income"": ""Cross border remittence"",
        ""contact_number"": ""1234567890"",
        ""dob"": ""1980-01-01"",
        ""city"": ""Mumbai"",
        ""postcode"": ""4703101"",
        ""state"": ""Maharashtra"",
        ""source_of_funds"": """",
        ""place_of_birth"": ""IN"",
        ""nationality"": ""IN"",
        ""occupation"": ""EXECUTIVE""
    },
    ""payout_options"": {
        ""fx_hold_id"": ""5aa22016-10da-11ea-9a9f-362b9e155667"",
        ""deduct_amount"": 100
    },
    ""additional_info"": {
        ""trade_order_id"": """",
        ""trade_time"": """",
        ""trade_currency"": """",
        ""trade_amount"": """",
        ""trade_name"": """",
        ""trade_count"": """",
        ""goods_carrier"": """",
        ""service_detail"": """",
        ""service_time"": """",
        ""cash_pickup"": """"
    },
    ""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"": """",
    ""payout_method"": ""CASH_PAYOUT""
}", 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",
    "hold_fx_expires_on": "2017-06-17T17: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.
transaction_number
REQUIRED
string
A unique transaction number specified by the client. Duplicate transaction number will be rejected.
destination_account
OPTIONAL
number
Destination account number.
destination_currency
OPTIONAL
string
Destination currency (3-letter ISO-4217 code).
local_conversion_currency
OPTIONAL
string
Beneficiary's country local currency.
statement_narrative
REQUIRED
string
Payment Narration.
original_remitter_fi
OPTIONAL
string
source_account
REQUIRED
number
Amount to send. Mutually exclusive with destination_amount.
source_amount
OPTIONAL
number
Source account number.
fee_payer
REQUIRED
string
Indicates who pays the taxes. OUR - remitter, BEN - beneficiary.
beneficiary.name
string
Beneficiary name.
beneficiary.address
string
Beneficiary address.
beneficiary.city
string
Beneficiary city.
beneficiary.country_code
string
Beneficiary country code (2-letter ISO 3166-2 country code).
beneficiary.email
string
Beneficiary email.
beneficiary.account_type
string
Beneficary account type either Individual or Company.
beneficiary.contact_number
string
Beneficiary contact number.
beneficiary.state
string
Beneficiary state.
beneficiary.postcode
string
Beneficiary postcode.
beneficiary.wallet_id
string
Beneficiary wallet id.
beneficiary.account_number
string
Beneficiary account number.
beneficiary.bank_account_type
string
Beneficiary Bank Account Type can be one of Checking, Saving or Maestra.
beneficiary.bank_name
string
Beneficiary bank name.
beneficiary.bank_code
string
Beneficiary bank code.
beneficiary.identification_type
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
string
Value corresponding to Beneficiary Identification Type.
beneficiary.card_number
string
Card number with.
beneficiary.card_expiry_date
string
Card expiration date in the format YYYY-MM.
beneficiary.relationship
string
Remitter beneficiary relationship.
remitter.name
string
Remitter name.
remitter.given_name
boolean
Indicates whether the remitters name should allow initials.
remitter.account_type
string
Remitter account type either Individual or Company.
remitter.bank_account_number
string
Remitter Bank Account Number.
remitter.identification_type
string
One of Registration Number, Registration ID, ACRA,Travel agent License number,Company Registration No,License No,ARNU,DRLC,NIDN,CCPT.
remitter.identification_number
string
Remitter identification number is the document identifier i.e. IN1244654.
remitter.country_code
string
Remitter country code (2-letter ISO 3166-2 country code).
remitter.address
string
Remitter address.
remitter.purpose_code
string
The purpose for the payment, i.e. IR001. Use Instarem's data reference for purpose code.
remitter.source_of_income
string
Remitter source of income.
remitter.contact_number
string
Remitter contact number.
remitter.dob
string
Remitter Date of birth (YYYY-MM-DD).
remitter.city
string
Remitter city.
remitter.postcode
string
Remitter postcode.
remitter.state
string
Remitter state.
remitter.source_of_funds
string
Remitters source of funds.
remitter.place_of_birth
string
Remitter place of birth (2-letter ISO 3166-2 country code).
remitter.nationality
string
Remitter nationality (2-letter ISO 3166-2 country code).
remitter.occupation
string
Remitter occupation, i.e.EXECUTIVE. Use Instarem's data reference for remitter occupation.
payout_options.fx_hold_id
string
Id of the lock & hold fx rate.
payout_options.deduct_amount
number
Amount to be deducted from beneficiary.
additional_info.trade_order_id
string
additional_info.trade_time
string
additional_info.trade_currency
string
additional_info.trade_amount
number
additional_info.trade_name
string
additional_info.trade_count
integer
additional_info.goods_carrier
string
additional_info.service_detail
string
additional_info.service_time
string
additional_info.cash_pickup
string
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, BRANCH CODE for Brazil and Bangladesh, 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, BRANCH CODE for Brazil and Bangladesh, 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, BRANCH CODE for Brazil and Bangladesh, 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).
payout_method
OPTIONAL
string
Payout Method either CASH_PAYOUT or BANK or CARD or WALLET

Response (200)

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

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_given_name": true,
    "remitter_account_type": "Company",
    "remitter_bank_account_number": "10022206393",
    "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",
    "remitter_place_of_birth": "IN",
    "remitter_nationality": "IN",
    "remitter_occupation": "EXECUTIVE",
    "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_wallet_id": "64000000003",
    "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": "",
    "original_remitter_fi": "",
    "deduct_amount": 100,
    "beneficiary_card_number": "1234123412341234",
    "beneficiary_card_expiry_date": "2020-12",
    "remitter_source_of_funds": "",
    "additional_info": {
        "trade_order_id": "",
        "trade_time": "",
        "trade_currency": "",
        "trade_amount": "",
        "trade_name": "",
        "trade_count": "",
        "goods_carrier": "",
        "service_detail": "",
        "service_time": "",
        "cash_pickup": ""
    },
    "payout_method": "CASH_PAYOUT"
}
--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_given_name": true,
    "remitter_account_type": "Company",
    "remitter_bank_account_number": "10022206393",
    "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",
    "remitter_place_of_birth": "IN",
    "remitter_nationality": "IN",
    "remitter_occupation": "EXECUTIVE",
    "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_wallet_id": "64000000003",
    "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": "",
    "original_remitter_fi": "",
    "deduct_amount": 100,
    "beneficiary_card_number": "1234123412341234",
    "beneficiary_card_expiry_date": "2020-12",
    "remitter_source_of_funds": "",
    "additional_info": {
        "trade_order_id": "",
        "trade_time": "",
        "trade_currency": "",
        "trade_amount": "",
        "trade_name": "",
        "trade_count": "",
        "goods_carrier": "",
        "service_detail": "",
        "service_time": "",
        "cash_pickup": ""
    },
    "payout_method": "CASH_PAYOUT"
})
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_given_name"": true,
    ""remitter_account_type"": ""Company"",
    ""remitter_bank_account_number"": ""10022206393"",
    ""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"",
    ""remitter_place_of_birth"": ""IN"",
    ""remitter_nationality"": ""IN"",
    ""remitter_occupation"": ""EXECUTIVE"",
    ""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_wallet_id"": ""64000000003"",
    ""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"": """",
    ""original_remitter_fi"": """",
    ""deduct_amount"": 100,
    ""beneficiary_card_number"": ""1234123412341234"",
    ""beneficiary_card_expiry_date"": ""2020-12"",
    ""remitter_source_of_funds"": """",
    ""additional_info"": {
        ""trade_order_id"": """",
        ""trade_time"": """",
        ""trade_currency"": """",
        ""trade_amount"": """",
        ""trade_name"": """",
        ""trade_count"": """",
        ""goods_carrier"": """",
        ""service_detail"": """",
        ""service_time"": """",
        ""cash_pickup"": """"
    },
    ""payout_method"": ""CASH_PAYOUT""
}", 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
CONDITIONAL
string
Remitter name
remitter_given_name
OPTIONAL
boolean
Indicates whether the remitters name should allow initials
remitter_account_type
REQUIRED
string
Remitter account type either Individual or Company
remitter_bank_account_number
OPTIONAL
string
Remitter Bank Account Number
remitter_identification_type
CONDITIONAL
string
One of Registration Number, Registration ID, ACRA,Travel agent License number,Company Registration No,License No,ARNU,DRLC,NIDN,CCPT.
remitter_identification_number
CONDITIONAL
string
Remitter identification number is the document identifier i.e. IN1244654
remitter_country_code
CONDITIONAL
string
Remitter country code (2-letter ISO 3166-2 country code)
remitter_address
CONDITIONAL
string
Remitter address
remit_purpose_code
CONDITIONAL
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
remitter_place_of_birth
CONDITIONAL
string
Remitter place of birth (2-letter ISO 3166-2 country code)
remitter_nationality
CONDITIONAL
string
Remitter nationality (2-letter ISO 3166-2 country code)
remitter_occupation
OPTIONAL
string
Remitter occupation, i.e.EXECUTIVE. Use Instarem's data reference for remitter occupation.
beneficiary_name
REQUIRED
string
Beneficiary name
beneficiary_address
OPTIONAL
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_wallet_id
CONDITIONAL
string
Beneficiary wallet id
beneficiary_account_number
CONDITIONAL
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
CONDITIONAL
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, BRANCH CODE for Brazil and Bangladesh, 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, BRANCH CODE for Brazil and Bangladesh, 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, BRANCH CODE for Brazil and Bangladesh, 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)
original_remitter_fi
OPTIONAL
string
deduct_amount
OPTIONAL
number
Amount to be deducted from beneficiary
beneficiary_card_number
OPTIONAL
string
Card number with
beneficiary_card_expiry_date
OPTIONAL
string
Card expiration date in the format YYYY-MM
remitter_source_of_funds
OPTIONAL
string
Remitters source of funds
additional_info.trade_order_id
string
additional_info.trade_time
string
additional_info.trade_currency
string
additional_info.trade_amount
number
additional_info.trade_name
string
additional_info.trade_count
integer
additional_info.goods_carrier
string
additional_info.service_detail
string
additional_info.service_time
string
additional_info.cash_pickup
string
payout_method
OPTIONAL
string
Payout Method either CASH_PAYOUT or BANK or CARD or WALLET

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",
    "payment_reference_number": "43966790"
}

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
Transaction Reference Number
payment_id
string
Transaction id
status
string
Transaction Status
autobookfx_confirmation_id
string
Unique confirmation ID generated by Nium for successful AutoBook Fx.
sub_status
string
Transaction Sub Status
status_description
string
Transaction Status details
created_at
string
Date and time (UTC) of transaction.
updated_at
string
Date and time (UTC) of transaction.
payment_reference_number
string
Payment confirmation number from the bank

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",
    "payment_reference_number": "43966790"
}

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
Transaction Reference Number
payment_id
string
Transaction id
autobookfx_confirmation_id
string
Unique confirmation ID generated by Nium for successful AutoBook Fx.
status
string
Transaction Status
sub_status
string
Transaction Sub Status
status_description
string
Transaction Status details
created_at
string
Date and time (UTC) of transaction.
updated_at
string
Date and time (UTC) of transaction.
payment_reference_number
string
Payment confirmation number from the bank

Lock FX API

Get FX rate signature

Definition

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

Example Request

curl --request get \
--url "https://api-test.instarem.com:4803/api/v1/lockFx/getFxRate?source_currency=&destination_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/lockFx/getFxRate?source_currency=&destination_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/lockFx/getFxRate?source_currency=&destination_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

{
    "source_currency": "USD",
    "destination_currency": "USD",
    "base_fx_rate": 64.5132,
    "margin": 0.5,
    "fx_rate": 64.1874,
    "rate_signature": "No example yet.",
    "lock_expiry_at": ""
}

Get the currently available FX rate along with rate signature.

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
source_currency
REQUIRED
string
Source currency (3-letter ISO-4217 code).
destination_currency
REQUIRED
string
Destination currency (3-letter ISO-4217 code).

Response (200)

source_currency
string
Source currency (3-letter ISO-4217 code).
destination_currency
string
Destination currency (3-letter ISO-4217 code).
base_fx_rate
number
Returns real time FX provider rate
margin
number
Returns margin percent as specified in the agreement for the book FX pair.
fx_rate
number
Returns Instarem FX rate.
rate_signature
string
A string containing the encrypted rate details.
lock_expiry_at
string
Datetime of lock expiry.

Lock FX rate

Definition

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

Example Request

curl --request post \
--url "https://api-test.instarem.com:4803/api/v1/lockFx/lockFxRate" \
--data {
    "rate_signature": "TYY9KqN7PYLG+ynsN67bmwBsFLbtQU3Nud0T0PS1tnEU7SDuf5oTMzqEprHq53k+XZrTEHJVkaBaOH14agsDy/j1xxQbooimihQ6JCV0HhjOz80ioCbaJjQb8Mp1otH9mDiF1Fe29ibiaSAsrEoMByD9PzcWU1TMJlqxBxvnRK73S7SaP/DqP4Ck7dbOEY4a4+haUxZgJXMyQinztHM9jpEgsQ9JxX/cmKjNH03C/JclgBATP4Qz+FfBb1iAgFyE+ZEUlSgO4siDWjswB0XVKc6LeL1ykC9/JhX0WclHSbXVK1vWsMIWcx6NxYlxRiJy2N8E5Jac"
}
--header 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0OTgxMzQ4OTQsImRhdGEiOnsic3ViIjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWE1IiwiY2xpZW50IjoiNTk0MjNmMzZjZWEyMTQ2OTI2ODczOWExIn0sImlhdCI6MTQ5ODA0ODQ5NH0.pevwSDpk-JDNtVIpqFu_m0Xu1UnDVumrAYStcrxf8sM' \
--header 'content-type: application/json' \
var data = JSON.stringify({
    "rate_signature": "TYY9KqN7PYLG+ynsN67bmwBsFLbtQU3Nud0T0PS1tnEU7SDuf5oTMzqEprHq53k+XZrTEHJVkaBaOH14agsDy/j1xxQbooimihQ6JCV0HhjOz80ioCbaJjQb8Mp1otH9mDiF1Fe29ibiaSAsrEoMByD9PzcWU1TMJlqxBxvnRK73S7SaP/DqP4Ck7dbOEY4a4+haUxZgJXMyQinztHM9jpEgsQ9JxX/cmKjNH03C/JclgBATP4Qz+FfBb1iAgFyE+ZEUlSgO4siDWjswB0XVKc6LeL1ykC9/JhX0WclHSbXVK1vWsMIWcx6NxYlxRiJy2N8E5Jac"
})
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/lockFx/lockFxRate")
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/lockFx/lockFxRate");
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", @"{
    ""rate_signature"": ""TYY9KqN7PYLG+ynsN67bmwBsFLbtQU3Nud0T0PS1tnEU7SDuf5oTMzqEprHq53k+XZrTEHJVkaBaOH14agsDy/j1xxQbooimihQ6JCV0HhjOz80ioCbaJjQb8Mp1otH9mDiF1Fe29ibiaSAsrEoMByD9PzcWU1TMJlqxBxvnRK73S7SaP/DqP4Ck7dbOEY4a4+haUxZgJXMyQinztHM9jpEgsQ9JxX/cmKjNH03C/JclgBATP4Qz+FfBb1iAgFyE+ZEUlSgO4siDWjswB0XVKc6LeL1ykC9/JhX0WclHSbXVK1vWsMIWcx6NxYlxRiJy2N8E5Jac""
}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Example Response

{
    "fx_hold_id": "bf07da86-d6d5-47a4-b3c6-b77203b298e1",
    "source_currency": "USD",
    "destination_currency": "EUR",
    "fx_rate": 64.1874,
    "hold_expiry_at": ""
}

Send rate signature as instruction to lock & held.

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
rate_signature
REQUIRED
string
A string containing the encrypted rate details.

Response (200)

fx_hold_id
string
Hold ID
source_currency
string
Source currency (3-letter ISO-4217 code).
destination_currency
string
Destination currency (3-letter ISO-4217 code).
fx_rate
number
Instarem FX rate.
hold_expiry_at
string
Datetime of the hold expiry.

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 beneficiary bank
PAID Payment successfully paid
RETURNED Payment returned from beneficiary bank
CANCELLED Payment cancelled
ERROR Payment instruction erroroneous, appended by exact error response from beneficiary bank
USER_REJECTED The transaction was cancelled by the client
AWAITING_FUNDS Payment will be processed once funds are received by Nium

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

Occupation List

Standard Occupation list.

Sr No. Occupation
1 ADMINISTRATIVE
2 AGRICULTURE
3 AUTOMOTIVE
4 CONSULTING
5 CUSTOMER CARE/RETAIL
6 EDUCATION
7 ENGINEER
8 ENTERTAINMENT
9 ENTREPRENEUR
10 EXECUTIVE
11 EXPLICIT SERVICES
12 FINANCIAL SERVICES
13 HEALTHCARE
14 HUMAN RESOURCES
15 INFORMATION TECHNOLOGY (IT)
16 LEGAL
17 PERSONAL SERVICES
18 PHYSICAL WORKER
19 PUBLIC SERVANT
20 RELIGIOUS
21 RESTAURANT
22 RETIREE
23 SPORT
24 STUDENT
25 UNEMPLOYED/HOMEMAKER

Source of Income

Default value of remitter_source_of_income is "Business Relations".

Validation Sheet

General and Corridor Validations

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