Payroll

1 Introduction
2 Authentication
- 2.1 JWT
- 2.2 Authorization header
- 2.3 Getting a token
- 2.4 Retrieval of JWT
3 API batch request
- 3.1 Submit batch
- 3.2 Get batch state
- 3.3 Get batch details
4 Batch statuses
5 Transaction statuses
6 Batch approval methods
7 Verification & confirmation
- 7.1 Verification of Payee
- 7.2 Confirmation of Payee
8 Callbacks
- 8.1 Receiving 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 the Masspay payroll functionality via API. In order to make use of this service, your ISX relationship manager needs to apply the relevant configuration settings.

Remittances (via API) in currencies other than 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

For authentication purposes, Masspay v.2 does not use encryption handling on the ISX side - everything is handled in the backend. A merchant just authenticates.

JWT

What is a JSON Web Token (JWT)?
JWT is a compact, URL-safe means of representing claims to be transferred between 2 parties. Essentially, it is a standardised way to securely transmit data between systems as a JSON object. JWTs are often used for authentication and authorization in web applications and APIs. Tokens are signed either using a private secret or a public/private key.

Authorization header

HTTP header: a bearer token must provided.

Getting a token

To get a token, sign into the Masspay dashboard:

Stage dashboard: https://masspay-stage.isxtech.com
Production dashboard: https://masspay.isxtech.com

On the right-hand menu, click on the Manage API keys option.

This section allows a user to generate and manage API keys.

The Manage API keys option is only available if the API option and associated configurations have been enabled for a merchant by an admin.
Only merchant users who have the Key Manager role assigned to them will be able to view the Manage API keys menu option in the Masspay dashboard. These users are able to create and/or view API keys for Masspay v.2.

An API key is a unique code used to authenticate and authorize access to an application programming interface (API). It acts as a secret token, enabling applications and/or users to identify themselves to the API provider and access specific resources or functionalities. It can be thought of as a digital key that unlocks access to a specific set of features or data within an application.

Select a merchant ID from the Merchant ID dropdown widget.

Any existing API key data will be retrieved & displayed.

Click on the Generate API key button to create an API key.

A pop-up window will advise the user that generating a new API key will replace the current key immediately and that the old key will cease functioning. The user is called to confirm whether they would like to proceed. Click on the Yes, proceed button.

An API key will be generated and displayed in the main body of the screen.

Use the Copy button to copy the generated key to memory.

The API key will only be visible while it is being viewed on the screen. Save it for future reference.

For security reasons, the API key is only visible whilst it is being viewed on the screen. It is advisable to save it for future reference.

When a user navigates away from the Manage API keys page, then the API key is masked, as the per the screenshot below.

If you require assistance, contact your ISX Relationship Manager.

Retrieval of JWT

Postman

Request Method: POST

The API is accessed from the Request URL.

Stage: https://auth-stage.isxtech.com/realms/corporate/protocol/openid-connect/token
Production: https://auth.isxtech.com/realms/corporate/protocol/openid-connect/token

Required Body (x-www-form-urlencoded)

Field name	Field value

Field name	Field value
`client_id`	{merchant_id}
`client_secret`	{client_secret}
`grant_type`	client_credentials

Example:

Field name	Field value

Field name	Field value
`client_id`	Test.merchant101.Payouts
`client_secret`	LC3SSRFC9XWH9DLE2N4TEA3GVC6FKMQH108QDV
`grant_type`	client_credentials

cURL

curl --location '{auth-url}/realms/corporate/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=Test.merchant101.Payouts' \
--data-urlencode 'client_secret=LC3SSRFC9XWH9DLE2N4TEA3GVC6FKMQH108QDV' \
--data-urlencode 'grant_type=client_credentials'

Response

Successful

