Masspay: Remittance
Introduction
The Masspay payout instruction functionality is implemented to allow a user to perform multiple payout requests with a single click. Efficiency and productivity are the main drivers of this feature as it allows a user to perform up to 1000 payouts in a single operation.
The focus of this guide is remittances, via API, in currencies other than EUR or GBP. In order to make use of the remittance service, your ISX relationship manager needs to apply the relevant configuration settings.
Remittances (via API) in EUR or GBP are described here.
What is an Application Programming Interface (API)?
An API is a way for two or more apps to communicate with each other. An API is a type of software interface offering a service to other pieces of software. APIs work by sharing data between apps, systems, and devices. This happens through a request and response cycle. A user initiates a request for data by interacting with an app. The request is sent to an API, which retrieves the data and then returns it to a user. A document that describes how to build or use such a connection or interface is called an API specification.
This API documentation makes extensive use of country codes expressed as ISO 3166-1 Alpha-2 and currency codes expressed as ISO 4217. The links provide relevant reference material.
Authentication
The authentication process is described here.
If you require assistance, contact your Relationship Manager.
API batch request
The base stage URL is: https://masspay-api-stage.isxtech.com
The base production URL is: https://masspay-api.isxtech.com
Required transfer details
Request method: Post
Content-Type: application/json
Endpoint: /v2/remittance/required-transfer-details
Get the transfer required attributes for provider and currency.
Request body
{
"items": [
{
"toCurrency": "string",
"bankCountry": "string",
"beneficiaryCountry": "string",
"entityType": "BUSINESS/INDIVIDUAL"
}
]
}
Example
{
"items": [
{
"to_currency": "CAD",
"bankCountry": "CA",
"beneficiaryCountry": "CA",
"entityType": "INDIVIDUAL"
}
]
}
cURL
curl -X 'POST' \
'https://masspay-api-stage.isxtech.com/v2/remittance/required-transfer-details' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"items": [
{
"to_currency": "CAD",
"bankCountry": "CA",
"beneficiaryCountry": "CA",
"entity_type": "INDIVIDUAL"
}
]
}'
Responses
Success
Content-Type: application/json
{
"items": [
{
"toCurrency": "CAD",
"bankCountry": "CA",
"beneficiaryCountry": "CA",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.address.stateOrProvince",
"description": "Enter the beneficiary bank's state or province."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 9-digit transit code. 4 digit bank number followed by 5 digit branch number."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.city",
"description": "Enter the beneficiary's city."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.address.line1",
"description": "Enter the full street address. PO Boxes and other invalid entries not allowed. Max length is 70 characters."
},
{
"attributeName": "beneficiary.address.stateOrProvince",
"description": "Enter the beneficiary's state or province."
},
{
"attributeName": "beneficiary.address.zipOrPostal",
"description": "Enter the beneficiary's postal code."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
Error
This unsupported request:
{
"items": [
{
"toCurrency": "AUD",
"bankCountry": "CY",
"beneficiaryCountry": "CY",
"entityType": "INDIVIDUAL"
}
]
}
would result in this:
{
"error_id": "ERR400RPIV",
"message": "Only ACH payment method is supported for remittance: [toCurrency: AUD, bankCountry: CY]",
"code": 400
}
Submit batch
Request method: Post
Content-Type: application/json
Endpoint: /v2/remittance/batch/submit
Endpoint for payroll: /v2/remittance/batch/payroll/submit
Submit the remittance batch.
Dataset details
SWIFT X character set
The SWIFT X character set is an alphanumeric standard used in financial messaging. It permits a specific set of 68 uppercase and lowercase letters, numbers & basic punctuation marks. Allowed characters:
uppercase & lowercase letters: Aa-Zz, numeric digits: 0-9, special characters & punctuation: /, -, ?, :, (, ), ., ,, ', +, {space}
Payload table
|
Batch details |
Mandatory |
Remark |
Value/format |
|
merchantId |
Yes |
|
|
|
senderIban |
Yes |
This is one of the merchant’s IBANs or account numbers. |
|
|
settlementCurrency |
No |
|
Default value is EUR. If, for example, CHF is sent to CHF, then the selected currency goes to its own batch & FX is not involved. |
|
description |
No |
Description of the batch in the dashboard. |
|
|
callbackUrl |
No |
|
|
|
Payments |
Mandatory |
Conditions |
Value/format |
|
amount |
Yes |
|
Dependent on merchant configuration. |
|
currencyCode |
Yes |
Supported: AUD, CAD, CHF, HKD, NZD, PLN, USD. If, the settlementCurrency is CHF, then only CHF can be sent in the batch. |
Expressed as ISO 4217. |
|
paymentDetails |
No |
|
Characters allowed: SWIFT X character set. |
|
referenceId |
No |
Used for merchant payment reference. |
Characters allowed: Aa-Zz, -, [, ], ?, :, -, +, ., ', /, \, (, ), _, and up to 36 characters. |
|
Beneficiary |
Mandatory |
Conditions |
Value/format |
|
firstName |
Conditional |
Required only if type is INDIVIDUAL. |
Characters allowed: Aa-Zz, -, ', {space} |
|
middleName |
No |
|
Characters allowed: Aa-Zz, -, ', {space} |
|
lastName |
Yes |
|
Characters allowed: Aa-Zz, -, ', {space} |
|
type |
No |
|
Can be either BUSINESS or INDIVIDUAL. |
|
gender |
Conditional |
Required only if type is INDIVIDUAL, required for AUD & dependent on merchant configuration. |
Characters allowed: SWIFT X character set. |
|
dateOfBirth |
Conditional |
Required only if type is INDIVIDUAL, required for AUD & dependent on merchant configuration. |
Format: YYYY-MM-DD. |
|
|
Conditional |
Required only if type is INDIVIDUAL, required for AUD & dependent on merchant configuration. |
|
|
businessName |
Conditional |
Required only if type is BUSINESS. |
Characters allowed: SWIFT X character set. |
|
beneficiaryReference |
No |
|
Characters allowed: Aa-Zz, -, [, ], ?, :, -, +, ., ', /, \, (, ), _, {space}, and up to 75 characters. |
|
Address |
Mandatory |
Conditions |
Value/format |
|
line1 |
Conditional |
Required for AUD, CAD & USD. |
Characters allowed: SWIFT X character set. |
|
city |
Conditional |
Required for AUD, CAD & USD. |
Characters allowed: SWIFT X character set. |
|
stateOrProvince stateOrProv |
Conditional Conditional |
Required for CAD & USD. Required for AUD. |
Characters allowed: SWIFT X character set. |
|
zipOrPostal |
Conditional |
Required for AUD, CAD & USD. |
Characters allowed: SWIFT X character set. |
|
countryCode |
Yes |
|
Expressed as ISO 3166-1 Alpha-2. |
|
Bank account |
Mandatory |
Conditions |
Value/format |
|
accountNumber |
Yes |
|
AUD: 6-10 digits. CAD: 7-12 digits. CHF: 21 alphanumeric character IBAN. IBAN format: CHkk BBBB BCCC CCCC CCCC C, where CH = Country Code, kk = Check Digits, B = Bank Code, and C = Account No. HKD: 6-9 digits. NZD: 9-10 digits. PLN: 28 alphanumeric character IBAN. IBAN format: PLkk BBBB BBBB CCCC CCCCCCCCCCCC, where PL = Country Code, kk = Check Digits, B = Bank Code, and C = Account No. USD: 5-17 digits. |
|
bankName |
Yes |
|
Characters allowed: SWIFT X character set. |
|
address.countryCode |
Yes |
|
Expressed as ISO 3166-1 Alpha-2. |
|
address.stateOrProvince |
Conditional |
Required for CAD. |
Characters allowed: SWIFT X character set. |
|
bankCode |
Conditional |
Required for CHF & PLN. |
BIC format. |
|
bankBranchCode |
Conditional |
Required for AUD, CAD, HKD, NZD & USD. |
AUD: this is called the BSB. A Bank State Branch (BSB) number is a 6-digit identification number that indicates the state and branch at which a bank account was opened. CAD: this is the branch transit code. A 12 digit account number may comprise of the last 5 digits of the transit code (known as branch identifier) followed by the 7 digit account number. HKD: composed of 6 digits. USD: this is a 9-digit FedACH ABA routing code. |
|
accountType |
Conditional |
Required for USD. |
Can be either checking or savings. |
Request body
{
"merchantId": "Jane.Merchant",
"senderIban": "CY12702202009743735424",
"description": "API Remittance",
"callbackUrl": "...",
"payments": [
{
"amount": 10000,
"currencyCode": "AUD",
"paymentDetails": "Payment 10/25",
"referenceId": "my-ref-id1234",
"beneficiary": {
"firstName": "Joe",
"lastName": "Doe",
"type": "INDIVIDUAL",
"address": {
"line1": "123 George Street",
"city": "Sydney",
"stateOrProv": "NSW",
"zipOrPostal": "2000",
"countryCode": "AU"
}
},
"bankAccount": {
"accountNumber": "12345678",
"bankName": "AU Bank Pty Ltd",
"bankBranchCode": "123456",
"address": {
"countryCode": "AU"
}
}
}
]
}
Required fields based on currencies
Click the arrow toggle button to expand each currency.
Australian Dollar [AUD]
{
"items": [
{
"toCurrency": "AUD",
"bankCountry": "AU",
"beneficiaryCountry": "AU",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 6-digit Australian BSB Code."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.city",
"description": "Enter the beneficiary's city. Character limit is 35 characters."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.address.line1",
"description": "Enter a valid street address. Character limit is 70. No PO Boxes."
},
{
"attributeName": "beneficiary.address.stateOrProv",
"description": "Enter the beneficiary's state or province."
},
{
"attributeName": "beneficiary.address.zipOrPostal",
"description": "Enter the beneficiary's 4-digit postal code."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
Canadian Dollar [CAD]
{
"items": [
{
"toCurrency": "CAD",
"bankCountry": "CA",
"beneficiaryCountry": "CA",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.address.stateOrProvince",
"description": "Enter the beneficiary bank's state or province."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 9-digit transit code. 4 digit bank number followed by 5 digit branch number."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.city",
"description": "Enter the beneficiary's city."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.address.line1",
"description": "Enter the full street address. PO Boxes and other invalid entries not allowed. Max length is 70 characters."
},
{
"attributeName": "beneficiary.address.stateOrProvince",
"description": "Enter the beneficiary's state or province."
},
{
"attributeName": "beneficiary.address.zipOrPostal",
"description": "Enter the beneficiary's postal code."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
Swiss Franc [CHF]
{
"items": [
{
"toCurrency": "CHF",
"bankCountry": "CH",
"beneficiaryCountry": "CH",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankCode",
"description": "Enter a valid 8 or 11 character SWIFT code."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
Hong Kong Dollar [HKD]
{
"items": [
{
"toCurrency": "HKD",
"bankCountry": "HK",
"beneficiaryCountry": "HK",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 6-digit routing code."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
New Zealand Dollar [NZD]
{
"items": [
{
"toCurrency": "NZD",
"bankCountry": "NZ",
"beneficiaryCountry": "NZ",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 6-digit routing code."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
Poland Złoty [PLN]
{
"items": [
{
"toCurrency": "PLN",
"bankCountry": "PL",
"beneficiaryCountry": "PL",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "bankAccount.bankCode",
"description": "Enter a valid 8 or 11 character SWIFT code."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
United States Dollar [USD]
{
"items": [
{
"toCurrency": "USD",
"bankCountry": "US",
"beneficiaryCountry": "US",
"entityType": "INDIVIDUAL",
"beneficiaryAttributes": [
{
"attributeName": "bankAccount.accountNumber",
"description": "Enter the beneficiary's bank account number."
},
{
"attributeName": "bankAccount.accountType",
"description": "Select the type of bank account."
},
{
"attributeName": "bankAccount.address.countryCode",
"description": "Select the country where the beneficiary's bank branch is located."
},
{
"attributeName": "bankAccount.bankBranchCode",
"description": "Enter a valid 9-digit FedACH ABA routing code."
},
{
"attributeName": "bankAccount.bankName",
"description": "Enter the name of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.city",
"description": "Enter the city of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.countryCode",
"description": "Select the country of the beneficiary."
},
{
"attributeName": "beneficiary.address.line1",
"description": "Enter the full street address of the beneficiary bank."
},
{
"attributeName": "beneficiary.address.stateOrProvince",
"description": "Enter the beneficiary's state or province."
},
{
"attributeName": "beneficiary.address.zipOrPostal",
"description": "Enter the beneficiary's zip code, formatted as either NNNNN or NNNNN-NNNN."
},
{
"attributeName": "beneficiary.firstName",
"description": "Enter the beneficiary's first name."
},
{
"attributeName": "beneficiary.lastName",
"description": "Enter the beneficiary's last name."
},
{
"attributeName": "payments.currencyCode",
"description": "Select the currency to pay the beneficiary."
}
]
}
]
}
cURL
curl -X 'POST' \
'https://masspay-api.isxtech.com/v2/remittance/batch/submit' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"merchantId": "Jane.Merchant",
"senderIban": "CY12702202009743735424",
"description": "API Remittance",
"callbackUrl": "...",
"payments": [
{
"amount": 10000,
"currencyCode": "AUD",
"paymentDetails": "Payment 10/25",
"referenceId": "my-ref-id1234",
"beneficiary": {
"firstName": "Joe",
"lastName": "Doe",
"type": "INDIVIDUAL",
"address": {
"line1": "123 George Street",
"city": "Sydney",
"stateOrProv": "NSW",
"zipOrPostal": "2000",
"countryCode": "AU"
}
},
"bankAccount": {
"accountNumber": "12345678",
"bankName": "AU Bank Pty Ltd",
"bankBranchCode": "123456",
"address": {
"countryCode": "AU"
}
}
}
]
}'
Responses
Success
Content-Type: application/json
{
"batch_id": "c123d123-ec80-441f-8cbf-29de5dc0c8c9"
}
Get batch quote
Request method: Post
Content-Type: application/json
Endpoint: /v2/remittance/batch/quote
Get batch quote.
Request body
{
"batch_id": "string"
}
Example
{
"batch_id": "c123d123-ec80-441f-8cbf-29de5dc0c8c9"
}
cURL
curl -X 'POST' \
'https://masspay-api-stage.isxtech.com/v2/remittance/batch/quote' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"batch_id": "c123d123-ec80-441f-8cbf-29de5dc0c8c9"
}'
Responses
Success
Content-Type: application/json
{
"quote_pairs": [
{
"to_currency": "AUD",
"rate": "0.5628"
},
{
"to_currency": "CAD",
"rate": "0.617551"
},
{
"to_currency": "CHF",
"rate": "1.077122"
},
{
"to_currency": "HKD",
"rate": "0.111828"
},
{
"to_currency": "NZD",
"rate": "0.487948"
}
],
"total_amount": 100.00,
"total_fees": 2.23,
"active_number_of_payments": 5
}
Get batch state
Request method: Get
Content-Type: application/json
Endpoint: /v2/remittance/batch/{batchUid}
Get information for a previously submitted batch.
cURL: create an API request
curl --location '{backend_url}/v2/remittance/batch/{batch_id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *****'
Response
{
"state": "PROCESSING"
}
Get batch details
Request method: Get
Content-Type: application/json
Endpoint: /v2/remittance/batchdetails/{batchUid}
Get statuses of all transactions associated with a previously submitted batch.
cURL: create an API request
curl --location '{backend_url}/v2/remittance/batchdetails/{batch_id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ****'
Response
Successful
{
"batch_details": [
{
"reference_id": "my-ref-id1234",
"status": "PENDING",
"exchange_rate": "0.650123",
"transaction_id": "5d15e560-5bf8-4316-8f5b-134a1a05efa3"
}
]
}
Failed
{
"error_id": "ERR401A",
"message": "Unauthorized",
"code": 401
}
Batch statuses
Batch statuses are listed in Payouts.
Transaction statuses
Transaction statuses are listed in Payouts.
Callbacks
Callbacks refers to the channel that is used for notification purposes.
This happens on:
- Batch status changed (incl. finalisation).
- End of day for non-finalised batches of the last 5 days.
Notification sample for a remittance batch:
{
"batch_id": "9f5a42f8-09d7-4911-99f1-f2ffe589d275",
"state": "PENDING_APPROVAL",
"batch_details": [
{
"reference_id": "my-ref-id1",
"status": "PENDING",
"exchange_rate": "0.5619",
"transaction_id": "a0edc971-eec8-4fc0-b4ce-3444c4c53731"
},
{
"reference_id": "my-ref-id2",
"status": "PENDING",
"exchange_rate": "0.619042",
"transaction_id": "300bed70-0eb8-45e4-847f-2b4fb03d63dd"
},
{
"reference_id": "my-ref-id3",
"status": "PENDING",
"exchange_rate": "0.488234",
"transaction_id": "7ff1f5dd-e1c3-4837-a80f-5818d499fdb1"
},
{
"reference_id": "my-ref-id4",
"status": "PENDING",
"exchange_rate": "1.083541",
"transaction_id": "9f898b47-6b91-4b95-b29f-39fbf3056357"
}
]
}
Notification sample for a remittance batch with the same settlement currency:
{
"batch_id": "bad3bb48-8fbc-470b-9bc5-204992f8f190",
"state": "PROCESSING",
"batch_details": [
{
"reference_id": "my-ref-id5",
"status": "PENDING",
"exchange_rate": "N/A",
"transaction_id": "8f64308f-763d-4296-9014-f674e9427a25"
}
]
}