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 in Payouts.

ℹ️ 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

JSON

{
"items": [
{
"toCurrency": "string",
"bankCountry": "string",
"beneficiaryCountry": "string",
"entityType": "BUSINESS/INDIVIDUAL"
}
]
}

Example

JSON

{
"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

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:

JSON

{
"items": [
{
"toCurrency": "AUD",
"bankCountry": "CY",
"beneficiaryCountry": "CY",
"entityType": "INDIVIDUAL"
}
]
}

would result in this:

JSON

{
"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. Select only one IBAN or account number.
`settlementCurrency`	No		Default value is `EUR`. If using any other currency, express the currency as ISO 4217. ℹ️ 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 a batch in the dashboard.
`callbackUrl`	No

Payments	Mandatory	Conditions	Value/format
`amount`	Yes		Dependent on merchant configuration.
`currencyCode`	Yes	Supported: `AUD`, `CAD`, `CHF`, `GBP`, HKD, HUF, ILS, NOK, NZD, PLN, `SGD`, 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.
`purposeOfPayment`	Conditional	Required for `HUF`, `ILS`.

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`.
`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

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. `GBP`: 8 digits account number or 22 alphanumeric character IBAN. `HKD`: 6-9 digits. `HUF`: 28 alphanumeric character IBAN. `ILS`: 23 alphanumeric character IBAN. `NOK`: 15 alphanumeric character IBAN. `NZD`: 9-10 digits. `PLN`: 28 alphanumeric character IBAN. `SGD`: 5-14 digits. `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`, `HUF`, `ILS`, `NOK`, `PLN`, `SGD`.	BIC format.
`bankBranchCode`	Conditional	Required for `AUD`, `CAD`, `GBP`, `HKD`, `NZD`, `SGD`, `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. `GBP`: this is a 6 digit sort code. `SGD`: this is a beneficiary bank routing code composed of 7 digits. `USD`: this is a 9-digit FedACH ABA routing code.
`accountType`	Conditional	Required for `USD`.	Can be either `checking` or `savings`.

Request body

JSON

{
"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"
}
}
}
]
}

cURL

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"
}
}
}
]

Rsponses

Success

Content-Type: application/json

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

JSON

{
"batch_id": "string"
}

Example

JSON

{
"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"
}'

Rsponses

Success

Content-Type: application/json

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

curl --location '{backend_url}/v2/remittance/batch/{batch_id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *****'

Response

JSON

{
"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

curl --location '{backend_url}/v2/remittance/batchdetails/{batch_id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ****'

Response

Successful

JSON

{

"batch_details": [

{

"reference_id": "my-ref-id1234",

"status": "PENDING",

"exchange_rate": "0.650123",

"transaction_id": "5d15e560-5bf8-4316-8f5b-134a1a05efa3"

}

]

}

Failed

JSON

{

"error_id": "ERR401A",

"message": "Unauthorized",

"code": 401

}

Batch statuses

Batch statuses are listed here.

Transaction statuses

Transaction statuses are listed here.

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:

JSON

{
"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:

JSON

{
"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"
}
]
}