{
    "access_token": "eyJhbGciOiJSUzI1NiIs...7j6ZfCKxZ7LHCNg",
    "expires_in": 1800,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

Failed

{
    "error": "invalid_client",
    "error_description": "Invalid client or Invalid client credentials"
}

API response field	Example	Comment

API response field	Example	Comment
`access_token`	eyJhbGciOiJSUzI1NiIs…	Retrieved by logging into the Masspay dashboard & it is added to the header.
`expires_in`	1800	Expressed is seconds & refers to how long it is active.
`refresh_expires_in`	0	Refresh expires in 0 seconds because no refresh token is present.
`token_type`	bearer	Type of token bearer & usually implies presenting a JWT for stateless auth.
`not_before_policy`	0
`scope`	email profile	This can contain default or optional scopes.

API batch request

The base stage URL is: https://masspay-api-stage.isxtech.com

The base production URL is: https://masspay-api.isxtech.com

Submit batch

Request method: Post

Content-Type: application/json

Endpoint for payroll: /v2/batch/payroll

This submits a payout batch. A batch will need to be approved to actually start execution.

Dataset details

Payload table

Batch details	Mandatory	Comment

Batch details	Mandatory	Comment
`merchant_id`	Yes
`sender_iban`	Conditional	This is one of the merchant’s IBANs. Select only one IBAN. This applies to EUR (& remittance) or GBP.
`sender_account_number`	Conditional	Valid account number. This applies to GBP only.
`description`	No
`callback_url`	No

In the case of GBP, either sender_iban or sender_account_number can be used.

Record name	Mandatory	Comment

Record name	Mandatory	Comment
`payment_details`	Yes
`beneficiary_name`	Yes	Accepts alphanumeric characters.
`beneficiary_reference`	Yes
`beneficiary_iban`	Conditional	Valid IBAN. This applies to EUR or GBP.
`beneficiary_sort_code`	Conditional	Valid sort code. This applies to GBP only.
`beneficiary_account_number`	Conditional	Valid account number. This applies to GBP only.
`payment_amount`	Yes	Depends on merchant config.
`currency`	Yes	Only EUR or GBP is accepted. Expressed as ISO 4217.
`reference_id`	Yes	Unique for each record.
`beneficiary_address`	Conditional	This applies to both EUR & GBP, but it is mandatory for GBP.
`beneficiary_city`	Conditional	This applies to both EUR & GBP, but it is mandatory for GBP.
`beneficiary_country`	Conditional	This applies to both EUR & GBP, but it is mandatory for GBP. Expressed as ISO 3166-1.

In the case of GBP, either beneficiary_iban or both beneficiary_sort_code and beneficiary_account_number can be used.

Payload samples

EUR

{
    "merchant_id": "Merchant101",
    "sender_iban": "CY21002001950000357001234565",
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_iban": "CY21002001950000357001234567",
            "payment_amount": "200",
            "currency": "EUR",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
        }
    ]
}

GBP (using IBANs)

{
    "merchant_id": "Merchant102",
    "sender_iban": "GB29NABK60161221945818"
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_iban": "GB29NWBK60161331926819",
            "payment_amount": "200",
            "currency": "GBP",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
            "beneficiary_address": "ClearKings Square N5 1AD",
            "beneficiary_city": "London",
            "beneficiary_country": "United Kingdom"
        }
    ]
}

GBP (using account numbers & sort codes)

{
    "merchant_id": "Merchant102",
    "sender_account_number": "31926819",
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_sort_code": "123456",
            "beneficiary_account_number": "98765432",
            "payment_amount": "200",
            "currency": "GBP",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
            "beneficiary_address": "ClearKings Square N5 1AD",
            "beneficiary_city": "London",
            "beneficiary_country": "GB"
        }
    ]
}

Remittances (via API) in currencies other than EUR or GBP are described here.

cURL: create an API request

EUR

curl --location 'https://masspay-api.isxtech.com/v2/batch/payroll' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *****' \
--data '{
    "merchant_id": "Merchant101",
    "sender_iban": "CY21002001950000357001234565",
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_iban": "CY21002001950000357001234567",
            "payment_amount": "200",
            "currency": "EUR",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
        }
    ]
}'

GBP (using IBANs)

curl --location 'https://masspay-api.isxtech.com/v2/batch/payroll' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *****' \
--data '{
    "merchant_id": "Merchant102",
    "sender_iban": "GB29NABK60161221945818"
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_iban": "GB29NWBK60161331926819",
            "payment_amount": "200",
            "currency": "GBP",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
            "beneficiary_address": "ClearKings Square N5 1AD",
            "beneficiary_city": "London",
            "beneficiary_country": "GB"
        }
    ]
}'

GBP (using account numbers & sort codes)

curl --location 'https://masspay-api.isxtech.com/v2/batch/payroll' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer *****' \
--data '{
    "merchant_id": "Merchant102",
    "sender_account_number": "31926819",
    "description": "API payout",
    "callback_url": "https://webhook.site/0c7db59d-73f8-4f5d-ac5a-f0c3bd98ec9a",
    "batch_records": [
        {
            "payment_details": "My Details",
            "beneficiary_name": "Joe Doe",
            "beneficiary_reference": "Payment 05/25",
            "beneficiary_sort_code": "123456",
            "beneficiary_account_number": "98765432",
            "payment_amount": "200",
            "currency": "GBP",
            "reference_id": "9de38ba8-8a1b-4015-b307-7aeea4042507"
            "beneficiary_address": "ClearKings Square N5 1AD",
            "beneficiary_city": "London",
            "beneficiary_country": "GB"
        }
    ]
}'

Response

{
    "batch_id": "d6729934-6df9-4d3e-9fc8-4112847680f3",
    "total_amount": 11.11
}

Get batch state

Request method: Get

Content-Type: application/json

Endpoint: /v2/batch/{batchUid}

Get information for a previously submitted batch.

cURL: create an API request

curl --location 'https://masspay-api.isxtech.com/v2/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/batchdetails/{batchUid}

Get statuses of all transactions associated with a previously submitted batch.

cURL: create an API request

curl --location 'https://masspay-api.isxtech.com/v2/batchdetails/{batch_id}' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ****'

Response

Successful

