Remittance

1 Introduction
2 Authentication
3 API batch request
- 3.1 Required transfer details
- 3.2 Submit batch
- 3.3 Get batch quote
- 3.4 Get batch state
- 3.5 Get batch details
4 Batch statuses
5 Transaction statuses
6 Callbacks

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

Payload table

Batch details	Mandatory	Comment

Batch details	Mandatory	Comment
`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
`callbackUrl`	No

Payments	Mandatory	Comment

Payments	Mandatory	Comment
`amount`	Yes	Depends on merchant config.
`currencyCode`	Yes	Expressed as ISO 4217. Currently supported: AUD, CAD, CHF, HKD, NZD, PLN. If, the `settlement_ currency` is CHF, then only CHF can be sent in the batch.
`paymentDetails`	No
`referenceId`	No	Used for merchant payment reference.

Beneficiary	Mandatory	Comment

Beneficiary	Mandatory	Comment
`firstName`	Yes
`lastName`	Yes
`type`	No	Can be either BUSINESS or INDIVIDUAL.
`businessName`	Conditional	Mandatory only if the entityType is BUSINESS.
`beneficiaryReference`	No

Address	Mandatory	Comment

Address	Mandatory	Comment
`line1`	Conditional	Required for AUD & CAD. Optional for CHF & NZD.
`city`	Conditional	Required for AUD & CAD. Optional for CHF & NZD.
`stateOrProvince`	Conditional	Required for AUD & CAD. Optional for CHF & NZD.
`zipOrPostal`	Conditional	Required for AUD & CAD. Optional for CHF & NZD.
`countryCode`	Yes	Expressed as ISO 3166-1 Alpha-2.

Bank account	Mandatory	Comment

Bank account	Mandatory	Comment
`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.
`bankName`	Yes
`address.countryCode`	Yes	Expressed as ISO 3166-1 Alpha-2.
`address.stateOrProvince`	Conditional	Required for AUD & CAD.
`bankCode`	Conditional	Required for CHF & PLN.
`bankBranchCode`	Conditional	Required for AUD, CAD, HKD & NZD. 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.

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",
                    "stateOrProvince": "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.

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

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

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

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

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

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

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",
                    "stateOrProvince": "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 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:

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