{
    "batch_details": [
        {
          "reference_id": "19df924f-2c07-47e9-9028-3d31d21e6f52",
          "status": "COP_PENDING_APPROVAL",
          "transaction_id": "51175033-9aba-4822-a11f-f9bdb6b2f92b",
          "verification_status": "Confirmation of Payee check failed"
        }
    ]
}

Failed

{
    "error_id": "ERR401A",
    "message": "Unauthorized",
    "code": 401
}

Batch statuses

Batch status	Final	Comment

Batch status	Final	Comment
`PENDING`	No	Submitted batch request received. Batch is being loaded & validated. User review may be required.
`PENDING_APPROVAL`	No	User has confirmed to proceed with a batch submission but there are conditions in place to require approval by someone else.
`CANCELED`	Yes	User has decided not to proceed with a previously submitted batch.
`FAILED`	Yes	Batch encountered a fatal error, or it never received confirmation for proceeding or cancelling.
`PROCESSING`	No	Transactions are being processed.
`REPROCESSING`	No	Transactions have been executed using instant processing. However, even if a transaction fails, the system will use alternative methods.
`COMPLETE`	Yes	All transactions in a batch have been finalised.

Transaction statuses

Transaction status	Final	Comment

Transaction status	Final	Comment
`PENDING`	No	Transaction execution is initiated. But, before transferring any funds pertaining to the transaction, further validations take place.
`VOP_PENDING_APPROVAL`	No	Transaction execution is initiated. But, before transferring any funds of the transaction, VoP approval is required. Refer to this link for more info.
`COP_PENDING_APPROVAL`	No	Transaction execution is initiated. But, before transferring any funds of the transaction, CoP approval is required. Refer to this link for more info.
`PROCESSING`	No	Transaction execution is initiated. VoP/CoP approval has been granted.
`CANCELED`	Yes	Upon review, user decided not to proceed with transaction execution or the transaction was canceled on VoP/CoP review.
`FAILED`	Yes	A transaction has encountered a fatal error, for example, it failed validation or one of the dependent systems is experiencing issues.
`REJECTED`	Yes	Transaction rejected because it was rejected by an external system, for example, rejected because of compliance issues.
`SUCCEEDED`	Yes	A transaction has been processed successfully & has been settled.

Batch approval methods

There are 3 options for batch approval:

Manual approval (a user must log into the Masspay dashboard & manually approve transactions/batches).

Auto-approval (you can confirm to us the number of transactions which will trigger the ‘auto-approval’ feature).

End of Day auto-approval (if the ‘auto-approval’ number of transactions is not reached by the daily cut-off time (i.e., 22:00 UTC time, which is 00:00 CY time), the transaction/batches will be processed).

If you wish to set or update an approval method, please contact your ISX Relationship Manager.

Verification & confirmation

Verification of Payee

What is Verification of Payee (VoP)?
VoP refers to a security process that checks if a name on a bank account matches an account number provided for a payment. It prevents fraud and misdirected payments by verifying payee details against the recipient bank's records before a transaction is completed. This is an EU-specific service.

Approve VoP

Request body

Request method: Post

Content-Type: application/json

Endpoint: /v2/vop/approve/{batchUid}

Example value

Requirements	Mandatory	Comment

Requirements	Mandatory	Comment
`transactionUid / transaction_id`	Yes	A transaction ID (or a list of transaction IDs) in VOP_PENDING_APPROVAL status must be provided.

[
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
]

Reject VoP

Request body

Request method: Post

Content-Type: application/json

Endpoint: /v2/vop/reject/{batchUid}

Example value

Requirements	Mandatory	Comment

Requirements	Mandatory	Comment
`transactionUid / transaction_id`	Yes	A transaction ID (or a list of transaction IDs) in VOP_PENDING_APPROVAL status must be provided.

[
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
]

Confirmation of Payee

What is Confirmation of Payee (CoP)?
CoP is an account name-checking service that is designed to help reduce misdirected payments and provide greater assurance that payments are being sent, and collected from, the intended account holder for UK domestic payments (applies only to FPS payments). This is a UK-specific service.

Approve CoP

Request body

Request method: Post

Content-Type: application/json

Endpoint: /v2/cop/approve/{batchUid}

Example value

Requirements	Mandatory	Comment

Requirements	Mandatory	Comment
`transactionUid / transaction_id`	Yes	A transaction_id (or a list of transaction_ids) in COP_PENDING_APPROVAL status must be provided.

[
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
]

Reject CoP

Request body

Request method: Post

Content-Type: application/json

Endpoint: /v2/cop/reject/{batchUid}

Example value

Requirements	Mandatory	Comment

Requirements	Mandatory	Comment
`transactionUid / transaction_id`	Yes	A transaction ID (or a list of transaction IDs) in COP_PENDING_APPROVAL status must be provided.

[
  "3fa85f64-5717-4562-b3fc-2c963f66afa6"
]

Callbacks

Note that this is optional.

Callbacks refers to the channel that is used for notification purposes.

This happens on:

Batch status changed (incl. finalisation).