TransferMate Payments API Documentation

Getting Started

The Payments API is a REST API that accepts standard HTTP commands (GET and POST), returns JSON-encoded responses, and uses standard HTTP response codes. The Payments service includes pre-defined domain-specific endpoints, such as banks and beneficiaries.

To use the Payments API, you must be authenticated by verifying your identity. See Authentication for more information.

To help you use the Payments API, we provide several use cases to get started and reference information that describes each API request in a consistent manner. These API request sections include:

General HTTP Request Information
Request Body Payload Example
Example Response
Error Response

In the Payments API, IDs are of type Varchar. This is important because IDs are often represented as numerical types.

Our mission is to provide customers with everything they need to use the Payments API effectively. If you have issues while using the API, discover shortcomings, or have suggestions for improvements, please do not hesitate to contact us.

Authentication

Information security is critical, especially in web-based applications. The Payments service uses the Oauth2 framework for advanced authentication. For details of the OAuth2 framework, see the OAuth2 website.

When you log in using your username and password, the Payments service generates an access token. You can use this token for verification in your API requests.

You include the token in the Authorization: Bearer… header for all interactions with the Payments API.

Authentication codes grant you special privileges to access and use the Payments API. Keep these codes safe and avoid sharing them in insecure environments.

Each client entity is considered unique and switching between entities will require a new /connect call and token. Partners are required to build any entity management functionality within their own system. This will also require a unique webhook URL per entity if webhooks are being utilized.

Authentication enables you to:

Connect to the Payments Service
When you connect (log in) to the Payments service, you receive an access token that you provide for verification in subsequent API requests. The access token is valid for a short time.

Disconnect from the Payments Service
When you disconnect from (log out of) the Payments service, you can no longer use API calls and the service revokes the access token granted to you when you logged in.

Retrieve Historical Connection Information
You can get information about past connections. You can specify the period from which you want to retrieve connection information and there are options for sorting the retrieved information.

POST Connect to the Payments Service

You connect to the Payments service to log in. You do this by sending an HTTP POST request with the required account login information to the /connect endpoint.

Endpoint: /connect

Request Body Payload Example

The request body includes the following parameters:

INPUT PARAMETER	DESCRIPTION	TYPE	SIZE	MANDTORY	DEFAULT VALUE
`username`	The name a user provided when creating an account.	Varchar	32	Yes	—
`password`	The password a user provided when creating an account.	Varchar	32	Yes	—

Example Request

{
"username": "ba11b15fd7d94b0abfd732a286f534cf",
"password": "C=EapNMbw+TL5jCs5P&HJtq4u=wB2^!?"
}

Response Body Payload Example

If the connect request is successful, the service returns an access token.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`token`	An access token to use as verification in service requests.	Varchar

Example Success Response

{
"token": "6e12dac6d8e172f304b5edb94c4312d3ae307dc71f9a49e0f89baa4cecd52623-58406"
}

Example Error Responses

If the connect request is not successful, the service responds with an error code, rejects the request, and denies access to the Payments service. Some example error responses are provided.

In the case of too many login errors, the account is locked, and you must contact an administrator to unlock it.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - Incorrect Credentials

{
"stat": "incorrect credentials. caution: multiple incorrect attempts"
}

Error Code 403 - Missing or Malformed Endpoint

{
"stat": "missing or malformed endpoint"
}

Error Code 403 - Too Many Incorrect Attempts

{
"stat": "too many incorrect attempts. account is locked"
}

GET Disconnect from the Payments Service

You disconnect from the Payments service to log out. You do this by sending an HTTP GET request to the /disconnect endpoint. The access token that you used for API request verification while connected becomes invalid.

Endpoint: /disconnect

Response Body Payload Example

If the disconnect request is successful, the service responds with a logged out message.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the outcome of the request.	Varchar

Example Success Response

{
"stat": "logged out"
}

Example Error Responses

If the disconnect request is not successful, the service responds with an error code, rejects the request and does not perform the log out operation. The relevant error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - Session Not Available or Incorrect SSO Token

{
"stat": "this session is not available, or the sso token is incorrect"
}

POST Retrieve Historical Connection Information

You can retrieve details of historical Payments service connections within a specific time period. You do this by sending an HTTP POST request to the /connection_history endpoint. The response JSON structure contains details of each connection. The details include the user ID, the date and time, the IP address, the country, and the local date and time.

Endpoint: /connection_history

Request Body Payload Example

The request body includes the following parameters:

INPUT PARAMETER	DESCRIPTION	TYPE	SIZE	MANDTORY	DEFAULT VALUE
`date_from`	Specifies the start date of the period for which you want to retrieve connection information. The format must be dd-mm-yyyy.	date	—	Yes	—
`date_to`	Specifies the end date of the period for which you want to retrieve connection information. The parameter is optional. If unspecified, the end date is the current date. The format must be dd-mm-yyyy.	date	—	No	—
`page_no`	A page navigation value for pagination and retrieving a specific page in the grid.	Varchar	3	Yes	—

Example Request

{
"date_from": "02-02-2022",
"date_to": "02-02-2022",
"page_no": "1"
}

Response Body Payload Example

If the request is successful, a list of connections are returned.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`token`	A list of error codes. This is an array of errors that could be caused by one or more parameters failing validation.	list
`rows`	A list of connections.	list
`uid`	The ID of the user that connected.	Varchar
`date`	The date and time of the connection.	Varchar
`ip`	The IP address from which the connection was made.	Varchar
`country`	The country from which the connection was made.	Varchar
`local`	The date and time of the connection in UTC format in the local connection timezone.	Varchar
`message`	One or more messages associated with the request.	list

Example Success Response

{
"errors": [],
"rows": [
{
"uid": "0",
"date": "Feb 02, 2022 16:47:32",
"ip": "193.105.145.29",
"country": "Ireland",
"local": "Feb 02, 2022 16:47:32"
},
{
"uid": "1",
"date": "Feb 02, 2022 16:47:32",
"ip": "193.105.145.29",
"country": "Ireland",
"local": "Feb 02, 2022 16:47:32"
}
{
"uid": "2",
"date": "Feb 02, 2022 16:47:32",
"ip": "193.105.145.29",
"country": "Ireland",
"local": "Feb 02, 2022 16:47:32"
}
],
"message": []
}

Example Error Responses

If the request is not successful, the service responds with an error code, rejects the request, and does not provide the historical connection information. The relevant error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - Invalid Token

{
"stat": "invalid token"
}

POST Change password for the Payment Service

First, you connect to the payments service to log in. You do this by sending an HTTP POST request with the required account login information to the /connect endpoint. Right after connecting to the payment service, you can change your password by sending an HTTP POST request with the required information to the /v2/change_password endpoint.

Endpoint: /v2/change_password

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`password`	The password a user provided when creating an account.	Varchar	32	Yes	—
`new_password`	The new password that will be used to connect to the payment service.	Varchar	32	Yes	—
`confirm_password`	Repeating the new password that will be used to connect to the payment service.	Varchar	32	Yes	—

Example Request

{
"password":"ba11b15fd7d94b0abfd732a286f534cf",
"new_password":"u%f337486&WH%F%ec@555zc",
"confirm_password":"u%f337486&WH%F%ec@555zc"
}

Response Body Payload Example

If the change password request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	Status of the request.	Varchar
`messages`	List of messages associated with the response.	List
`success`	Any messages associated with this request.	Varchar
`web_login_id`	The ID of the user that connected.	Integer

Example Success Response

{
"is_successful": true,
"messages": {
"success": "Action performed successfully."
},
"web_login_id": 1234
}

Example Error Responses

FIELD	DESCRIPTION	TYPE
`is_successful`	A status message that describes the error encountered.	Varchar
`messages`	List of messages associated with the response.	Varchar
`new_password`	A message that describes the error encountered.	Varchar

{
"is_successful": false,
"messages": {
"new_password": "New password has to be different from the old one!"
}
}

{
"is_successful": false,
"messages": {
"new_password": "Password should contain at least one uppercase letter, one lowercase letter, one digit and one special character (~!@#$%^&*{})"
}
}

Treasury Account Management

The TransferMate Payments API allows an authenticated user to manage personal bank account information. As a regulated entity and to ensure we follow anti-money laundering best-practice, TransferMate must collect the details of the funding bank account in every transaction. Before functionality of the account is enabled,a bank account needs to be created prior to any action.

Using our Payments API, an authenticated user can:

Add a New Bank Account
You add a new bank account by providing the account details. If the account is created successfully, the service assigns and returns an account ID. When you add a new bank account, the service performs rigorous validation and may report a variety of errors.

View Existing Bank Account Details
You can retrieve the details of existing bank accounts. There is an option to retrieve all active or inactive accounts and you can choose to paginate the results with a certain number of bank accounts presented per page.

Edit Existing Bank Account Details
You can edit a bank account name or deactivate an account. You cannot recover or re-use an inactive account. Inactive accounts are removed from all live lists. To view inactive accounts, see View Existing Bank Account Details.

Verify Existing Bank Account Details
You can verify the details of an existing bank account. The service uses an internal verifier to perform checks on the provided bank account details to ensure conformance to standards.
To get meaningful results, you must provide at least an International Bank Account Number (IBAN), a Bank Information Code (BIC), or other pertinent bank identification information, for example, a bank number or sort code.
The verifier returns codes and messages that explain the results of the verification. See Bank Verifier Codes and Messages for more information.

The information maintained for a bank account includes the following:

Account ID

Account Name

Account Description

Bank Name

Country

Currency of Account

Payment Type

Direct Debit Capability

Wire Transfer Capability

Bank Details (such as the IBAN and SWIFT/BIC codes)

Active Indicator (indicates if the bank account is active or inactive)

Editable Indicator (indicates if the bank details are editable or not)

POST Add a New Bank Account

You add a new bank account by sending an HTTP POST request with the required account information to the /add_bank endpoint.

In earlier versions of this API, you could add a new bank account with an HTTP POST request. The POST method is now deprecated in favor of the PUT request. We recommend that you use the PUT request because the POST method will be removed from future API versions.

Please note when creating a bank account if you select iban_3 as the value for account_number_type then validations will be done on the account_number field to ensure it is in a valid IBAN format.

If you select account_type_1 for account_number_type then the API requires you fill out the transit_code_type field and will validate the value of the transit_code field based on this value.

If using Direct Debit/Reverse Wire functionality, the account_name must match the name of the company as it appears on the company bank statement - this field cannot be edited.

Endpoint: /add_bank

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`country_code`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	2	Yes	—
`currency_type_id`	An ID from the list of valid currency IDs, for example, EUR (Euro). See Currency Codes (ISO 4217) for more information.	Varchar	3	Yes	—
`account_name`	The name of the bank account. Only alphanumeric characters and spaces are allowed.	Varchar	50	Yes	—
`account_number_type`	The account number type. The value must be account_number_1 or iban_3. If the value is iban_3, the transit_code_type and transit_code fields can be left blank.	Varchar	20	Yes	—
`account_number`	A valid account number, or IBAN. This must match the type entered in the account_number_type field.	—	—	Yes	—
`transit_code_type`	A code from the list of valid transit codes, for example, sort_code_2 (Sort Code). See Transit Code Values for more information.	Varchar	—	Yes	—
`transit_code`	A valid code that must match the type entered in the transit_code_type field.	—	—	Yes	—
`swift`	The Swift or IBAN code, if known, for example, IPOBIE2D. This parameter must be included, but it can be left blank.	Varchar	50	Yes	—
`account_description`	This field is not mandatory. You can use it for your purposes to enter information that will help you recognize the account. It is strongly recommended not to use an account number or IBAN in this field	Varchar	50	Yes	—

Example Request

{
"country_code": "IE",
"currency_type_id": "EUR",
"account_name": "New Account",
"account_number_type": "iban_3",
"account_number": "IE29AIBK93115312345678",
"transit_code_type": " ",
"transit_code": " ",
"swift": "AIBKIE2D",
"account_description": "Irish Bank"
}

Response Body Payload Example

If the add bank request is successful and the service allocates an account ID, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	The status of the request, success.	Varchar
`qid`	The ID of the bank account, for example, 321894.	Integer

Example Success Response

{
"stat": "success",
"qid": 321894
}

Example Error Responses

If the add bank request is not successful, the service responds with an error code, rejects the request, and does not create the bank account. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`id`	The source of the error, for example, account number, currency ID, or database action.	Varchar
`description`	A description of the error encountered.	Varchar
`stat`	A status message that describes the error encountered.	Varchar

Error Code 531 - Account Exists, Unknown Currency, or Operation Unsuccessful.

[
{
"ID": "account_number",
"description": "Already exists!"
},
{
"ID": "currency_id",
"description": "Unknown currency"
},
{
"ID": "db_action",
"description": "Operation is not successful! Please try again."
}
]

Error Code 532 - One or More JSON Attributes Missing or Malformed

{
"stat": "One or More JSON Attributes Missing or Malformed: country_code"
}

Error Code 533 - Invalid Token or Missing Return Data

{
"stat": "Invalid token or missing return data"
}

POST Verify Existing Bank Account Details

You can get a list of active or inactive bank accounts with details by sending an HTTP POST request to the /view_banks endpoint.

Optionally, you can paginate the results to retrieve a certain number of bank accounts per page. If there are more than 25 bank accounts in the response, pagination occurs automatically.

Endpoint: /view_banks

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`show`	Include active or inactive bank accounts in the result. Set to 1 to return active accounts only. Set to 0 to return inactive accounts only. If this field is not included in the request it will default to 1 (Active).	Integer	—	No	1
`page_no`	Pagination occurs automatically if there are more than 25 bank accounts in the response. Set to 1 to call page 1, set to 2 to call page 2 etc.	Integer	—	No	1
`with_pagination_data`	Attach or exclude pagination metadata for the result. Set to 1 to attach pagination metadata. Set to 0 to exclude pagination metadata. Setting the value of this parameter to 1 changes the returned structure from a list to an object.	Integer	—	No	1

Example Request

{
"show": 1,
"page_no": 1,
"with_pagination_data": 1
}

{
"show": 1
}

Response Body Payload Example

If the view bank account details request is successful, the service returns a list of bank details. If pagination is requested then the metadata will be returned with information about this.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`banks`	A List of relevant.	list
`metadata`	If pagination is selected this will hold revlevant data about this.	object
`uid`	The internal unique ID of the bank, for example 49665.	Integer
`id`	The bank account ID.	Varchar
`account_name`	The name of the bank account.	Varchar
`account_description`	A text description for the bank account.	Varchar
`bank_name`	The name of the bank that manages the account.	Varchar
`country`	The country in which the bank is located.	Varchar
`currency`	The currency of the bank account.	Varchar
`tran_type`	The transaction type, for example, Wire Transfer.	Varchar
`reverse_wire`	A flag to indicate if reverse wire is enabled for the bank account. This is 1 if reverse wire is enabled and 0 if reverse wire is not enabled.	Varchar
`direct_debit`	A flag to indicate if direct debit is enabled for the bank account. This is 1 if direct debit is enabled and 0 if direct debit is not enabled.	Varchar
`wire_transfer`	A flag to indicate if wire transfer is enabled for the bank account. This is 1 if wire transfer is enabled and 0 if wire transfer is not enabled.	Varchar
`is_default`	A flag to indicate if this bank account is the default bank account for this currency. When money is recieved into a virtual bank account it will be automatically transfered into the defalut bank account of the same currency.	Integer
`bank_details`	Additional information about the bank account, such as the IBAN number and the SWIFT/BIC code.	Varchar
`active`	A flag to indicate if the bank account is active or inactive. This is 1 if the bank is active and 0 if the bank is inactive.	Varchar
`actions`	Specifies the actions that you can perform on the account, for example, Edit.	Varchar

Example Success Response

The returned JSON structure is as follows for request with parameter "with_pagination_data":

{
"banks": [
{
"uid": 49665,
"id": "49665",
"account_name": "Test",
"account_description": "None",
"bank_name": "CAISSE DESJARDINS DE JONQUIERE",
"country": "Canada",
"currency": "Canada Dollars (CAD)",
"tran_type": "Wire Transfer",
"reverse_wire": "0",
"direct_debit": "0",
"wire_transfer": "1",
"is_default": "0",
"bank_details": "Account (or IBAN) Number: 0xx-xxxx-xx64,SWIFT/BIC Code: Cxx-xxxx-xxMM",
"active": "1",
"actions": "Edit"
},
{
"uid": 42087,
"id": "42087",
"account_name": "None",
"account_description": "None",
"bank_name": "WELLS FARGO BANK, NATIONAL ASSOCIATION",
"country": "USA",
"currency": "United States of America Dollars (USD)",
"tran_type": "Wire Transfer",
"reverse_wire": "0",
"direct_debit": "0",
"wire_transfer": "1",
"is_default": "1",
"bank_details": "Account (or IBAN) Number: 1xx-xxxx-xx11,ABA / Routing Number: 0xx-xxxx-xx03,SWIFT/BIC Code: Wxx-xxxx-xxXX",
"active": "1",
"actions": "Edit"
}
],
"metadata": {
"current_page_size": 25,
"total_records_this_query": 173
}
}

The returned JSON structure is as follows for request without parameter "with_pagination_data":

{
"banks": [
{
"uid": 49665,
"id": "49665",
"account_name": "Test",
"account_description": "None",
"bank_name": "CAISSE DESJARDINS DE JONQUIERE",
"country": "Canada",
"currency": "Canada Dollars (CAD)",
"tran_type": "Wire Transfer",
"reverse_wire": "0",
"direct_debit": "0",
"wire_transfer": "1",
"is_default": "0",
"bank_details": "Account (or IBAN) Number: 0xx-xxxx-xx64,SWIFT/BIC Code: Cxx-xxxx-xxMM",
"active": "1",
"actions": "Edit"
},
{
"uid": 42087,
"id": "42087",
"account_name": "None",
"account_description": "None",
"bank_name": "WELLS FARGO BANK, NATIONAL ASSOCIATION",
"country": "USA",
"currency": "United States of America Dollars (USD)",
"tran_type": "Wire Transfer",
"reverse_wire": "0",
"direct_debit": "0",
"wire_transfer": "1",
"is_default": "1",
"bank_details": "Account (or IBAN) Number: 1xx-xxxx-xx11,ABA / Routing Number: 0xx-xxxx-xx03,SWIFT/BIC Code: Wxx-xxxx-xxXX",
"active": "1",
"actions": "Edit"
}
]
}

Example Error Responses

If the view existing account request is not successful, the service returns an error code, rejects the request, and does not return the existing account details. The relevant error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 536 - Invalid token example

{
"stat": "Invalid token"
}

POST Edit Existing Bank Account Details

You edit a bank account name or deactivate an account by sending an HTTP POST request to the /edit_bank endpoint.

You cannot recover or re-use an inactive account. Inactive accounts are removed from all live lists. See View Existing Bank Account Details to view inactive accounts.

Endpoint: /edit_bank

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id`	The ID of the bank account.	Integer	—	Yes	—
`account_name`	The updated name of the bank account.	Varchar	50	No	—
`is_active`	Set to 0 to permanently deactivate the account. Set to 1 to keep the account active.	Varchar	50	No	1

Example Request

{
"id": 65400,
"account_name": "Pies Plc.",
"is_active": 1
}

Response Body Payload Example

If the request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`id`	The bank account ID.	Varchar
`account_name`	The name of the bank account.	Varchar
`account_description`	A text description for the bank account.	Varchar
`bank_name`	The name of the bank that manages the account.	Varchar
`country`	The country in which the bank is located.	Varchar
`currency`	The currency of the bank account.	Varchar
`tran_type`	The transaction type, for example, Wire Transfer.	Varchar
`direct_debit`	A flag to indicate if direct debit is enabled for the bank account. This is 1 if direct debit is enabled and 0 if direct debit is not enabled.	Varchar
`wire_transfer`	A flag to indicate if wire transfer is enabled for the bank account. This is 1 if wire transfer is enabled and 0 if wire transfer is not enabled.	Varchar
`is_default`	A flag to indicate if this bank account is the default bank account for this currency. When money is recieved into a virtual bank account it will be automatically transfered into the defalut bank account of the same currency.	Integer
`bank_details`	Additional information about the bank account, such as the IBAN number and the SWIFT/BIC code.	Varchar
`active`	A flag to indicate if the bank account is active or inactive. This is 1 if the bank is active and 0 if the bank is inactive.	Varchar
`actions`	Specifies the actions that you can perform on the account, for example, Edit.	Varchar

Example Success Response

If the account is active (active = 1), the response is as follows:

{
"id": "65400",
"account_name": "Pies Plc.",
"account_description": null,
"bank_name": "NATIONAL AUSTRALIA BANK LIMITED",
"country": "Australia",
"currency": "Euro (EUR)",
"tran_type": "Wire Transfer",
"direct_debit": "0",
"wire_transfer": "1",
"is_default": "0",
"bank_details": "Account (or IBAN) Number: Bxx-xxxx-xx10", "BSB": "0xx-xxxxxx82",
"active": "1",
"actions": "Edit"
}

If the account is inactive (active = 0), the response is as follows:

{
"stat": "65389 has been disabled"
}

Example Error Responses

If the edit account request is not successful, the service responds with an error code. If the service returns an error, it rejects the request and does not edit the account information. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST Verify Existing Bank Account Details

You can verify existing bank account details by sending an HTTP POST request to the /verify_bank endpoint.

The request invokes an internal verifier that performs checks on the provided bank account details to ensure conformance to standards.

You must provide a valid value for at least one of the following parameters in the request:

iban (International Bank Account Number) natid (bank number, bank/branch code, sort code, or clearing code of a bank) bic (Bank Information Code) The response always contains a code and a message tag that provide an explanation of the result. For more information, see Bank Verifier Codes and Messages.

Endpoint: /verify_bank

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`country`	A two-letter ISO country code that identifies the country of the bank, for example, US (United States). See ISO 3166 for more information.	Char	2	Yes	—
`currency`	A three-character ISO currency code, for example, USD. Specify if known, otherwise use n/a. See Currency Codes (ISO 4217) for more information.	Varchar	3	No	—
`account_number`	The account number of the bank account you want to verify.	Varchar	20	Yes	—
`iban`	The International Bank Account Number (IBAN) of the account. If a value is given here natid and bic can be left blank.	Varchar	20	No	—
`natid`	The national identification number of the bank, which is also called ABA/Routing Number, Sort Code, Transit Number, BSB, Bank Code, or Bank Clearing Number. If a value is given here iban and bic can be left blank.	Varchar	20	No	—
`bic`	The Bank Identification Code (BIC), also known as the SWIFT Code. If a value is given here natid and iban can be left blank.	Varchar	20	No	—

Example Request

{
"country": "US",
"currency": "USD",
"account_number": "01245678",
"iban": "IE29 AIBK 9311 5312 3456 78",
"natid": "122105244",
"bic": "IPOBIE2D"
}

Response Body Payload Example

If the verify account request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`code`	The name of the bank.	Varchar
`bankname`	The name of the bank.	Varchar
`bankid`	The ID of the bank.	Varchar
`unqkey`	The unique internal ID of the bank.	Varchar
`message`	A message phrase that provides information about the verification.	Varchar

Example Success Response

{
"code": "1400",
"bankname": "FIRST CENTURY BANK, NATIONAL ASSOCIATION",
"bankid": "52661",
"unqkey": "97365396",
"message": "Valid data provided!"
}

Example Error Responses

If the verify account request is not successful, the service responds with an error code. If the service returns an error, it rejects the request and does not edit the account information. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar
`stat`	An error code.	Varchar
`message`	A description associated with an error code.	Varchar

Error Code 534 - specific issue with request, read message for more details

{
"code": "1020",
"message": "Selected country and IBAN country do not match!"
}

Beneficiary Account Management

A beneficiary account is the destination of a funds transfer. For example, a supplier bank account in an invoice payments system can be a beneficiary account.

Using the Payments API, you can:

Add a New Beneficiary Account
A beneficiary bank account must be verified before it is added to the system. The bank verifier provides an indication of possible issues when adding a new beneficiary account.
The business team adds details, such as payment types (for example, Direct Debit, ACH, or Wire), when the appropriate details are received.

Add a New Beneficiary Account V2

Disable an Existing Beneficiary Account

Edit an Existing Beneficiary Account
Once a beneficiary account is created, you can edit certain details.
You can edit the bank address, names associated with the account, and some non-mandatory fields.
You cannot edit account details such as the account ID or IBAN.

Edit an Existing Beneficiary Account V2

View Beneficiary Accounts
You can get a list of beneficiary accounts filtered by name (a single return) or country (multiple returns).

POST Add a New Beneficiary Account- Scheduled for depreciation 29th September 2025

You add a new beneficiary account by sending an HTTP POST request with the required account information to the /add_beneficiary endpoint.

Endpoint: /add_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`payee_name`	A unique payee name is used to identify the beneficiary account. Only alphanumeric characters and spaces are allowed. TM will reject all special characters and replace them with a space. All special characters will be replaced with a space.	Varchar	80	Yes	—
`client_id`	A unique alphanumeric string that may be given to identify the beneficiary account. It will accept "-".	Varchar	100	No	—
`duplicate_bene`	A field to determine whether a beneficiary is enabled as a duplicate beneficiary. This allows multiple beneficiaries to be set up with the same details. 1 is true, 0 is false.	Bit	1	No	—
`country_code`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	2	Yes	—
`country_id`	An ID from the list of valid country system IDs, for example, 113 (Ireland). See Country Reference by System ID for more information. If the country_code field has been populated, this can be left blank.	Varchar	3	No	—
`state`	The appropriate state in the US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	50	Yes	—
`currency_type_id`	An ID from the list of currency IDs. See Currency Codes (ISO 4217) for more information.	Varchar	20	Yes	—
`beneficiary_type_id`	The beneficiary type. Possible values are: 3 for an individual client, 23 for a corporate client.	Integer	—	Yes	23
`account_number_type`	The account number type. The value must be account_number_1 or iban_3. If the value is iban_3, the transit_code_type and transit_code fields can be left blank.	Varchar	20	Yes	—
`account_number`	The IBAN code, if known, otherwise the bank account number of the beneficiary.	Varchar	100	Yes	—
`transit_code_type`	The transit code type. This is a required field, but it can be left blank. See account_number_type description. See Transit Code Values for more information.	Varchar	—	Yes	—
`transit_code`	A valid code that must match the type entered in the transit_code_type field.	Varchar	100	Yes	—
`swift`	The SWIFT code is known. This is a required field if the account_number_type field is iban_3. Otherwise, it can be left blank. See the account_number_type description.	Varchar	11	Yes	—
`payee_address`	The address of the payee. All details are included in one field. To separate multiple address lines, please include _/ to indicate a line break. TM will reject the majority of special characters. It will accept _ / . &	Varchar	1000	Yes	—
`payee_city`	The name of the city where the payee resides.	Varchar	255	Yes	—
`payee_postal_code`	The postal code of the payee. This field is mandatory for the following countries: USA, Canada, Malaysia, NZ, Australia, and the Philippines.	Varchar	20	Yes	—
`payee_phone_number_international_dialing_code`	The international dialing code of the country in which the payee resides. See Country Code for more information.	Varchar	80	No	—
`payee_phone_number_mobile_phone`	The mobile phone contact number for the payee.	Varchar	80	No	—
`payee_dob`	The date of birth of the payee. This is taken in the format YYYY-MM-DD.	Varchar	80	No	—
`payee_country`	An ISO standard country code for the payee from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	3	Yes	—
`payee_state`	The appropriate state of the payee in the US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	50	Yes	—
`bank_branch_address`	The address of the branch of the payee's bank. All details are included in one field. To separate multiple address lines, please include _/ to indicate a line break. This field can be left blank. TM will reject the majority of special characters. It will accept _ /. &	Varchar	1000	No	—
`bene_bank_account_type`	Only for Chile. Two values are "checking_50" or "saving_52".	String	—	No (Only for Chile)	—
`account_type`	The account type. For India, this field is mandatory. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident. For all other countries, this can be left blank.	Varchar	10	Yes(Only in India)	—
`for_further_credit_to`	The name of the final beneficiary if this is a 4th-party payment. This is a compliance requirement. Only alphanumeric values and spaces will be accepted. TM will reject the majority of special characters. It will accept _ / . &.	Varchar	1000	No	—
`def_payment_reference`	Free text that represents the default reference for payments. TM will accept special characters !£$%^&*()_+-={}[]:;@'~#,./?.	Varchar	250	Yes	—
`def_transfer_reason`	Default reason for payment. Can be left blank.	String	—	Yes	—
`def_transfer_reason_id`	Default reason for payment. See Transfer Reasons for more information.	Integer	—	Yes	—
`email`	A valid email address if the beneficiary to receive updates on transactions. (Required if payment is coming from California or the beneficiary is in California) TM will reject the majority of special characters. It will accept @. _ -.	Varchar	150	No	—
`email_alert_flag`	email_alert_flag	Bit	1	No	—
`payee_tax_id`	The beneficiary tax registration number. Only alphanumeric values will be accepted.	Varchar	20	No	—
`passport_number`	The Passport number of the beneficiary. Only alphanumeric values and spaces will be accepted.	Varchar	20	No	—
`additional_routing_number`	A valid code that must match the type entered in the transit_code_type field. This field can be used if the beneficiary account has an ABA routing number for ACH and a different ABA routing number for WIRE. - Please use this field for WIRE ONLY.	Varchar	100	No	—

Example Request

{
"payee_name": "Bogo MIPS PLC",
"client_id": "8cc94b579dc7ef71e520bcbd8c9912c99b1b9a35",
"duplicate_bene": 0,
"country_code": "IE",
"state": "",
"currency_type_id": "EUR",
"account_number": "IE29AIBK93115312345678",
"account_number_type": "iban_3",
"transit_code_type": "",
"transit_code": "",
"additional_routing_number": "",
"swift ": "BOFIIE2D",
"beneficiary_type_id": 23,
"payee_address": "1_/Main Street_/Town",
"payee_city": "New York",
"payee_country": "US",
"payee_state": "US-NY",
"payee_postal_code": "10001",
"payee_phone_number_international_dialing_code": "ie 353",
"payee_phone_number_mobile_phone": "871234567",
"payee_dob": "1984-06-25",
"bank_branch_address": "bank address on one line",
"account_type": "",
"for_further_credit_to": "follow-on further documentation",
"def_payment_reference": "default payment reference",
"def_transfer_reason_id": "7",
"email": "acm2e@wily.com",
"email_alert_flag": 0,
"payee_tax_id": "12345",
"passport_number": "54321"
}

Response Body Payload Example

If the Add Beneficiary request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	The status of the request, success.	Varchar
`qid`	The ID of the bank account, for example, 321894.	Integer

Example Success Response

{
"stat": "success",
"qid": 321894
}

Example Error Responses

If the add beneficiary bank account request is not successful, the service responds with an error code, rejects the request, and does not create the new beneficiary account. Some examples of the error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`id`	The source of the error, for example, account number, currency ID, or database action.	Varchar
`description`	A description of the error encountered.	Varchar
`stat`	A status message that describes the error encountered.	Varchar

Error Code 521 - Account Number Exists, Client ID Exists, or Unsuccessful Operation

[
{
"id": "iban_account_number",
"description": "Already exists!"
},
{
"id": "client_id",
"description": "Already exists!"
},
{
"id": "db_action",
"description": "Operation is not successful! Please try again."
}
]

Error Code 522 - One or More JSON Attributes Are Missing or Malformed

{
"stat": "One or more JSON attributes missing or malformed: country_id"
}

Error Code 523 - Invalid Token or Missing Return Data

{
"stat": "Invalid token or missing return data"
}

POST Add a New Beneficiary Account V2

You add a new beneficiary account by sending an HTTP POST request with the required account information to the /v2/add_beneficiary endpoint.

Endpoint: /v2/add_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`payee_name`	A unique payee name is used to identify the beneficiary account. Only alphanumeric characters and spaces are allowed. TM will accept special characters ( ) . , - '_ : ; &"	Varchar	80	Yes	—
`client_id`	A unique alphanumeric string that may be given to identify the beneficiary account. It will accept "-".	Varchar	100	No	—
`duplicate_bene`	A field to determine whether a beneficiary is enabled as a duplicate beneficiary. This allows multiple beneficiaries to be set up with the same details. 1 is true, 0 is false.	Bit	1	No	—
`country_code`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	2	Yes	—
`state_iso`	The appropriate State is mandatory for Australia, New Zealand, the USA, and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	6	Conditional	—
`currency_type_id`	An ID from the list of currency IDs. See Currency Codes (ISO 4217) for more information.	Varchar	20	Yes	—
`beneficiary_type_id`	The beneficiary type. Possible values are: 3 for an individual client, 23 for a corporate client.	Integer	—	Yes	—
`account_number_type`	The account number type. The value must be account_number_1 or iban_3. If the value is iban_3, the transit_code_type and transit_code fields can be left blank.	Varchar	20	Yes	—
`account_number`	The IBAN code, if known, or otherwise the bank account number of the beneficiary.	Varchar	100	Yes	—
`transit_code_type`	The transit code type. This is a required field, but it can be left blank. See account_number_type description. See Transit Code Values for more information.	Varchar	—	Yes	—
`transit_code`	A valid code that must match the type entered in the transit_code_type field.	Varchar	100	Yes	—
`swift`	This is a required field if the account_number_type field is iban_3. Otherwise, consult the beneficiary rules.	Varchar	11	Conditional	—
`payee_city`	The name of the city where the payee resides.	Varchar	255	Yes	—
`payee_building _name`	The building number or name where the payee resides. Allowed characters: Latin letters A-Z, a-z, numbers 0-9 , - , _ , % , . : ; , ' space, ()	Varchar	40	Yes	—
`payee_street_name`	The street name where the payee resides. Allowed characters: Latin letters A-Z, a-z, numbers 0-9 , - , _ , % , . : ; , ' space, ()	Varchar	70	Yes	—
`payee_town_name`	The town name where the payee resides. Allowed characters: Latin letters A-Z, a-z, numbers 0-9 , - , _ , % , . : ; , ' space, ()	Varchar	35	Yes	—
`payee_postal_code`	The postal code of the payee. This field is mandatory for the following countries: Australia, Canada, Mexico, Malaysia, New Zealand, Serbia, Sweden, the Philippines, the UAE, and the USA.	Varchar	20	Conditional	—
`payee_country_iso`	An ISO standard country code for the payee from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	2	Yes	—
`payee_state_iso`	Mandatory for Australia, New Zealand, the USA, and Canada. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	50	Conditional	—
`payee_phone_number_international_dialing_code`	The international dialing code of the country in which the payee resides. See Country Code for more information.	Varchar	80	Conditional	—
`payee_phone_number_mobile_phone`	The mobile phone contact number for the payee.	Varchar	80	Conditional	—
`payee_dob`	The date of birth of the payee. This is taken in the format dd/mm/yyyy.	Varchar	80	Mandatory only for Individual Benes only with Curr = CNY and Country = China	—
`bank_branch_address`	The address of the branch of the payee's bank. All details are included in one field. To separate multiple address lines, please include _/ to indicate a line break. This field can be left blank. TM will reject the majority of special characters. It will accept _ /. &	Varchar	1000	Conditional	—
`bene_bank_account_type`	Only for Chile. Two values are "checking_50" or "saving_52".	Varchar	—	No (Only for Chile)	—
`account_type`	The account type. For India, this field is mandatory. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident. For all other countries, this can be left blank.	Varchar	10	Conditional	—
`for_further_credit_to`	The name of the final beneficiary if this is a 4th-party payment. This is a compliance requirement. Only alphanumeric values and spaces will be accepted. TM will reject the majority of special characters. It will accept _ / . &.	Varchar	1000	No	—
`def_payment_reference`	Free text that represents the default reference for payments. TM will accept special characters !£$%^&*()_+-={}[]:;@'~#,./?	Varchar	250	Yes	—
`def_transfer_reason`	Default reason for payment. Can be left blank.	Integer	—	Yes	—
`def_transfer_reason`	Default reason for payment: See Transfer Reasons for more information.	Integer	—	Yes	—
`email`	A valid email address if the beneficiary is to receive updates on transactions. (Required if payment is coming from California or the beneficiary is in California) TM will reject the majority of special characters. It will accept @. _ -.	Varchar	150	Conditional	—
`email_alert_flag`	1 for yes 0 for no	Bit	1	Yes	—
`payee_tax_id`	The beneficiary tax registration number. Only alphanumeric values will be accepted.	Varchar	20	No	—
`passport_number`	The Passport number of the beneficiary. Only alphanumeric values and spaces will be accepted.	Varchar	20	Conditional	—
`additional_routing_number`	A valid code that must match the type entered in the transit_code_type field. This field can be used if the beneficiary account has both an ABA routing number for ACH and a separate ABA routing number for wire transfers. Please use this field for WIRE ONLY.	Varchar	100	Conditional	—
`bene_company_register_num`	The beneficiary company's registered number.	Varchar	30	Only for Corporate Beneficiaries with Curr = ILS and Country = Israel	—
`bene_nationality`	ISO code of the Beneficiary National country.	Varchar	3	Only for Individual Benes only with Curr = BDT and Country = Bangladesh	—
`employee_id*`	Employee ID	Integer	4-15	Only for WPS Individual Beneficiaries, where Beneficiary Category=2, Beneficiary country= UAE, Beneficiary currency= AED	1
`beneficiary_category*`	Beneficiary category. Possible values are: 1 - Standard beneficiaries, 2 - WPS Beneficiaries.	Integer	1	Only for WPS Individual Beneficiaries, where Beneficiary Category=2, Beneficiary country= UAE, Beneficiary currency= AED	—

Example Request

An example of the JSON structure in the request is as follows:

{
"short_response": 1,
   "duplicate_bene": 0,
   "beneficiary_type_id": "",
   "payee_name": "test_beneficiary",
   "country_code": "IE",
   "state_iso": "",
   "state": "",
   "currency_type_id": "GBP",
   "account_number_type": "account_number_1",
   "account_number": "api_account_number_api",
   "transit_code_type": "bik_28",
   "transit_code": "buin7005",
   "swift": "",
   "additional_routing_number": "",
   "payee_country": "",
   "payee_country_iso": "",
   "payee_state_iso": "",
   "payee_state": "",
   "payee_city": "",
   "payee_town_name": "",
   "payee_street_name": "",
   "payee_building_name": "",
   "payee_postal_code": "",
   "payee_tax_id": "",
   "payee_address": "",
   "payee_phone_number_international_dialing_code": "",
   "payee_phone_number_mobile_phone": "",
   "account_type": "",
   "bene_bank_account_type": "",
   "bene_nationality": "",
   "payee_dob": "",
   "passport_number": "",
   "bene_company_register_num": "",
   "bank_branch_address": "",
   "for_further_credit_to": "",
   "def_payment_reference": "",
   "def_transfer_reason": "",
   "email": "",
   "email_alert_flag": 0,
   "client_id": "",
"beneficiary_category": "1",
   "employee_id": "",
}

Response Body Payload Example

FIELD	DESCRIPTION	TYPE
`alert`	Beneficiary verification alert.	Varchar
`is_successful`	True or false.	Varchar
`stat`	Success.	Varchar
`qid`	The ID of the beneficiary.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
"messages": {
"alert": "By continuing you are saying you have checked and trust all the Beneficiary details – Payee Name and Bank Account. If you are unsure, please do not proceed. Instead go back to check, as payments sent to the wrong account or beneficiary may not be able to be recovered by TransferMate. TransferMate verifies Beneficiary details where possible – view your settings API Endpoint. Please note fee will apply.",
       "success": "Action performed successfully."
   },
   "is_successful": true,
   "stat": "success",
   "qid": 4043874
}

Example Error Responses

If the /v2/add_beneficiary request is not successful, the service responds with an error code, rejects the request, and does not create the beneficiary. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`ID`	Field that failed.	Varchar
`description`	Description of error.	Varchar

Error Code 521

[
{
"ID": "db_action",
"description": "Operation is not successful! Please try again."
   },
   {
"ID": "payee_name",
"description": "Already exists! Existing Bene ID: 3841899"
   }
]

POST Disable an Existing Beneficiary Account

You disable a beneficiary account by sending an HTTP POST request with the required account information to the /disable_beneficiary endpoint.

Endpoint: /disable_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`beneficiary_id`	The beneficiary ID of the beneficiary account to disable. This is the unique ID assigned to the account by TransferMate.	Varchar	—	No	—
`client_id`	The client ID of the beneficiary account to disable. This is the unique ID assigned to account by the user. Please see Add a New Beneficiary Account for details.	Varchar	—	No	—

Example Request

{
"beneficiary_id": "123456"
}

{
"client_id": "ABCD1234"
}

Response Body Payload Example

If the disable beneficiary account request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	The status of the request, success.	Varchar

Example Success Response

{
"stat": "'id' disable operation complete"
}

Example Error Responses

If the disable beneficiary bank account request is not successful, the service responds with an error code and rejects the request.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 400 - Disable not successful

{
"stat": "'id' disable operation not successful. Either 'id' does not exist or 'id' cannot be disabled at this time"
}

POST Edit an Existing Beneficiary Account- - Scheduled for depreciation 29th September 2025

You edit an existing beneficiary account by sending an HTTP POST request with the required account information to the /edit_beneficiary endpoint.

Certain fields cannot be edited i.e. beneficiary_id.

Note: Some fields cannot be edited after a booking has taken place for the associated beneficiary. These are indicated in the input parameters below with an '*'. E.g client_id.

Endpoint: /edit_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`beneficiary_id`	The ID of the beneficiary account to be edited. Either the beneficiary_id or client_id must be given.	Varchar	—	Yes	—
`beneficiary_type_id*`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar	20	No	—
`client_id*`	A unique alpha-numeric string which may be given in order to identify the beneficiary account. It will accept "-".	Varchar	—	No	—
`payee_name`	Name of the beneficiary.	Varchar	—	No	—
`duplicate_bene`	A field to determine whether a beneficiary is enabled as a duplicate beneficiary. This allows multiple beneficiaries to be set up with the same details. 1 is true, 0 is false.	Bit	1	No	—
`payee_address`	The address of the payee. All details are included in one field. To seperate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It will accept _ / . &	Varchar	1000	No	—
`payee_city`	The name of the city where the payee resides.	Varchar	255	No	—
`payee_postal_code`	The postal code of the payee. This field is mandatory for the following countries: USA, Canada, Malaysia, NZ, Australia and Philippines.	Varchar	20	No	—
`payee_phone_number_international_dialing_code`	The international dialing code of the country in which the payee resides. See Country Code for more information.	Varchar	80	No	—
`payee_phone_number_mobile_phone`	The mobile phone contact number for the payee.	Varchar	20	No	—
`def_transfer_reason`	Default reason for payment. Can be left blank.	Integer	—	No	—
`def_payment_reference`	Free text that represents the default reference for payments. TM will accept special characters !£$%^&*()_+-={}[]:;@'~#,./?.	Varchar	250	No	—
`email`	A valid email address if the beneficiary is to receive updates on transactions. (Required if payment is coming from California or beneficiary is in California) TM will reject majority special characters. It Will accept @ . _ -.	Varchar	150	No	—
`email_alert_flag`	email_alert_flag	Bit	1	No	—
`is_active`	A flag that indicates if the beneficiary is active or not. Set to 1 to keep the beneficiary active. Set to 0 to deactivate the beneficiary.	Bit	1	No	—
`payee_tax_id`	The beneficiary tax registration number. Only Alpha numeric values will be accepted.	Varchar	20	No	—
`payee_dob*`	The date of birth of the payee. This is taken in the format YYYY-MM-DD.	Varchar	20	No	—
`additional_routing_number`	A valid code which must match the type entered in the transit_code_type field. This field can be used if the beneficiary account has an ABA routing number for ACH and different ABA routing number for WIRE - Please use this field for WIRE ONLY.	Varchar	100	No	—

Example Request

{
"beneficiary_id": "123456",
"payee_name": "edit_bene_test",
"email": "test@test.com"
}

{
"beneficiary_id": "123456",
"payee_dob": "12/03/1990"
}

{
"beneficiary_id": "123456",
"is_active": "0"
}

{
"beneficiary_id": "123456",
"additional_routing_number": "121000248",
"is_active": "1"
}

Response Body Payload Example

If the Edit Beneficiary request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	The status of the request, success.	Varchar

Example Success Response

{
"stat": "update complete"
}

Example Error Responses

If the edit beneficiary account request is unsuccessful, the service returns a response.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST Edit an Existing Beneficiary Account V2

You edit an existing beneficiary account by sending an HTTP POST request with the required account information to the /v2/edit_beneficiary endpoint.

Endpoint: /v2/edit_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`beneficiary_id`	The ID of the beneficiary account to be edited. Either the beneficiary_id or client_id must be given.	Varchar	—	No	—
`payee_name`	A unique payee name used to identify the beneficiary account. Only alphanumeric characters and spaces are allowed. TM will accept special characters ( ) . , - '_ : ; &"	Varchar	80	Yes	—
`additional_routing_number`	A valid code which must match the type entered in the transit_code_type field. This field can be used if the beneficiary account has an ABA routing number for ACH and different ABA routing number for WIRE - Please use this field for WIRE ONLY.	Varchar	100	Conditional	—
`payee_country_iso`	An ISO standard country code for the payee from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	3	Yes	—
`payee_state_iso`	Mandatory for Australia, New Zealand, USA and Canadian For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	50	Conditional	—
`payee_city`	The name of the city where the payee resides.	Varchar	255	Yes	—
`payee_town_name`	The town name where the payee resides.	Varchar	35	Yes	—
`payee_street_name`	The building number or name where the payee resides.	Varchar	70	Yes	—
`payee_building_name`	The building number or name where the payee resides.	Varchar	40	Yes	—
`payee_postal_code`	The postal code of the payee. This field is mandatory for the following countries: Australia, Canada, Mexico, Malaysia, New Zealand, Serbia, Sweden, The Philippines, UAE and USA.	Varchar	20	Conditional	—
`is_active`	A flag that indicates if the beneficiary is active or not. Set to 1 to keep the beneficiary active. Set to 0 to deactivate the beneficiary.	Bit	—	Yes	—
`payee_tax_id`	The beneficiary tax registration number. Only Alpha numeric values will be accepted.	Varchar	20	No	—
`payee_phone_number_international_dialing_code`	The international dialing code of the country in which the payee resides. See Country Code for more information.	Varchar	80	Conditional	—
`payee_phone_number_mobile_phone`	The mobile phone contact number for the payee.	Varchar	80	Conditional	—
`payee_dob*`	The date of birth of the payee. This is taken in the format DD/MM/YYYY	Varchar	80	No	—
`passport_number`	The Passport number of the beneficiary.Only Alpha numeric values and spaces will be accepted.	Varchar	20	Conditional	—
`bene_company_register_num`	The Company register number of the beneficiary.	Varchar	30	Only for Corporate Beneficiaries with Curr = ILS and Country = Israel	—
`account_type`	The account type. For India, this field is mandatory. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident. For all other countries this can be left blank.	Varchar	10	Conditional	—
`bene_bank_account_type`	Only for Chile. Two values are "checking_50" or "saving_52".	Varchar	—	No (Only for Chile)	—
`bene_nationality`	ISO code of the Beneficiary National country.	Varchar	3	Only for Individual Benes only with Curr = BDT and Country = Bangladesh	—
`bank_branch_address`	The address of the branch of the payee's bank. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. This field can be left blank. TM will reject majority special characters. It Will accept _ / . &	Varchar	1000	Conditional	—
`def_payment_reference`	Free text that represents the default reference for payments. TM will accept special characters !£$%^&*()_+-={}[]:;@'~#,./?	Varchar	250	Yes	—
`def_transfer_reason`	Default reason for payment. Can be left blank.	Integer	—	Yes	—
`def_transfer_reason_id`	Default reason for payment. See Transfer Reasons for more information.	Integer	—	Yes	—
`email`	A valid email address if the beneficiary is to receive updates on transactions. (Required if payment is coming from California or the beneficiary is in California) TM will reject the majority of special characters. It will accept @. _ -.	Varchar	150	Conditional	—
`email_alert_flag`	1 for yes 0 for no	Bit	1	Yes	—
`beneficiary_type_id`	The beneficiary type. Possible values are 3 for an individual client and 23 for a corporate client.	Integer	—	Yes	—

Example Request

An example of the JSON structure in the request is as follows:

{
   "short_response": 1,
   "beneficiary_id": 15285,
   "duplicate_bene": 0,
   "beneficiary_type_id": "",
   "payee_name": "test_beneficiary",
   "state_iso": "",
   "state": "",
   "additional_routing_number": "",
   "payee_country": "",
   "payee_country_iso": "",
   "payee_state_iso": "",
   "payee_state": "",
   "payee_city": "",
   "payee_town_name": "",
   "payee_street_name": "",
   "payee_building_name": "",
   "payee_postal_code": "",
   "payee_tax_id": "",
   "payee_address": "",
   "__payee_phone_number_international_dialing_code": "",
   "__payee_phone_number_mobile_phone": "",
   "account_type": "",
   "bene_bank_account_type": "",
   "bene_nationality": "",
   "bene_date_birth": "",
   "bene_passport_number": "",
   "bene_company_register_num": "",
   "bank_branch_address": "",
   "def_payment_reference": "",
   "def_transfer_reason": "",
   "email": "",
   "email_alert_flag": 0,
   "client_id": "",
   "is_active": 0
}

Response Body Payload Example

If the Edit Beneficiary request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	The status of the request, success.	Varchar

Example Success Response

{
"stat": "update complete"
}

Example Error Responses

If the edit beneficiary account request is unsuccessful, the service returns a response.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POSTView Beneficiary Accounts

You view beneficiary accounts by sending an HTTP POST request with the required account information to the /view_beneficiaries endpoint.

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`beneficiary_name`	This field can be used to search on different values. You can input the name of a single beneficiary account. Use * symbol if not sure for one or more letters. To search by Bene ID, input "#:bene_ID".To search by E-mail, input "@:email".To search by Client ID, input "$:client-id".	Varchar	50	Yes	—
`beneficiary_country`	A country in which there are one or more beneficiary accounts.	Varchar	50	Yes	—
`page_no`	A page navigation value for pagination and retrieving a specific page in the grid.	Integer	—	No	1
`with_pagination_data`	Attach or exclude pagination metadata for the result. Set to 1 to attach pagination metadata. Set to 0 to exclude pagination metadata. Setting the value of this parameter to 1 changes the returned structure from a list to an object.	Integer	—	No	1

Example Request

An example of the JSON structure (with Beneficiary Name) in the request is as follows:

{
"beneficiary_name": "Bogo MIPS PLC"
}

An example of the JSON structure (with Beneficiary Id) in the request is as follows:

{
"beneficiary_name": "#:637104"
}

An example of the JSON structure (with Client ID) in the request is as follows:

{
"beneficiary_name": "$:TM1234"
}

An example of the JSON structure (with Beneficiary Email) in the request is as follows:

{
"beneficiary_name": "@:test@test.com"
}

An example of the JSON structure (with blank beneficiary name and page number) in the request is as follows:

{
"beneficiary_name": "",
"page_no": 25
}

Response Body Payload Example

If the view beneficiary accounts request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`id`	The ID of the beneficiary account.	Varchar
`payee_name`	The name of the payee.	Varchar
`bene_id`	The beneficiary ID.	Varchar
`bene_id`	The beneficiary ID.	Varchar
`currency`	The currency type. See Currency Codes (ISO 4217) for more information.	Varchar
`user_email`	The email address of the beneficiary.	Varchar
`email_alert_flag`	TA flag that idicates if the beneficiary is to receive transaction updates or not. A value of 1 indicates that email updates are enabled. A value of 0 indicates that email updates are not enabled.	Varchar
`country`	The country in which the beneficiary resides.	Varchar
`def_payment_reference`	Arbitrary text that identifies the transfer for the beneficiary.	Varchar
`def_transfer_reason`	The reason for the transfer.	Varchar
`bank_details`	The beneficiary bank account details.	Varchar
`active`	Indicates whether the beneficiairy is active and can be paid. 0: Inactive, 1: Active, 4: Rejected, 5: Pending.	Varchar
`account_type`	Indicates wheteher the beneficiary is a resident of the country or not. Only applicable to India. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident.	Varchar
`payee_addess`	The address of the beneficiary.	Varchar
`bank_branch_address`	The address of the branch of the payee's bank.	Varchar

Example Success Response

{
"id": "637104",
"payee_name": "Bogo MIPS PLC",
"bene_id": "637104",
"currency": "EUR",
"user_email": "test@test.com",
"email_alert_flag": "X",
"country": "Ireland",
"def_payment_reference": "Test payment",
"def_transfer_reason": "Bill payment",
"bank_details": "THE GOVERNOR AND COMPANY OF THE BANK OF IRELAND",
"Account (or IBAN) Number": "Ixx-xxxx-xx84",
"SWIFT/BIC Code": "Bxx-xxxx-xx2D",
"client_id": "TM1234",
"active": "1",
"actions": " ",
"account_type": null,
"payee_address": "1 Main Street, Dublin",
"bank_branch_address": null
}

Example Error Responses

If the view beneficiary account request is not successful, the service responds with an error code, rejects the request, and does not return the beneficiary account details. An example error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 500 - Invalid Parameter Format

{
"stat": "invalid parameter format"
}

POSTView Beneficiary Accounts V2

You view beneficiary accounts by sending an HTTP POST request with the required account information to the /v2/view_beneficiaries endpoint.

Endpoint: /v2/view_beneficiaries

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`beneficiary_name`	This field can be used to search on different values. You can input the name of a single beneficiary account. Use * symbol if not sure for one or more letters. To search by Bene ID, input "#:bene_ID".To search by E-mail, input "@:email".To search by Client ID, input "$:client-id".	Varchar	50	Yes	—
`beneficiary_country`	A country in which there are one or more beneficiary accounts.	Varchar	50	Yes	—
`page_no`	A page navigation value for pagination and retrieving a specific page in the grid.	Integer	—	No	1
`with_pagination_data`	Attach or exclude pagination metadata for the result. Set to 1 to attach pagination metadata. Set to 0 to exclude pagination metadata. Setting the value of this parameter to 1 changes the returned structure from a list to an object.	Integer	—	No	1

Example Request

An example of the JSON structure (with Beneficiary Name) in the request is as follows:

{
"beneficiary_name": "Bogo MIPS PLC"
}

An example of the JSON structure (with Beneficiary Id) in the request is as follows:

{
"beneficiary_name": "#:637104"
}

An example of the JSON structure (with Client ID) in the request is as follows:

{
"beneficiary_name": "$:TM1234"
}

An example of the JSON structure (with Beneficiary Email) in the request is as follows:

{
"beneficiary_name": "@:test@test.com"
}

An example of the JSON structure (with blank beneficiary name and page number) in the request is as follows:

{
"beneficiary_name": "",
"page_no": 25
}

Response Body Payload Example

If the view beneficiary accounts request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`id`	The ID of the beneficiary account.	Varchar
`payee_name`	The name of the payee.	Varchar
`bene_id`	The beneficiary ID.	Varchar
`country_default_currency`	Default country currency. See Currency Codes (ISO 4217) for more information.	Varchar
`currency`	The currency type. See Currency Codes (ISO 4217) for more information.	Varchar
`user_email`	The email address of the beneficiary.	Varchar
`email_alert_flag`	This flag indicates whether the beneficiary is to receive transaction updates or not. A value of 1 indicates that email updates are enabled. A value of 0 indicates that email updates are not enabled.	Varchar
`country`	The country in which the beneficiary resides.	Varchar
`def_payment_reference`	Arbitrary text that identifies the transfer for the beneficiary.	Varchar
`def_transfer_reason`	The reason for the transfer.	Varchar
`bank_details`	The beneficiary bank account details.	Varchar
`client_id`	The Client ID	Varchar
`active`	Indicates whether the beneficiary is active and can be paid. 0: Inactive, 1: Active, 4: Rejected, 5: Pending.	Varchar
`account_type`	Indicates whether the beneficiary is a resident of the country or not. Only applicable to India. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident.	Varchar
`payee_addess`	The address of the beneficiary.	Varchar
`bank_branch_address`	The address of the branch of the payee's bank.	Varchar
`beneficiary_type_id`	The type of the beneficiary. ID 23= Corporate, ID 3=Personal	Varchar
`bene_verification_status`	Display the status of the Verfication of Payee	Varchar
`bene_verification_status_txt`	Display the status of the Verfication of Payee	Varchar
`payee_country`	Payee country ID	Varchar
`payee_country_iso`	Payee country	Varchar
`payee_state`	Payee state ID	Varchar
`payee_state_iso`	Payee state	Varchar
`payee_city`	Payee city	Varchar
`payee_tax_id`	Payee tax ID	Varchar
`payee_phone_number`	Payee phone number	Varchar
`payee_zipcode`	Payee address zip code	Varchar
`payee_town_name`	Payee town name	Varchar
`payee_street_name`	Payee street name	Varchar
`payee_building_name`	Payee building name	Varchar
`dublicate_bene`	indicates if the Beneficiary is a duplicate or not. 0= No, 1=Yes	Varchar
`for_further_credit_to`	Indicates if the Beneficiary is for further credit	Varchar
`beneficiary_category`	Beneficiary category ID	Varchar
`employee_id`	Employee ID	Varchar

Example Success Response

{
"id": "637104",
"payee_name": "zzz",
"bene_id": "4397450",
"currency": "EUR",
"country_default_currency": "EUR",
"user_email": "test@transfermate.com",
"email_alert_flag": "X",
"country": "Belgium",
"def_payment_reference": "Test payment 123",
"def_transfer_reason": "Bill payment",
"bank_details": "CACEIS BANK, Account (or IBAN) Number: Bxx-xxxx-6858",
"client_id": null,
"active": "1",
"account_type": null,
"payee_address": "Brussels 31 Brussels Street The Big Building",
"bank_branch_address": null,
"beneficiary_type_id": "23",
"tr_status": "0",
"bene_verification_status": "",
"bene_verification_status_txt": "Null",
"payee_country": "23",
"payee_country_iso": "Belgium",
"payee_state": "",
"payee_state_iso": "",
"payee_city": "Brussels",
"payee_tax_id": "",
"payee_phone_number": "be 325555555559",
"payee_zipcode": "1000",
"payee_town_name": "Brussels",
"payee_street_name": "31 Brussels Street",
"payee_building_name": "The Big Building",
"duplicate_bene": "0",
"for_further_credit_to": null,
"beneficiary_category": "",
"employee_id": ""
}

Example Error Responses

If the view beneficiary account request is not successful, the service responds with an error code, rejects the request, and does not return the beneficiary account details. An example error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 500 - Invalid Parameter Format

POST Verification Service List

As a response of this endpoint, client will receive a list with all Beneficiary countries, where we provide Beneficiary verification.

Please contact your partner implementation manager at partnerimplementation@transfermate.com if you would like access to this functionality.

Endpoint: /verification_services_list

Example Request

{}

Response Body Payload Example

FIELD	DESCRIPTION	TYPE
`messages`	List of messages associated with the response.	List
`success`	Any messages associated with this request.	Varchar
`service_id`	Unique ID of the provided service.	Integer
`country`	Beneficiary country.	Varchar
`currency`	The currency type. See Currency Codes (ISO 4217) for more information.	Varchar
`verification_available`	Display type of verification available for the country.	Varchar
`fee`	Fee for the service.	Decimal
`status`	Status of the service for this beneficiary country.	Varchar

Example Success Response

{
   "is_successful": true,
   "messages": {
      "success": "Action performed successfully."
   },
   "verification_services": [
      {
         "service_id": 630170,
         "country": "Argentina",
         "verification_available": "Beneficiary accounts in any currency",
         "fee": "0.40 USD",
         "status": "Disabled"
      },
      {
         "service_id": 630171,
         "country": "Bangladesh",
         "verification_available": "Beneficiary accounts in any currency",
         "fee": "0.20 USD",
         "status": "Disabled"
      },
      {
         "service_id": 630172,
         "country": "Belgium",
         "verification_available": "Beneficiary accounts in any currency",
         "fee": "2.40 USD",
         "status": "Disabled"
      },
      {
         "service_id": 630173,
         "country": "Brazil",
         "verification_available": "Beneficiary accounts in domestic currency",
         "fee": "0.70 USD",
         "status": "Disabled"
      },
      {
         "service_id": 630191,
         "country": "Vietnam",
         "verification_available": "Beneficiary accounts in domestic currency",
         "fee": "0.24 USD",
         "status": "Disabled"
      }
   ]
}

POST Verification Service Edit

Using this endpoint, client can activate or disable a beneficiary verification service for a country.

Client can disable/enable more than one country as per endpoint, but they can only do one action- multiple enable or multiple disable.

Endpoint: /verification_services_edit

Request Body Payload Example

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`service_ids`	A list of service IDs, multiple add available.	List	-	Yes	1
`active`	Status of the service, possible values: 1- to activate/enable 0- disable	Bit	1	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"service_ids": [
630191,
630187,
630186
],
"active": "1"
}

Response Body Payload Example

FIELD	DESCRIPTION	TYPE
`is_successful`	Status of the request.	Varchar
`stat`	A status message that describes the error encountered.	Varchar
`messages`	List of messages associated with the response.	List
`global_errors`	Global errors associated with the request.	List

Example Success Response

{
   "is_successful": true,
   "stat": "Service IDs 630186,630187,630191 successfully updated.",
   "messages": {
      "alert": "For some countries, no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply."
   }
}

Example Error Responses

HTTP ERROR 522 - Bad request

// Missing active|service_ids param

{
   "is_successful": false,
   "messages": {
      "alert": "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply.",
      "db_action": "Operation is not successful! Please try again."
   },
   "stat": "One or more JSON attributes missing or malformed: 'service_ids'"
}

HTTP ERROR 521 - Bad Request

// Invalid "active" param -> for example "active": "asdasd"

{
   "is_successful": false,
   "messages": [
      "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply."
   ],
   "global_errors": [],
   "input_errors": [
      {
         "ID": "active",
         "description": "Please enter correct information!"
      }
   ]
}

HTTP ERROR 422 - Unprocessable Entity

// Empty "service_ids" provided -> for example "service_ids": []

{
   "is_successful": false,
   "messages": {
      "alert": "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply.",
      "db_action": "Operation is not successful! Please try again."
   },
   "stat": "Please enter only valid service IDs!"
}

// Not existing "service_id" provided -> for example ""

{
   "is_successful": false,
   "messages": {
      "alert": "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply.",
      "db_action": "Operation is not successful! Please try again."
   },
   "stat": "Service ID 123123123123 is not existing!"
}

Service cannot be updated ( disabled already or pending activation / deactivation) - message depends on service status

{
   "is_successful": false,
   "messages": {
      "alert": "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply.",
      "db_action": "Service ID 26134 is already pending!"
   },
   "stat": "Service ID 26134 is already pending!"
}

{
   "is_successful": false,
   "messages": {
      "alert": "For some countries no verification is available for non-local currency bank accounts (i.e. UK accounts where the currency is different from GBP). In case you opt for such verification, TransferMate may not be able to verify the account. Still service charge may apply.",
      "db_action": "Service ID 26134 is disabled!"
   },
   "stat": "Service ID 26134 is disabled!"
}

POST Verify Beneficiary

Endpoint: /verify_beneficiary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`payee_name`	A unique payee name used to identify the beneficiary account. Only alphanumeric characters and spaces are allowed. TM will reject all special characters and replace with a space. All special characters will be replaced with a space.	Varchar	80	Yes	—
`country_code`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	3	Yes	—
`state`	The appropriate state in US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	50	Yes	—
`currency_type_id`	An ID from the list of currency IDs. See Currency Codes (ISO 4217) for more information.	Varchar	20	Yes	—
`payee_address`	The address of the payee. All details are included in one field. To seperate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It will accept _ / . &	Varchar	1000	Yes	—
`beneficiary_type_id`	The beneficiary type. Possible values are: - 3 for an individual client - 23 for a corporate client.	Integer	—	Yes	—
`account_number_type`	The account number type. The value must be account_number_1 or iban_3. If the value is iban_3, the transit_code_type and transit_code fields can be left blank.	Varchar	20	Yes	—
`account_number`	The IBAN code if known, otherwise the bank account number of the beneficiary.	Varchar	100	Yes	—
`transit_code_type`	The transit code type. This is a required field, but it can be left blank. See account_number_type description. See Transit Code Values for more information.	Varchar	&mdash	Yes	—
`transit_code`	A valid code which must match the type entered in the transit_code_type field.	Varchar	100	Yes	—
`swift`	The SWIFT code if known. This is a required field if the account_number_type field is iban_3. Otherwise it can be left blank. See the account_number_type description.	Varchar	11	Yes	—
`payee_city`	The name of the city where the payee resides.	Varchar	255	Yes	—
`payee_postal_code`	The postal code of the payee. This field is mandatory for the following countries: Australia, Canada, Mexico, Malaysia, New Zealand, Serbia, Sweden, The Philippines, UAE and USA.	Varchar	20	Conditional	—
`payee_phone_number_international_dialing_code`	The international dialing code of the country in which the payee resides. See Country Code for more information.	Varchar	80	Conditional	—
`payee_phone_number_mobile_phone`	The mobile phone contact number for the payee.	Varchar	80	Conditional	—
`bank_branch_address`	The address of the branch of the payee's bank. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. This field can be left blank. TM will reject majority special characters. It Will accept _ / . &	Varchar	1000	Conditional	—
`account_type`	The account type. For India, this field is mandatory. Possible values are: - resident_30 - Resident - non_resident_31 - Non-resident. For all other countries this can be left blank.	Varchar	10	Conditional	—
`for_further_credit_to`	The name of the final beneficiary if this is a 4th party payment. This is a compliance requirement. Only Alpha numeric values and spaces will be accepted. TM will reject majority special characters. It Will accept _ / . &.	Varchar	1000	Nо	—
`def_payment_reference`	Free text that represents the default reference for payments. TM will accept special characters !£$%^&*()_+-={}[]:;@'~#,./?	Varchar	250	Yes	—
`def_transfer_reason`	Default reason for payment. Can be left blank.	Integer	—	Yes	—
`def_transfer_reason_id`	Default reason for payment. See Transfer Reasons for more information.	Integer	—	Yes	—
`email`	A valid email address if the beneficiary to receive updates on transactions. (Required if payment is coming from California or the beneficiary is in California) TM will reject the majority of special characters. It will accept @. _ -.	Varchar	150	Conditional	—
`email_alert_flag`	1 for yes 0 for no	Bit	1	Yes	—
`payee_tax_id`	The beneficiary tax registration number. Only alphanumeric values will be accepted.	Varchar	20	No	—

Example Request

An example of the JSON structure in the request is as follows:

{
   "payee_name": "Test z341312312312x",
   "country_code": "US",
   "state": "US-FL",
   "currency_type_id": "USD",
   "payee_address": "testter",
   "beneficiary_type_id": "3",
   "account_number_type": "account_number_1",
   "account_number": "1000000003123123",
   "transit_code_type": "aba_number_5",
   "transit_code": "0260-0959-3",
   "swift": "",
   "payee_city": "New York",
   "payee_postal_code": "10001",
   "payee_phone_number_international_dialing_code": "us 1",
   "payee_phone_number_mobile_phone": "202-555-0192",
   "bank_branch_address": "",
   "account_type": "",
   "for_further_credit_to": "",
   "def_payment_reference": "Test payment",
   "def_transfer_reason": "",
   "def_transfer_reason_id": "7",
   "email": "test@test.com",
   "email_alert_flag": "0",
   "payee_tax_id": ""
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`code`	The name of the bank.	Varchar
`bank_name`	The name of the bank that manages the account.	Varchar
`bank_id`	The bank account ID.	Varchar
`unq_key`	The unique internal ID of the bank.	Varchar
`message`	A message phrase that provides information about the verification.	Varchar
`bene_verifier`	Verification result.	List

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "code": "1200",
   "bank_name": "NATIONAL WESTMINSTER BANK PLC",
   "bank_id": 20175,
   "unq_key": "BD0000001IT3",
   "message": "",
   "bene_verifier": {
      "response_code": 2000,
      "response_message": "ValidationSucceeded",
      "data": {
         "match_score": "1",
         "match_score_description": "Strong Match"
      }
   }
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`global_errors`	Global errors associated with the request.	List
`input_errors`	Input errors associated with the request.	List

{
   "is_successful": false,
   "messages": [],
   "global_errors": [],
   "input_errors": [
      {
         "ID": "transit_code_type",
         "description": "National Bank Code does not exist or the selected country does not provide National Bank Code!"
      }
   ]
}

Treasury Account Management

Treasury Account Management allows you to create, edit and view Global Bank Accounts.

Using the Payments API, you can:

Activate Virtual/Global Accounts(Scheduled for deprecation)
You can activate a virtual/global account of a given currency.

Activate Virtual/Global Accounts V2
You can activate a virtual/global account of a given currency.

View Global Bank Accounts
You can view a list of global accounts. You cannot recover or re-use an inactive account. Inactive accounts are removed from all live lists.

Edit Global Account Name
You can edit the name of a Global Account

View Global Account Details
You can view the details of a specified global account.

View Global Account Details V2
You can view the details of a specified global account.

View Existing Virtual Bank Account Details
You can retrieve the details of all existing virtual bank accounts.

View Virtual Account Details
You can view the details of a specified virtual account.

Global Account Summary
You can retrieve a report on all the active Global accounts and include a .csv and .xls export.

ASSIGNEE
You can view the details of a specified virtual account.
- Add assignee
  You can create and add the details of an assignee to global account.
- Assign assignee
  You can assign the added assignee to one or more global accounts.
- View assignee
  You can view all the assignees created under your profile.

POST Activate Virtual/Global Accounts(Scheduled for deprecation)

You can activate virtual and global accounts of a given currency by sending an HTTP POST request to the `/activate_virtual_global_account` endpoint.

Endpoint: /activate_virtual_global_account

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the account you wish to actiave.	Varchar	3	Yes	—
`type`	Specifies the type of account you want to activate. The options are either "global" or "virtual".	Varchar	—	No	—

Example Request

{
"currency": "EUR",
"type": "global"
}

Response Body Payload Example

If the activate virtual global account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`account_description`	Name of the Global Account.	Varchar
`ending_in`	Last four digits of the account number.	Varchar
`balance`	The balance available in the Global Acccount.	Varchar
`id`	ID of the Global Account.	Varchar
`user_bank_id`	User Bank ID of the Global Account.	Varchar
`benef_id`	ID of the beneficiary.	Varchar
`Info`	Type of the account.	List
`active`	The active status of the account.	Varchar
`supported_payments`	List of supported payment types.	Varchar
`wire`	Shows availability of Wire transfer.	Integer
`ach`	Shows availability of Automatic clearing house.	Integer
`alert`	Information relating to the terms and conditions.	Varchar

Example Success Response

{
"test - eur 3": {
"account_description": "Test - EUR 3",
"ending_in": "0041",
"balance": "0.00",
"id": "83541",
"user_bank_id": "149732",
"benef_id": "1151804",
"is_pending": "0",
"info": {
"type": "GA",
"active": "1",
"supported_payments": {
"wire": "1",
"ach": "1"
},
"bank_details": {
"global_account_holder": "Test",
"global_account_name": "Test - EUR 3",
"account_number": "T000000041",
"iban": "GB68BKEN10000000000041T",
"sort_code": "100000",
"bic_swift": "BKENGB33",
"bank_name": "JPMorgan Chase Bank, N. A.",
"bank_account_holder": "Interpay UK",
"bank_address": "JPMorgan Chase Bank, N.A., London Branch25 Bank StreetCanary WharfLondonE14 5JP"
}
}
},
"alert": "by continuing you confirm you accept the terms and conditions, https://www.transfermate.com/terms/"
}

Example Error Responses

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST Activate Virtual/Global Accounts V2

You can activate virtual and global accounts of a given currency by sending an HTTP POST request to the `/activate_virtual_global_account` endpoint.

Endpoint: /v2/activate_virtual_global_account

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the account you wish to activate.	Varchar	3	Yes	—
`type`	Specifies the type of account you want to activate. The options are either "global" or "virtual".	Varchar	—	Yes	—
`name`	The nickname of the Global account	Varchar	150	No	—
`tax_id`	The tax ID of the client. A-Z a-z 0-9 - _ &. :; , ' :space: ( )	Varchar	35	Only for currencies MXN and BRL	—
`website_address`	Client`s website	Varchar	150	Only for currencies MXN and BRL	—
`register_for_amazon`	accepts “1” for Yes and “0“ for No.	Bit	0	No	No

Example Request

{
"currency": "EUR",
"type": "global",
"name": "nickname of global account",
"tax_id": "65311",
"website": "",
"register_for_amazon": "1"
}

Response Body Payload Example

If the activate virtual global account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`account_description`	Name of the Global Account.	Varchar
`ending_in`	Last four digits of the account number.	Varchar
`balance`	The balance available in the Global Acccount.	Varchar
`id`	ID of the Global Account.	Varchar
`user_bank_id`	User Bank ID of the Global Account.	Varchar
`benef_id`	ID of the beneficiary.	Varchar
`is_pending`	Pending status of the beneficiary.	Varchar
`Is_default`	If default main GA for currency 1 for yes 0 for no.	Integer
`Info`	Type of the account.	List
`type`	Type of the account. GA or VA.	Varchar
`active`	The active status of the account.	Varchar
`supported_payments`	List of supported payment types.	Varchar
`wire`	Shows availability of Wire transfer.	Integer
`ach`	Shows availability of Automatic clearing house.	Integer
`Instant`	Shows availability of instant payment clearing.	Integer
`bank_details`	List of bank details of the Global Account.	List
`global_account_holder`	The name of the account under which the global account is held.	Varchar
`global_account_name`	Nickname of the global account.	Varchar
`account_number`	Account number – if applicable – of the global account.	Varchar
`iban`	Iban – if applicable – of the global account.	Varchar
`sort_code`	Sort Code – if applicable – of the global account.	Varchar
`bic_swift`	Bic/Swift of the global account.	Varchar
`bank_name`	The name of the bank in which the global account is created.	Varchar
`bank_account_holder`	The legal entity under which the global account is held.	Varchar
`bank_address`	Address of the bank where the account is held.	Varchar
`alert`	Information relating to the terms and conditions.	Varchar
`is_successful`	Status of the request.	Varchar
`messages`	List of messages associated with the response.	List
`success`	Any messages associated with this request.	Varchar

Example Success Response

{
"mathew": {
"account_description": "Nickname of GA",
"ending_in": "4886",
"balance": "0.00",
"id": 80386,
"user_bank_id": 374202,
"benef_id": 2812459,
"is_pending": 0,
"is_default": 0,
"info": {
"type": "GA",
"active": 1,
"supported_payments": {
"ach": 1,
"wire": 1,
"instant": 1
},
"bank_details": {
"global_account_holder": "test",
"global_account_name": "Nickname of GA",
"account_number": "T0014886",
"iban": "IE45IRCE99990100014886T",
"sort_code": "999901",
"bic_swift": "IRCEIE2D",
"bank_name": "J.P. MORGAN BANK (IRELAND) PLC",
"bank_account_holder": "Interpay",
"bank_address": "JPMORGAN HOUSE INTERNATIONAL FINANCIAL SERVICES CENTRE,\n\tDublin 1,\n\tIreland"
}
}
},
"alert": "By continuing, you confirm that you accept the Terms and Conditions. https://transfermate.io/en/terms.html",
"is_successful": true,
"messages": {
"success": "Action performed successfully."
}
}

Example Error Responses

If the activate virtual global account request is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST View Global Bank Accounts

You can get a list of global bank accounts with details by sending an HTTP POST request to the `/view_banks_global` endpoint.

**NOTE**: View Existing Global Bank Account Details does not have any input parameters.

Endpoint: /view_banks_global

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the account you wish to view.	Varchar	—	No	—

Example Request

{}

{
"currency": "EUR"
}

Response Body Payload Example

If the view bank account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`currency`	The currency of the account.	Varchar
`name`	Name name of the overarching account.	Varchar
`last_transaction`	List of details pertaining to the most recent transaction.	List
`id`	ID of the most recent transaction.	Varchar
`date`	Date of the most recent transaction.	Varchar
`name`	name of the bene pertaining to the most recent transaction.	Varchar
`amount`	The monetary value of the most recent transaction.	Varchar
`total_balance`	The total available funds in the account.	Varchar
`account_description`	Name of the Global Account.	Varchar
`ending_in`	Last four digits of the account number.	Varchar
`client_status`	Status of the client.	Varchar
`balance`	The balance available in the Global Acccount.	Varchar
`id`	ID of the Global Account.	Varchar
`user_bank_id`	User Bank ID of the Global Account.	Varchar
`benef_id`	ID of the beneficiary.	Varchar
`is_pending`	Pending status of the beneficiary.	Varchar
`Info`	List of information pertaining to the account.	List
`type`	Type of the account. GA or VA.	Varchar
`active`	The active status of the account.	Varchar
`supported_payments`	List of supported payment types.	Varchar
`wire`	Shows availability of Wire transfer.	Integer
`ach`	Shows availability of Automatic clearing house.	Integer
`bank_details`	List of bank details of the Global Account.	List
`global_account_holder`	The name of the account under which the global account is held.	Varchar
`global_account_name`	Nickname of the global account.	Varchar
`acccount_number`	Number of the account.	Varchar
`iban`	Iban – if applicable – of the global account.	Varchar
`bank_name`	The name of the bank in which the global account is created.	Varchar
`bank_account_holder`	The legal entity under which the global account is held.	Varchar
`bank_address`	Address of the bank where the account is held.	Varchar

Example Success Response

{
"EUR": {
"currency": "EUR",
"name": "Euro",
"last_transaction": {
"id": "3809917",
"date": "2022-05-11 14:03:12",
"name": "test",
"amount": "-1.00"
},
"total_balance": "5.30",
"148877": {
"account_description": "Test - EUR 20",
"ending_in": "4082",
"client_status": "",
"last_transaction": "",
"balance": "0.00",
"id": "79582",
"user_bank_id": "148877",
"benef_id": "1151132",
"is_pending": "0",
"info": {
"type": "GA",
"active": "1",
"supported_payments": {
"wire": "1",
"ach": "1"
},
"bank_details": {
"global_account_holder": "Test",
"global_account_name": "Test - EUR 20",
"account_number": "T0014082",
"iban": "IE25IRCE99990100014082T",
"sort_code": "999901",
"bic_swift": "IRCEIE2D",
"bank_name": "J.P. MORGAN BANK (IRELAND) PLC",
"bank_account_holder": "Interpay",
"bank_address": "JPMORGAN HOUSE INTERNATIONAL FINANCIAL SERVICES CENTRE,Dublin 1,Ireland"
}
}
},
"148876": {
"account_description": "Test - EUR 19",
"ending_in": "4081",
"client_status": "",
"last_transaction": "",
"balance": "0.00",
"id": "79581",
"user_bank_id": "148876",
"benef_id": "1151131",
"is_pending": "0",
"info": {
"type": "GA",
"active": "1",
"supported_payments": {
"wire": "1",
"ach": "1"
},
"bank_details": {
"global_account_holder": "Test",
"global_account_name": "Test - EUR 19",
"account_number": "T0014081",
"iban": "IE25IRCE99990100014082T",
"sort_code": "999901",
"bic_swift": "IRCEIE2D",
"bank_name": "J.P. MORGAN BANK (IRELAND) PLC",
"bank_account_holder": "Interpay",
"bank_address": "JPMORGAN HOUSE INTERNATIONAL FINANCIAL SERVICES CENTRE,Dublin 1,Ireland"
}
}
}
}
}

{
"currency": "EUR",
"name": "Euro",
"last_transaction": {
"id": "3809917",
"date": "2022-05-11 14:03:12",
"name": "test",
"amount": "-1.00"
},
"total_balance": "5.30",
"148877": {
"account_description": "Test - EUR 20",
"ending_in": "4082",
"client_status": "",
"last_transaction": "",
"balance": "0.00",
"id": "79582",
"user_bank_id": "148877",
"benef_id": "1151132",
"is_pending": "0",
"info": {
"type": "GA",
"active": "1",
"supported_payments": {
"wire": "1",
"ach": "1"
},
"bank_details": {
"global_account_holder": "Test",
"global_account_name": "Test - EUR 20",
"account_number": "T0014082",
"iban": "IE25IRCE99990100014082T",
"sort_code": "999901",
"bic_swift": "IRCEIE2D",
"bank_name": "J.P. MORGAN BANK (IRELAND) PLC",
"bank_account_holder": "Interpay",
"bank_address": "JPMORGAN HOUSE INTERNATIONAL FINANCIAL SERVICES CENTRE,Dublin 1,Ireland"
}
}
}
}

Example Error Responses

If the add bank request is not successful, the service responds with an error code, rejects the request, and does not create the bank account. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST View Global Bank Accounts V2

You can get a list of global bank accounts with details by sending an HTTP POST request to the `/v2/view_banks_global` endpoint.

Endpoint: /v2/view_banks_global

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the global bank account.	Varchar	-	No	-
`user_bank_id`	The standard five digit bank account ID that the user may access the virtual bank account by.	Varchar	-	No	-
`assignee_id`	ID of the existing assignee that could be attached to the global bank account.	Integer	-	No	-
`assignee_reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-".	Varchar	-	No	-
`global_account_name`	Nickname of the global account.	Varchar	-	No	-
`id`	ID of the Virtual Account.	Integer	-	No	-

Example Request

An example of the JSON structure in the request is as follows:

{
   "currency": "MXN",
   "user_bank_id": 123,
   "assignee_id": "123",
   "assignee_reconciliation_id": "123",
   "global_account_name": "Name Filter",
   "id": 123
}

Response Body Payload Example

If the request is successful, the response includes the following parameters:

Field	Description	Type
`is_successful`	This is either true of false.	Varchar
`messages`	List of messages associated with the response.	List
`page`	The current page numbe	Integer
`pages_count`	Total amount of pages.	Integer
`records_per_page`	Amount of transaction records per page.	Integer
`total_records`	Total records in the Quote Batch.	Integer
`accounts`	The list of global accounts.	List
`currency`	The currency of the global bank account.	Varchar
`currency_active`	Does currency active.	Varchar
`balance`	The balance available in the Global Acccount.	Varchar
`global_account_holder`	The name of the account under which the global account is held.	Varchar
`vrn`
`ach_aba_number`
`wire_aba_number`
`ending_in`	Last four digits of the account number.	Varchar
`client_name`
`client_status`	Status of the client.	Varchar
`id`	ID of the Global Account.	Varchar
`currency_full_text`
`user_bank_id`	User Bank ID of the Global Account.	Varchar
`auto_withdrawal`		Varchar
`active_sweeps`		List
`is_addressable`		Varchar
`benef_id`	ID of the beneficiary.	Varchar
`local_bank`		Varchar
`is_local`		Varchar
`account_number`	Account number – if applicable – of the global account.	Varchar
`iban`	Iban – if applicable – of the global account.	Varchar
`swift_bic`	Bic/Swift of the global account.	Varchar
`sepa_instant_swift`
`active`	The active status of the account.	Varchar
`active`	The bank and branch code of the bank.	Varchar
`bank_and_branch_code`	The bank and branch code of the bank.	Varchar
`branch_code`	The branch code of the bank.	Varchar
`hkd_branch_code_under_title`		Varchar
`wire_aba_code`		Varchar
`ach_aba_code`
`bsb`	The bank’s BSB number.	Varchar
`is_default`	If default main GA for currency 1 for yes 0 for no.	Integer
`is_blocked`		Varchar
`is_pending`		Varchar
`supported_payments_flags`	List of supported payment types.	Varchar
`bank_name`	The name of the bank in which the global account is created.	Varchar
`bank_address`	Address of the bank where the account is held.	Varchar
`bank_account_holder`	The legal entity under which the global account is held.	Varchar
`last_tr_id`
`last_tr_date`
`last_tr_name`
`last_tr_amount`
`latest_account_activity`
`correspondent_bank`
`correspondent_swift_bic`
`correspondent_iban`
`correspondent_account_number`
`correspondent_kbe_code`
`correspondent_bin`
`provider_id`		Varchar
`ga_assignee_enabled`
`ga_assignee_id`		Integer
`ga_assignee_is_blocked`		Integer
`ga_assignee_consent`	Does the assignee give consent to have a GA assigned to themselves: 1 for Yes, 0 for No	Boolean
`ga_assignee_name`	The name of the assignee (company name if assignee is type: corporate, else individual’s name)	Varchar
`ga_assignee_reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-".	Varchar
`ga_assignee_address`	The address of the assignee. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It Will accept _ / . &.	Varchar
`register_for_amazon`	Register for Amazon.	Bit
`ga_assignee_alert`	Alert message	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "messages": {
      "success": "Action performed successfully."
   },
   "page": 1,
   "pages_count": 1,
   "records_per_page": 100,
   "total_records": 1,
   "accounts": [
      {
         "currency": "MXN",
         "currency_active": "1",
         "global_account_name": "Test - MXN",
         "balance": "0.00",
         "global_account_holder": "Test",
         "vrn": "",
         "ach_aba_number": "",
         "wire_aba_number": "",
         "ending_in": "",
         "client_name": "",
         "client_status": "",
         "id": "157107",
         "currency_full_text": "Mexico Pesos",
         "user_bank_id": "",
         "auto_withdrawal": "0",
         "active_sweeps": [],
         "is_addressable": "1",
         "benef_id": "",
         "local_bank": "1",
         "is_local": "1",
         "account_number": "",
         "iban": "",
         "swift_bic": "",
         "sepa_instant_swift": "",
         "active": "1",
         "bank_and_branch_code": "",
         "branch_code": "",
         "hkd_branch_code_under_title": "",
         "wire_aba_code": "",
         "ach_aba_code": "",
         "bsb": "",
         "is_default": "0",
         "is_blocked": "0",
         "is_pending": "1",
         "supported_payments_flags": "{\"ach\": 0, \"spei\": 1, \"wire\": 0, \"ach_tm\": 0, \"instant\": 0, \"wire_tm\": 0, \"instant_tm\": 0}",
         "bank_name": "",
         "bank_address": "",
         "bank_account_holder": "",
         "last_tr_id": "",
         "last_tr_date": "",
         "last_tr_name": "TransferMate",
         "last_tr_amount": "",
         "latest_account_activity": "",
         "correspondent_bank": "",
         "correspondent_swift_bic": "",
         "correspondent_iban": "",
         "correspondent_account_number": "",
         "correspondent_kbe_code": "",
         "correspondent_bin": "",
         "provider_id": "3",
         "ga_assignee_enabled": "0",
         "ga_assignee_id": "",
         "ga_assignee_is_blocked": "",
         "ga_assignee_consent": "",
         "ga_assignee_name": "",
         "ga_assignee_reconciliation_id": "",
         "ga_assignee_address": "",
         "register_for_amazon": "0",
         "ga_assignee_alert": "MXN GAs cannot be Assigned after activation. If you need an MXN GA for an Assignee you need to activate one specifically for them",
         "type": "GA"
      }
   ]
}

POST View Global Account Details

You can retrieve withdrawals and deposits from a global account by sending an HTTP POST request to the `/view_global_account_details` endpoint. Recommend to use a date range (Max of 7 days).

Endpoint: /view_global_account_details

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id`	Id of the account you want to view.	Integer	—	Yes	1
`date_from`	Specifies the start date of the period for which you want to retrieve account details. The parameter is optional. The format must be dd/mm/yyyy.	Date	—	No	1
`date_to`	Specifies the end date of the period for which you want to retrieve account details. The parameter is optional. If unspecified, the end date is the current date. The format must be dd/mm/yyyy.	Date	—	No	—
`items_per_page`	Number of items returned per page 10/20/30/null. If "null" is used, the API will return all transactions for the given date range.	Integer	—	No	1
`page_no`	Pagination Set to 1 to call page 1, set to 2 to call page 2 etc. Defaults to 1 if not provided.	Integer	—	No	1

Example Request

{
"id": 135066,
"date_from": "01/01/2022",
"date_to": "07/01/2022"
}

Response Body Payload Example

If the view global account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`global_account`	Currency of the account.	Varchar
`trans_status`	Status of the transactrion.	Varchar
`beneficiary`	Name of Beneficiary of the transaction.	Varchar
`payer`	Name of the account that paid the transaction.	Varchar
`date`	Date at which the transaction was paid.	Varchar
`amount`	The value of the transaction. Note the Postive value is a deposit, negative is withdrawl.	Varchar
`reference`	Reference to payment provided by the user when transaction was booked.	Varchar
`payer_swift`	The swift code of the payer.	Varchar
`payer_iban`	The iban of the payer.	Varchar
`payer_transit_code`	The transit code of the payer.	Varchar
`running_balance`	The current available balance of the virtual account.	Varchar

Example Success Response

[
{
"date_paid": "2023-01-05",
"date_no_time": "2023-01-05",
"beneficiary": "TEST GA",
"payer": "Test Payer",
"ultimate_debtor": "-",
"transaction_type": "Convert",
"web_transaction_id": "T6999520",
"description": "Converted at a rate of 1 USD = 1 USD",
"fee": "0.00",
"credit": "+50.00 USD",
"status": "Paid",
"running_balance": "2625.00",
"payer_swift": "Cxx-xxxx-xx33",
"payer_iban": "Txx-xxxx-0039",
"payer_transit_code": "0xx-xxxx-xx24"
}
]

Example Error Responses

If the view global bank account details request is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST View Global Account Details V2

You can retrieve withdrawals  and deposits from a global account by sending an HTTP POST request to the `/v2/view_global_account_details` endpoint. Recommend to use a date range (Max of 7 days)

Endpoint: /v2/view_global_account_details

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id`	Id of the account you want to view.	Integer	—	Yes	1
`date_from`	Specifies the start date of the period for which you want to retrieve account details. The parameter is optional. The format must be dd/mm/yyyy.	Date	—	No	1
`date_to`	Specifies the end date of the period for which you want to retrieve account details. The parameter is optional. If unspecified, the end date is the current date. The format must be dd/mm/yyyy.	Date	—	No	—
`items_per_page`	Number of items returned per page 10/20/50/100. Default is 10	Integer	—	No	10
`p_number`	Pagination Set to 1 to call page 1, set to 2 to call page 2 etc. Defaults to 1 if not provided.	Integer	—	No	1
`transaction_id`	Specify the transaction (T) number to filter transactions associated with that T number. Contains a T by at least 6 digits.	Varchar	20	No	—

Example Request

{
"user_bank_id": 191879,
"transaction_id": "T8193161",
"date_from": "10/10/2023",
"date_to": "10/03/2024",
"items_per_page": "10",
"p_number": "1"
}

Response Body Payload Example

If the view global account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`Date_paid`	Date at which the transaction was paid	Date
`date_no_time`	Date at which the transaction was submitted/approved?	Date
`date_time`	DDate and time at which the transaction was submitted/approved?	Date
`web_transaction_id`	DThe reference / transaction number of a payment.	Varchar
`transaction_id`	DThe reference / transaction number of a payment.	Varchar
`beneficiary`	Name of Beneficiary of the transaction.	Varchar
`payer`	Name of the account that paid the transaction.	Varchar
`ultimate_debtor`	The name of the ultimate debtor.	Varchar
`transaction_type`	The type of transaction processed – Convert or null.	Varchar
`transaction_direction`	The type of transaction processed – Convert or null.
`reference`	Reference to payment provided by the user when transaction was booked.	Varchar
`reference`	Reason of transfer with exchange rate of the payment.	Varchar
`fee`	The fee for the payment transaction.	Decimal
`debit`	The debit amount withdrawn from global account with currency units.	Varchar
`credit`	The credit amount deposited into global account with currency units.	Varchar
`status`	The status of the transaction – pending/paid/cancelled/rejected	Varchar
`running_balance`	The current available balance of the global account.	Decimal or varchar
`payer_account_number`	The bank account number of the Payer.	Varchar
`payer_bank_and_branch_code`	The bank and branch code of the payer bank.	Varchar
`payer_swift`	The SWIFT code of the payer.	Varchar
`payer_bic`	The SWIFT BIC code of the Payer bank.	Varchar
`payer_sort_code`	The sort code of the Payer bank.	Varchar
`payer_aba_number`	The Payer bank’s ABA routing number.	Varchar
`payer_bsb`	The Payer bank’s BSB number.	Varchar
`payer_iban`	The IBAN of the payer.	Varchar
`payer_transit_code`	The Payer bank’s transit code.	Varchar
`payer_bank_address`	The Payer bank – bank address.	Varchar

Example Success Response

{
"is_successful": true,
"messages": {
"success": "Action performed successfully."
},
"csv_export_url": "https://sandbox-payments-api.tmatedev.net/reports?exp=plugins/globalaccounts/globalaccountsdetailsapp&tp=csv&dummy=20240322112015",
"xls_export_url": "https://sandbox-payments-api.tmatedev.net/reports?exp=plugins/globalaccounts/globalaccountsdetailsapp&tp=excel&dummy=20240322112015",
"data": [
{
"date_paid": "",
"date_no_time": "2024-01-25",
"date_time": "2024-01-25 13:34:53.876528",
"web_transaction_id": "T8193161",
"transaction_id": "T8193161",
"beneficiary": "Ireland Company Abc",
"payer": "USD GA for Payroll payments",
"ultimate_debtor": "-",
"transaction_type": "",
"transaction_direction": "",
"reference": "Test transfer USD to EUR",
"description": "Bill payment at a rate of 1 USD = 0.91604 EUR",
"fee": "1.75",
"debit": "-1093.41 USD",
"credit": "",
"status": "Pending",
"running_balance": "16639.17",
"payer_account_number": "",
"payer_bank_and_branch_code": "",
"payer_swift": "Cxx-xxxx-xx33",
"payer_bic": "",
"payer_sort_code": "",
"payer_aba_number": "",
"payer_bsb": "",
"payer_iban": "Txx-xxxx-0233",
"payer_transit_code": "0xx-xxxx-xx24",
"payer_bank_branch_code": "",
"payer_bank_address": ""
}
]
}

Example Error Responses

If the view global bank account details request is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 400 - No data

{
"is_successful": true,
"messages": {
"data": "No data found."
},
"data": {}
}

POST Edit Global Account Name

You can edit the name of a global/virtual account by sending an HTTP POST request to the `/edit_global_account_name` endpoint.

Endpoint: /edit_global_account_name

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`name`	Name the account will be changed too.	Varchar	—	Yes	1
`user_bank_id`	User bank if of the account you want to edit.	Integer	—	Yes	1
`type`	The type of account that is being edited. global/virtual.	String	—	Only for virtual accounts	global

Example Request

{
"name": "GA updated name",
"user_bank_id": 149477
}

{
"name": "VA updated name",
"user_bank_id": 149478,
"type": "virtual"
}

Response Body Payload Example

If the view global account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	Update successful.	Varchar

Example Success Response

{
"stat": "Update successful"
}

Example Error Responses

If the view global bank account details request is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 422 - Unprocessable Entity

{
"stat": "This Account Description is already in use, please choose a different one"
}

POST View Existing Virtual Bank Account Details

You can get a list of virtual bank accounts with details by sending an HTTP POST request to the /view_banks_virtual endpoint.

Please Note that while you may view virtual bank accounts through the API you cannot create them and must contact your sales representative to have one attached to your account.

NOTE: View Existing Virtual Bank Account Details does not have any input parameters.

Endpoint: /view_banks_virtual

Request Body Payload Example

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the virtual bank account.	Varchar	-	No	-
`user_bank_id`	The standard five digit bank account ID that the user may access the virtual bank account by.	Varchar	-	No	-
`assignee_id`	ID of the existing assignee that could be attached to the virtual bank account.	Integer	-	No	-
`assignee_reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-"	Varchar	-	No	-
`global_account_name`	Nickname of the global account.	Varchar	-	No	-
`id`	ID of the Virtual Account.	Integer	-	No	-

Example Request

{
"currency": "USD",
"user_bank_id": 413,
"assignee_id": "123",
"assignee_reconciliation_id": "123",
"global_account_name": "Name Filter",
"id": "444"
}

Response Body Payload Example

If the view bank account details request is successful, the service returns a response.,The response contains a list of bank details for each bank.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`uid`	The internal unique ID of the bank, for example 49665.	Integer
`actions`	Not yet implemented.	Varchar
`action`	Not yet implemented.	Varchar
`virtual_account_name`	The name of the virtual bank account.	Varchar
`currency`	The currency of the virtual bank account.	Varchar
`availability`	The amount of available currency, which can be accessed by the user, held in the virtual account.	Varchar
`blocked_amount`	The amount of currency which is still in a pending transaction and has not cleared from the account yet.	Varchar
`full_amount`	The total amount of currency held in the virtual account.	Varchar
`user_bank_id`	The standard five digit bank account ID that the user may access the virtual bank account by.	Varchar

Example Success Response

The request body includes the following parameters:

[
{
"uid": 2291,
       "actions": " ",
       "action": " ",
       "virtual_account_name": "Test - USD",
       "currency": "USD",
       "availability": "923.88",
       "blocked_amount": "76.12",
       "full_amount": "1000",
       "user_bank_id": "83683"
   }
]

Example Error Responses

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST View Virtual Account Details

You can retrieve withdrawls and deposits from a virtual account by sending an HTTP POST request to the `/view_virtual_account_details` endpoint. Recommend to use a date range (Max of 7 days)

Endpoint: /view_virtual_account_details

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id`	Id of the account you want to view.	Integer	—	Yes	1
`date_from`	Specifies the start date of the period for which you want to retrieve account details. The parameter is optional. The format must be dd-mm-yyyy.	Date	—	No	—
`date_to`	Specifies the end date of the period for which you want to retrieve account details. The parameter is optional. If unspecified, the end date is the current date. The format must be dd-mm-yyyy.	Date	—	No	—
`items_per_page`	Number of items returned per page.	Integer	—	No	1
`page_no`	Pagination Set to 1 to call page 1, set to 2 to call page 2 etc. Defaults to 1 if not provided.	Integer	—	No	1

Example Request

{
"id": 99470,
"date_from": "01/01/2022",
"date_to": "07/01/2022"
}

Response Body Payload Example

If the view virtual account details request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`beneficiary`	Name of Beneficiary of the transaction.	Varchar
`payer`	Name of the account that paid the transaction.	Varchar
`date_paid`	Date at which the transaction was paid.	Varchar
`amount`	The value of the transaction.	Varchar
`reference`	Reference to payment provided by the user when transaction was booked.	Varchar
`credit`	Amount added to account.	Varchar
`debit`	Amount taken from account.	Varchar
`transaction_type`	The type of transaction i.e Wire transfer, Reverse Wire, or Direct Debit.	Varchar
`running_balance`	The current available balance of the virtual account.	Varchar

Example Success Response

[
   {
"date_paid": "2022-03-02",
"beneficiary": "Test",
"payer": "Test",
"transaction_type": "Convert",
"description": "Converted at a rate of 1 EUR = 1 EUR",
"fee": "0.00",
"debit": "-10.00 EUR",
"status": "Paid",
"running_balance": "493681.62"
   },
   {
"date_paid": "2020-07-10",
"beneficiary": "TransferMate",
"description": "Bill payment",
"fee": "0.00",
"credit": "+500000 EUR",
"status": "Paid",
"running_balance": "500000"
}
]

Example Error Responses

If the view existing virtual account details request is not successful, the service responds with an error code, rejects the request, and does not create the bank account. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

POST Register for Amazon

Clients will use the new endpoint when they wish to register or remove the registration of a Global account for Amazon

Endpoint: /v2/register_for_amazon

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id`	User bank ID of the global account	Integer	—	Yes	—
`register_for_amazon`	Acepts: 1 for Yes (not registered) 0 for No	Bit	—	Yes	—

Example Request

An example of the JSON structure in the request is as follows:

{
"user_bank_id": 1234,
"register_for_amazon": 0
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`alert`	Register for Amazon alert.	Date
`is_successful`	True or false.	Varchar
`register_for_amazon`	Register for Amazon.	Bit

Response Body Payload Example

{
   "alert": "By continuing, I confirm I wish to use this global account for the purposes of receiving funds due to me from Amazon (and its affiliates). I understand that in order to receive these funds, TransferMate is required to send this confirmation to Amazon.",
   "is_successful": true,
   "register_for_amazon": 1
}

Example Error Responses

Error Code 422 - Unprocessable Entity

{
"is_successful": false,
"stat": "Please provide valid user_bank_id"
}

{
"is_successful": false,
"stat": "Invalid value for register_for_amazon"
}

POST Global Account Summary

This new endpoint will allow partners to retrieve a report on all active Global accounts.This response will be in JSON but also allow a .csv and .xls export. Please note that when requesting the either the .csv or .xls report, you are required to use the same session.

Endpoint: /global_accounts_summary

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id`	User bank ID of the global account	Integer	—	Yes	—
`register_for_amazon`	Acepts: 1 for Yes (not registered) 0 for No	Bit	—	Yes	—

Example Request

An example of the JSON structure in the request is as follows:

{
"date_time_from": "13/12/2023 00:00:00",
  "date_time_to": "13/12/2023 23:29:59",
  "type": "ga",
  "items_per_page": 50,
  "p_number": 1
}

Response Body Payload Example

If the global accounts summary request is successful, the service returns a response. Point to remember -While making call to get .csv or .xls reports, you will need to call the url provided in the response and use the correct bearer token.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`date_no_time`	Date at which the transaction was submitted	Date
`date_time`	Date and time at which the transaction was submitted	Date
`ref_number`	The reference / transaction number of a payment.	Varchar
`account_description`	Name of the Global Account.	Varchar
`transaction_id`	The reference / transaction number of a payment.	Varchar
`account_number`	Number of the account.	Varchar
`currency_type_id`	The currency of the account	Varchar
`beneficiary`	Name of Beneficiary of the transaction	Varchar
`payer`	Name of the account that paid the transaction	Varchar
`ultimate_debtor`	The name of the ultimate debtor.	Varchar
`transaction_type`	The type of transaction processed – Convert or null	Varchar
`transaction_direction`	It’s always empty in the response	Varchar
`reference`	Reference to payment provided by the user when the transaction was booked	Varchar
`description`	Reason of transfer with exchange rate of the payment	Varchar
`fee`	The fee for the payment transaction.	Decimal
`debit`	The debit amount withdrawn from global account with currency units	Varchar
`credit`	The credit amount deposited into global account with currency units	Varchar
`status`	The status of the transaction – pending/paid/cancelled/rejected	Varchar
`batch_ref_number`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`user_bank_id`	The Id of the global/virtual account.	Integer

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "is_successful": true,
      "messages": {
          "success": "Action performed successfully."
      },
      "page": 1,
      "pages_count": 8,
      "records_per_page": 10,
      "total_records": 75,
      "csv_export_url": "https://uat-payments-api.transfermate.com/reports?exp=plugins/globalaccounts/globalaccountsdetailsallapp&tp=csv&dummy=20231220161229",
      "xls_export_url": "https://uat-payments-api.transfermate.com/reports?exp=plugins/globalaccounts/globalaccountsdetailsallapp&tp=excel&dummy=20231220161229",
      "data": [
{
           "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:17:19.69855",
              "ref_number": "T7621259",
              "account_description": "Company ABC",
              "transaction_id": "T7621259",
              "account_number": "00000000099",
              "currency_type_id": "SGD",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43812 SGD",
              "fee": "0.00",
              "debit": "",
              "credit": "+12656.89 SGD",
              "status": "Paid",
              "batch_ref_number": "B1786864",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:17:19.69855",
              "ref_number": "T7621259",
              "account_description": "EUR Main",
              "transaction_id": "T7621259",
              "account_number": "IE19IRCE99990100014093",
              "currency_type_id": "EUR",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43812 SGD",
              "fee": "0.00",
              "debit": "-8801.00 EUR",
              "credit": "",
              "status": "Paid",
              "batch_ref_number": "B1786864",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:54.74979",
              "ref_number": "T7621258",
              "account_description": "Company ABC",
              "transaction_id": "T7621258",
              "account_number": "00000000099",
              "currency_type_id": "SGD",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "",
              "credit": "+12656.45 SGD",
              "status": "Paid",
              "batch_ref_number": "B1786863",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:54.74979",
              "ref_number": "T7621258",
              "account_description": "EUR Main",
              "transaction_id": "T7621258",
              "account_number": "IE19IRCE99990100014093",
              "currency_type_id": "EUR",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "-8801.00 EUR",
              "credit": "",
              "status": "Paid",
              "batch_ref_number": "B1786863",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:44.648769",
              "ref_number": "T7621257",
              "account_description": "Company ABC",
              "transaction_id": "T7621257",
              "account_number": "00000000099",
              "currency_type_id": "SGD",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "",
              "credit": "+12770.06 SGD",
              "status": "Paid",
              "batch_ref_number": "B1786862",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:44.648769",
              "ref_number": "T7621257",
              "account_description": "EUR Main",
              "transaction_id": "T7621257",
              "account_number": "IE19IRCE99990100014093",
              "currency_type_id": "EUR",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "-8880.00 EUR",
              "credit": "",
              "status": "Paid",
              "batch_ref_number": "B1786862",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:38.162841",
              "ref_number": "T7621256",
              "account_description": "Company ABC",
              "transaction_id": "T7621256",
              "account_number": "00000000099",
              "currency_type_id": "SGD",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "",
              "credit": "+2703.57 SGD",
              "status": "Paid",
              "batch_ref_number": "B1786861",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:38.162841",
              "ref_number": "T7621256",
              "account_description": "EUR Main",
              "transaction_id": "T7621256",
              "account_number": "IE19IRCE99990100014093",
              "currency_type_id": "EUR",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "-1880.00 EUR",
              "credit": "",
              "status": "Paid",
              "batch_ref_number": "B1786861",
              "user_bank_id": "152220"
  },
  {
              "date_no_time": "2023-12-13",
              "date_time": "2023-12-13 10:16:17.817418",
              "ref_number": "T7621255",
              "account_description": "Company ABC",
              "transaction_id": "T7621255",
              "account_number": "00000000099",
              "currency_type_id": "SGD",
              "beneficiary": "Company ABC",
              "payer": "EUR Main",
              "ultimate_debtor": "-",
              "transaction_type": "Convert",
              "transaction_direction": "",
              "reference": "",
              "description": "Converted at a rate of 1 EUR = 1.43807 SGD",
              "fee": "0.00",
              "debit": "",
              "credit": "+143",
              "status": "paid",
              "batch_ref_number": "B1786860",
              "user_bank_id": "152220"
          }
      ]
}
]

Example Error Responses

If the global account summary request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 400 - No data

{
"is_successful": false,
  "messages": {
      "items_per_page": "Please enter correct information!",
      "data": "No data found."
  },
  "data": {}
}

POST Add Assignee

You can add (create) details of an assignee (client) to global account under a Partner by sending a HTTPS POST request to the /add_assignee endpoint.

Endpoint: /add_assignee

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`assignee_name`	The name of the assignee (company name if assignee is type: corporate, else individual’s name)	Varchar	—	Yes	—
`assignee_type`	The type of the assignee: 1 for Corporate/Company, 2 for Individual	Integer	—	Yes	Yes
`assignee_reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-"	Varchar	—	Yes	—
`assignee_country_iso`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	—	Yes	—
`assignee_country_iso`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	—	Yes	—
`assignee_state_iso`	The appropriate state in US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	—	No	—
`assignee_city`	The name of the city where the assignee resides.	Varchar	—	Yes	—
`assignee_zip_postcode`	The postal code of the assignee.	Varchar	—	Yes	—
`assignee_address`	The address of the assignee. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It Will accept _ / . &	Varchar	—	Yes	—
`assignee_date_incorporation`	The date of assignee’s incorporation	Date	—	No	—
`assignee_taxid`	The assignee’s tax registration number. Only Alpha numeric values will be accepted. TM will reject all special characters.	Varchar	—	No	—
`assignee_website`	The assignee’s tax registration number. Only Alpha numeric values will be accepted. TM will reject all special characters.	Varchar	—	No	—
`assignee_client_consent`	Does the assignee give consent to have a GA assigned to themselves: 1 for Yes, 0 for No	Boolean	—	No	0 (False)
`ultimate_debtor_id`	The ultimate debtor or third-party id associated with the assignee.	Integer	—	—	—
`beneficial_owners`	This object is required if the assignee is a company. Details of at least one beneficial owner is provided.	Object	—	Yes	—
`assignee_beneficial_owner_first_name`	First name of the assignee’s beneficial owner	Varchar	—	Yes	—
`assignee_beneficial_owner_middle_name`	Middle name of the assignee’s beneficial owner	Varchar	—	No	—
`assignee_beneficial_owner_last_name`	Last name of the assignee’s beneficial owner	Varchar	—	Yes	—
`assignee_beneficial_owner_country_iso`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information	Varchar	—	Yes	—
`assignee_beneficial_owner_state_iso`	The appropriate state in US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	—	No	—
`assignee_beneficial_owner_city`	The name of the city where the assignee’s beneficial owner resides.	Varchar	—	Yes	—
`assignee_beneficial_owner_zip_postcode`	The postal code of the assignee’s beneficial owner.	Varchar	—	Yes	—
`assignee_beneficial_owner_address`	The address of the assignee’s beneficial owner. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It will accept _ / . &	Varchar	—	Yes	—
`assignee_beneficial_owner_date_birth`	The beneficial owner’s date of birth	Date	—	No	—
`assignee_beneficial_owner_tax_id`	The tax id of the beneficial owner	Varchar	—	No	—

Example Request

An example of the JSON structure in the request is as follows:

{
"assignee_name": "Client AB",
  "assignee_type": 1,
  "assignee_reconciliation_id": "client_id_AB-1",
  "assignee_country_iso": "IE",
  "assignee_state_iso": "",
  "assignee_city": "Test city",
  "assignee_zip_postcode": "1000",
  "assignee_address": "test address",
  "assignee_date_incorporation": null,
  "assignee_taxid": "abbuuua77674uha",
  "assignee_website": null,
  "assignee_client_consent": null,
  "ultimate_debtor_id": null,
  "beneficial_owners": [
      {
          "assignee_beneficial_owner_first_name": "John",
          "assignee_beneficial_owner_middle_name": null,
          "assignee_beneficial_owner_last_name": "Smith",
          "assignee_beneficial_owner_country_iso": "CA",
          "assignee_beneficial_owner_state_iso": "CA-AB",
          "assignee_beneficial_owner_city": "City test",
          "assignee_beneficial_owner_zip_postcode": "8000",
          "assignee_beneficial_owner_address": "test address",
          "assignee_beneficial_owner_date_birth": "27/02/1993",
          "assignee_beneficial_owner_tax_id": null
      },
      {
          "assignee_beneficial_owner_first_name": "Ivan",
          "assignee_beneficial_owner_middle_name": null,
          "assignee_beneficial_owner_last_name": "Smith",
          "assignee_beneficial_owner_country_iso": "BG",
          "assignee_beneficial_owner_state_iso": null,
          "assignee_beneficial_owner_city": "City test",
          "assignee_beneficial_owner_zip_postcode": "8000",
          "assignee_beneficial_owner_address": "test address",
          "assignee_beneficial_owner_date_birth": "11/05/1990",
          "assignee_beneficial_owner_tax_id": null
      }
]
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`assignee`	Unique id of the global account assignee created	Integer

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "is_successful": true,
      "messages": {
      "success": "Action performed successfully."
  },
  "ga_assignee_id": 159
  }
]

Example Error Responses

If the convert request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - No data

{
"is_successful": false,
  "messages": {
      "assignee_reconciliation_id": "The reconciliation ID is already used by another assignee!"
  }
}

Error Code 200 - OK

{
"is_successful": false,
  "messages": {
      "assignee_reconciliation_id": "The reconciliation ID is already used by another assignee!"
  }
}

Error Code 200 - OK

{
"is_successful": false,
  "messages": {
      "assignee_name": "Please enter correct information!"
  }
}

Error Code 200 - OK

{
"is_successful": false,
  "messages": {
      "assignee_country": "Please enter correct information!",
      "assignee_city": "Please enter correct information!",
      "assignee_zip_postcode": "Please enter correct information!",
      "assignee_address": "Please enter correct information!"
  }
}

Add Assignee GA

Endpoint: /add_assignee_ga

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency`	The currency of the account you wish to actiave.	Varchar	3	Yes	—
`name`	The nickname of the global account.	Varchar, A-Z a-z 0-9 - _ & . : ; , ' :space: ( )	35	No	—
`tax_id`	The tax ID of the client	Varchar	35	Only for currency=MXN and BRL
`website`	Address of the client's website	Varchar	150	Only for currency=MXN and BRL	—
`assignee_id`	ID of the existing assignee that could be attached to the GA.	Integer	6	No	—
`register_for_amazon`	accepts “1” for Yes and “0“ for No.	Bit	—	No	—
`assignee_name`	The name of the assignee (company name if assignee is type: corporate, else individual’s name).	Varchar, A-Z a-z 0-9 - _ & . : ; space: ()	150	Yes	—
`assignee_type`	The type of the assignee: 1 for Corporate/Company, 2 for Individual.	Integer	—	Yes	1
`assignee_reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-".	Varchar	—	Yes	—
`assignee_country_iso`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	—	Yes	—
`assignee_state_iso`	The appropriate state in US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	—	No	—
`assignee_city`	The name of the city where the assignee resides.	Varchar	—	Yes	—
`assignee_zip_postcode`	The postal code of the assignee.	Varchar	—	Yes	—
`assignee_address`	The address of the assignee. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It Will accept _ / . &	Varchar	—	Yes	—
`assignee_date_incorporation`	The date of assignee’s incorporation.	Date	—	No	—
`assignee_taxid`	The assignee’s tax registration number. Only Alpha numeric values will be accepted. TM will reject all special characters.	Varchar	—	No	—
`assignee_website`	The assignee’s website details.	Varchar	—	No	—
`assignee_client_consent`	Does the assignee give consent to have a GA assigned to themselves: 1 for Yes, 0 for No.	Boolean	—	No	0 (False)
`ultimate_debtor_id`	The ultimate debtor or third-party id associated with the assignee.	Integer	—	—	—
`beneficial_owners`	This object is required if the assignee is a company. Details of at least one beneficial owner is provided.	Object	—	Yes	—
`assignee_beneficial_owner_first_name`	First name of the assignee’s beneficial owner.	Varchar	—	Yes	—
`assignee_beneficial_owner_middle_name`	Middle name of the assignee’s beneficial owner.	Varchar	—	No	—
`assignee_beneficial_owner_last_name`	Last name of the assignee’s beneficial owner.	Varchar	—	Yes	—
`assignee_beneficial_owner_country_iso`	An ISO standard country code from the list of valid country codes, for example, IE (Ireland). See Country Reference by System ID for more information.	Varchar	—	Yes	—
`assignee_beneficial_owner_state_iso`	The appropriate state in US and Canadian jurisdictions. For all other jurisdictions, leave blank. See Country Code for more information.	Varchar	—	No	—
`assignee_beneficial_owner_city`	The name of the city where the assignee’s beneficial owner resides.	Varchar	—	Yes	—
`assignee_beneficial_owner_zip_postcode`	The postal code of the assignee’s beneficial owner.	Varchar	—	Yes	—
`assignee_beneficial_owner_zip_postcode`	The postal code of the assignee’s beneficial owner.	Varchar	—	Yes	—
`assignee_beneficial_owner_address`	The address of the assignee’s beneficial owner. All details are included in one field. To separate multiple address lines please include _/ to indicate a line break. TM will reject majority special characters. It will accept _ / . &	Varchar	—	Yes	—
`assignee_beneficial_owner_date_birth`	The beneficial owner’s date of birth.	Date	—	No	—
`assignee_beneficial_owner_tax_id`	The tax id of the beneficial owner.	Varchar	—	No	—

Example Request

An example of the JSON structure in the request is as follows:

{
"currency": "MXN",
   "name": "MXN assignee",
   "tax_id": "6775421",
   "website": "www.example.com",
   "register_for_amazon": "0",
   "assignee_data": {
"assignee_name": "Test Assigene",
"assignee_type": 1,
"assignee_reconciliation_id": "251217ff1970f0fb18016a725205a139",
"assignee_country_iso": "US",
"assignee_state_iso": "US-CA",
"assignee_city": "Test city",
"assignee_zip_postcode": "1000",
"assignee_address": "test address",
"assignee_date_incorporation": null,
"assignee_taxid": "b0b7b698c8bbde154b237e9a08ab6114",
"assignee_website": null,
"assignee_client_consent": true,
"ultimate_debtor_id": null,
"beneficial_owners": [
{
"assignee_beneficial_owner_first_name": "John",
"assignee_beneficial_owner_middle_name": null,
"assignee_beneficial_owner_last_name": "Smith",
"assignee_beneficial_owner_country_iso": "CA",
"assignee_beneficial_owner_state_iso": "CA-AB",
"assignee_beneficial_owner_city": "City test",
"assignee_beneficial_owner_zip_postcode": "8000",
"assignee_beneficial_owner_address": "test address",
"assignee_beneficial_owner_date_birth": "27/02/1993",
"assignee_beneficial_owner_tax_id": null
},
{
"assignee_beneficial_owner_first_name": "Ivan",
"assignee_beneficial_owner_middle_name": null,
"assignee_beneficial_owner_last_name": "Smith",
"assignee_beneficial_owner_country_iso": "BG",
"assignee_beneficial_owner_state_iso": null,
"assignee_beneficial_owner_city": "City test",
"assignee_beneficial_owner_zip_postcode": "8000",
"assignee_beneficial_owner_address": "test address",
"assignee_beneficial_owner_date_birth": "11/05/1990",
"assignee_beneficial_owner_tax_id": null
}
]
}
}

Example Success Response

The JSON structure in a successful response is as follows:

{
"test assigene - mxn": {
"account_description": "Test Assigene - MXN",
"ending_in": "1126",
"balance": "0.00",
"id": 76626,
"user_bank_id": 513879,
"benef_id": 3949888,
"is_pending": 0,
"is_default": 0,
"info": {
"type": "GA",
"active": 1,
"supported_payments": {
"ach": 0,
"wire": 1,
"instant": 0
},
"bank_details": {
"global_account_holder": "Test Assigene",
"global_account_name": "Test Assigene - MXN",
"account_number": "T0011126",
"iban": "IE06IRCE99990100011126T",
"sort_code": "999901",
"bic_swift": "IRCEIE2D",
"sepa_instant_swift": null,
"bank_name": "J.P. MORGAN BANK (IRELAND) PLC",
"bank_account_holder": "Interpay",
"bank_address": "JPMORGAN HOUSE INTERNATIONAL FINANCIAL SERVICES CENTRE, Dublin 1, Ireland"
           }
       }
},
   "alert": "By continuing, you confirm that you accept the Terms and Conditions. https://transfermate.io/en/terms.html",
   "assignee_id": 34507,
   "assignee_reconciliation_id": "251217ff1970f0fb18016a725205a139",
   "assign_assignee": true,
   "is_successful": true,
"messages": {
"success": "Action performed successfully."
}
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters:

Field	Description	Type
`is_success`	A status message that is either true or false.	Varchar
`stat`	A status message that describes the error encountered.	Varchar

Error Code 422 - When invalid assignee_id is provided

{
...
   "assignee_id": 0,
   "assignee_reconciliation_id": "",
   "assign_assignee": false,
   "is_successful": false,
   "messages": {
"stat": "Please enter valid assignee_id!"
   },
"stat": "Please enter valid assignee_id!"
}

Error Code 422 - In case "assignee_id" AND "assignee_data" parameters are missing from request

{
...
   "assignee_id": 0,
   "assignee_reconciliation_id": "",
   "assign_assignee": false,
   "is_successful": false,
   "messages": {
"stat": "Please add assignee_id or assignee_data!"
   },
"stat": "Please add assignee_id or assignee_data!"
}

Error Code 422 - In case "assignee_data" is provided but it is empty - "assignee_data": {} for example

{
...
   "assignee_id": 0,
   "assignee_reconciliation_id": "",
   "assign_assignee": false,
   "is_successful": false,
   "messages": {
"err": "Invalid ID provided"
   },
"stat": "Please add assignee_id or assignee_data!"
}

POST View Assignee

You can view all the assignees and the global accounts associated with each of them by sending an HTTPS POST request to the /view_assignees endpoint.

Endpoint: /view_assignees

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`page_no`	Pagination Set to 1 to call page 1, set to 2 to call page 2 etc. Defaults to 1 if not provided.	Integer	—	No	1
`page_size`	Number of items returned per page 10/20/30/null. If "null" is used, the API will return all the assignees.	Integer	—	No	—
`assignee_search`	Keyword search that matches either ‘reconciliation_id’ or ‘assignee_name’ or ‘assignee_id’	Varchar	—	No	—

Example Request

An example of the JSON structure in the request is as follows:

{
"page_no": 1,
"page_size": "5",
"assignee_search": "test"
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`Page stats`	Contains pagination stats like the page number, page_count (number of pages), records_per_page (number of items per page) and total_records (total number of items returned)	Array
`assignee_id`	Unique id of the global account assignee created	Integer
`reconciliation_id`	User defined reconciliation id. A unique alpha-numeric string which may be given to identify the assignee. It will accept "-"	Varchar
`assignee_type`	The type of the assignee: 1 for Corporate / Company, 2 for Individual	Integer
`assignee_name`	The name of the assignee (company name if assignee is type: corporate, else individual’s name)	Varchar
`country`	The country of the assignee	Varchar
`state`	The appropriate state in US and Canadian jurisdictions.	Varchar
`city`	The name of the city where the assignee resides.	Varchar
`assigned_global_accounts`	The list of global accounts (with user bank id) that are associated with the assignee_id	Object
`consent`	Does the assignee give consent to have a GA assigned to themselves	—

Example Success Response

The JSON structure in a successful response is as follows:

[
{
  "is_successful": true,
      "messages": {
          "success": "Action performed successfully."
      },
      "data": [
          {
              "assignee_id": "121",
              "reconciliation_id": "3454643634531532542345234",
              "assignee_type": "Corporate",
              "assignee_name": "Test Assigene And Son",
              "country": "USA",
              "state": "Florida",
              "city": "Test city",
              "assigned_global_accounts": {
                "185785": "Test Assigene And Son - SGD 3"
              },
              "consent": "0"
          },
          {
              "assignee_id": "118",
              "reconciliation_id": "251217ff1970f0fb18016a725205a139",
            "assignee_type": "Corporate",
            "assignee_name": "Test Assigene",
              "country": "USA",
              "state": "Florida",
            "city": "Test city",
            "assigned_global_accounts": {
             "183645": "Test Assigene - SGD",
               "185780": "Test Assigene - SGD 2"
              },
              "consent": "1"
          }
        ]
   }
]

Example Error Responses

The JSON structure associated with the error responses has the following parameters:

Error Code 403 - No data

{
"is_successful": false,
  "messages": {
      "stat": "missing or invalid token"
  },
  "stat": "missing or invalid token"
}

Error Code 200 - No data

{
"is_successful": false,
  "messages": {
      "ga_bank_ids": "No data found."
  }
}

POST Assign Assignee

You can associate global account(s) to the added assignee by sending a HTTPS POST request to the /assign_assignee endpoint.

Endpoint: /assign_assignee

Request Body Payload Example

The request body includes the following parameters:

FIELD	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`assignee_id`	The unique assignee id to which the global accounts are to be assigned to	Integer	—	Yes	—
`ga_bank_ids`	One or more global account Id’s	Integer	—	Yes	—

Example Request

An example of the JSON structure in the request is as follows:

{
"assignee_id": 122,
  "ga_bank_ids": [
      210294,
      164750
  ]
}

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "is_successful": true,
      "messages": {
          "success": "Action performed successfully."
      }
  }
]

Example Error Response

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - No data

{
"is_successful": false,
  "messages": {
      "stat": "missing or invalid token"
  },
  "stat": "missing or invalid token"
}

Error Code 200 - No data

{
"is_successful": false,
  "messages": {
      "ga_bank_ids": "Please select a Global Account from the list"
  }
}

Error Code 200 - No data

{
"is_successful": false,
  "messages": {
      "err": "Invalid ID provided"
  }
}

POST Add Sweep Rule

When a user has global accounts created, the sweep functionality allows the user to set rules based on multiple criteria to transfer funds between accounts and/or into external bank accounts.

Sweeping rules and Default Global accounts:

The default Global account can be a Sweep TO, but not a Sweep FROM account. It can have a minimum balance rule to pull from, so it can be loaded for transactions. But it can't have a max or target balance to sweep to.

Please contact your partner implementation manager at partnerimplementation@transfermate.com if you would like access to this functionality.

List of Auto sweep rule endpoints:

Add sweep rule
Edit sweep rule
Change sweep rule status
Delete sweep rule
List sweep rule

Endpoint: /v2/add_sweep_rule

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`rule_name`	Sweep rule name, accept Latinised ASCI characters	Varchar	500	No	-
`rule_type`	Possible options: - transaction - when money lands in this account, it will be immediately swept. - regular - based on Balance amount.	Varchar	11	Yes	-
`rule_balance_based_sweep`	Possible options: 2- Max Account balance 3- Min Account balance 4- Target Account balance	Integer	1	Mandatory when rule_type=Regular	-
`rule_currency`	3-letter currency ISO code of the global account sweeping from	Varchar	3	Yes	-
`rule_sweep_to_type`	Possible options: - "global"=One of my other Global Accounts in the same or different currency - "beneficiary"=One of my Beneficiaries	Varchar	11	Yes	-
`rule_sweep_from`	Global account ID from where we will be sweeping money; it could be more than one Global account. EXAMPLE: ["458973", "466671"]	Varchar	-	Yes	-
`rule_sweep_to`	ISO currency and - “benef_id” of beneficiary/global account	Varchar	500	rule_balance_based_sweep=2, 4	-
`rule_account_balance`	The amount that will be automatically swept.	-	-	Available only when rule_type= Regular	-
`rule_pull_from_type`	"global"=One of my other Global Accounts in the same or different currency	-	-	rule_balance_based_sweep=3, 4	-
`rule_pull_from`	ISO currency and - “Global Account user_bank_id” EXAMPLE: EUR-458973	-	-	rule_balance_based_sweep=3, 4	-
`rule_run_type`	Possible options: - "immediately"= Immediately when conditions are met - "daily" - "weekly” - “monthly”	Varchar	-	Available only when rule_type= Regular	-
`rule_start_date`	Display when the rule should start yyyy-mm-dd	Date	10	Yes	-
`rule_last_date`	Display when the rule should stop yyyy-mm-dd. Send an empty string to continue the rule without an end date.	Date	10	-	-
`rule_apply_all`	Do you wish to apply ( enable) the rule. Possible options: 0- no 1- yes	Date	10	-	-
`rule_frequency`	A list of rule frequency attributes	List	-	Yes	-
`rule_time`	GMT time, format Hh: mm	-	-	Not mandatory, only if rule_run_type= “immediatelly”	-
`week_checkboxes`	Possible values: 1- MON 2- TUE 3- WED 4- THU 5- FRI 6- SAT 7- SUN	-	-	Not mandatory, only if rule_run_type= “immediatelly”	-
`rule_date`	dd/mm/yyyy	-	-	rule_run_type= “monthly”	-

Example Request

An example of the JSON structure in the request is as follows:

{
   "rule_name": "",
   "rule_type": "regular",
   "rule_balance_based_sweep": "4",
   "rule_currency": "GBP",
   "rule_sweep_to_type": "global",
   "rule_sweep_from": [
       "458973",
       "466671"
   ],
   "rule_sweep_to": "USD-74333",
   "rule_account_balance": "10",
   "rule_pull_from_type": "global",
   "rule_pull_from": "EUR-458973, EUR-466671",
   "rule_run_type": "daily",
   "rule_start_date": "2025-01-21",
   "rule_last_date": "2026-12-12",
   "rule_apply_all": "0",
   "rule_frequency": [
{
"rule_time": "00:18",
"week_checkboxes": "",
"rule_date": "02/04/2025"
}
]
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar
`rule_id`	The ID of the sweep rule, for example, 321894.	Integer

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "stat": "success",
   "messages": {
"success": "Action performed successfully."
   },
"rule_id": 127
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar
`global_errors`	Global errors associated with the request.	List
`input_errors`	Input errors associated with the request.	List

HTTP 521 - Bad Request

{
   "is_successful": false,
   "messages": [],
   "global_errors": [],
   "input_errors": [
{
"ID": "rule_start_date",
"description": "You cannot select a past date as a start date"
}
]
}

POST Edit sweep rule

Endpoint: /v2/edit_sweep_rule

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id`	Sweep Rule ID	Integer	-	Yes	-
`rule_name`	Sweep rule name, accept latinise ASCI characters	Varchar	500	No	-
`rule_currency`	3 letter currency ISO code of the global account sweeping from	Varchar	3	Yes	-
`rule_sweep_to_type`	Possible options: - "global"=One of my other Global Accounts in the same or different currency - "beneficiary"=One of my Beneficiaries	Varchar	11	Yes	-
`rule_sweep_from`	Global account ID from where we will be sweeping money, it could be more than one Global account EXAMPLE: ["458973", "466671"]	Varchar	-	Yes	-
`rule_sweep_to`	ISO currency and - “benef_id” of beneficiary/global account	Varchar	500	rule_balance_based_sweep=2, 4	-
`rule_account_balance`	The amount which will be automatically swept.	-	-	Available only when rule_type= Regular	-
`rule_pull_from_type`	"global"=One of my other Global Accounts in the same or different currency	-	-	rule_balance_based_sweep=3, 4	-
`rule_pull_from`	ISO currency and - “Global Account user_bank_id” EXAMPLE: EUR-458973	-	-	rule_balance_based_sweep=3, 4	-
`rule_run_type`	Possible options: - "immediately"= Immediately when conditions are met - "daily" - "weekly” - “monthly”	Varchar	-	Available only when rule_type= Regular	-
`rule_start_date`	Display when rule should start yyyy-mm-dd	Date	10	Yes	-
`rule_last_date`	Display when rule should stop yyyy-mm-dd. Send empty string to continue rule without end date.	Date	10	-	-
`rule_apply_all`	Do you wish to apply ( enable) the rule. Possible options: 0- no 1- yes	Date	10	-	-
`rule_frequency`	A list of rule frequency attributes	List	-	Yes	-
`rule_time`	GMT time, format Hh:mm	-	-	Not mandatory, only if rule_run_type= “immediatelly”	-
`week_checkboxes`	Possible values: 1- MON 2- TUE 3- WED 4- THU 5- FRI 6- SAT 7- SUN	-	-	Not mandatory, only if rule_run_type= “immediatelly”	-
`rule_date`	dd/mm/yyyy	-	-	rule_run_type= “monthly”	-

Example Request

An example of the JSON structure in the request is as follows:

{
   "id": 96,
   "rule_name": "",
   "rule_currency": "GBP",
   "rule_sweep_to_type": "sender",
   "rule_sweep_from": [],
   "rule_sweep_to": "EUR-",
   "rule_account_balance": "10",
   "rule_pull_from_type": "global",
   "rule_pull_from": "EUR-458973, EUR-466671",
   "rule_run_type": "daily",
   "rule_start_date": "2021-21",
   "rule_last_date": "2022-12",
   "rule_apply_all": "0",
   "rule_frequency": [
{
"rule_time": "00:18",
"week_checkboxes": "",
"rule_date": "13/02/20325"
},
{
"rule_time": "00:18",
"week_checkboxes": "",
"rule_date": "14/02/2025"
}
]
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "stat": "success",
   "messages": {
"success": "Action performed successfully."
   }
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar

HTTP 421 – Not Processable Entity

{
   "is_successful": false,
   "messages": {
"stat": "Sweeping Rule id not provided!"
   },
   "stat": "Sweeping Rule id not provided!"
}

// Case "id" is invalid (not existing)

{
   "is_successful": false,
   "messages": {
"stat": "Sweeping Rule not found!"
   },
   "stat": "Sweeping Rule not found!"
}

HTTP 521 - Bad Request

{
   "is_successful": false,
   "messages": [],
   "global_errors": [],
   "input_errors": [
      {
"ID": "rule_sweep_from",
         "description": "Please select"
      },
      {
         "ID": "rule_sweep_to",
         "description": "Please enter correct information!"
      },
      {
         "ID": "rule_start_date",
         "description": "Please enter correct information!Date format error: Y-m-d 20211-21! The separation symbol could not be found"
      },
      {
         "ID": "rule_last_date",
         "description": "Please enter correct information!Date format error: Y-m-d 20212-12! The separation symbol could not be found"
      },
      {
         "ID": "rule_date_picker_1",
         "description": "Please enter correct information!Date format error: d/m/Y 13/02/20325! Trailing data"
      }
   ]
}

POST Change sweep rule status

Endpoint: /v2/sweep_rule_status

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id`	Sweep Rule ID	Integer	-	Yes	-
`active`	Possible values: “0”, ““, “false” ( deactivating ) , “true”, “1” (activating)	Varchar	1	No	-

Example Request

An example of the JSON structure in the request is as follows:

{
"id": 54,
"active": 1
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar
`active`	A message that describes the outcome of the request.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "stat": "Sweeping Rule status was updated successfully!",
   "messages": {
      "success": "Action performed successfully."
   },
   "active": 1
}

Case when user de-activate the rule

{
   "is_successful": true,
   "stat": "Sweeping Rule status was updated successfully!",
   "messages": {
      "success": "Action performed successfully."
   },
   "active": 0
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar
`active`	A message that describes the outcome of the request.	Varchar

HTTP 532 - Bad Request

// Case "id" is missing from request

{
   "is_successful": false,
   "messages": {
      "stat": "One or more JSON attributes missing or malformed: 'id'"
   },
   "stat": "One or more JSON attributes missing or malformed: 'id'"
}

HTTP ERROR 521 - Bad Request

// Invalid id provided

{
   "is_successful": false,
   "messages": [],
   "input_errors": [
      {
         "ID": "id",
         "description": "Sweeping Rule not found!"
      }
   ]
}

// Invalid "active" parameter provided

{
   "is_successful": false,
   "messages": [],
   "input_errors": [
      {
         "ID": "active",
         "description": "Please enter correct information!"
      }
   ]
}

POST Delete sweep rule

The client can use this endpoint if they wish to delete (completely remove) a sweep rule. If they wish to currently deactivate a sweep rule, they should use /sweep_rule_status endpoint instead.

Endpoint: /v2/delete_sweep_rule

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id`	Sweep Rule ID	Integer	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"id": ""
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "stat": "Sweeping Rule was deleted successfully!",
   "messages": {
      "success": "Action performed successfully."
   }
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`stat`	A status message that describes the outcome of the request.	Varchar
`input_errors`	Input errors associated with the request.	List

HTTP ERROR 532 - Bad Request

// Case where we miss ID from request

{
   "is_successful": false,
   "messages": {
      "stat": "One or more JSON attributes missing or malformed: 'id'"
   },
   "stat": "One or more JSON attributes missing or malformed: 'id'"
}

HTTP ERROR 521 - Bad Request

// Case when the rule ID is invalid

{
   "is_successful": false,
   "messages": [],
   "input_errors": [
      {
         "ID": "id",
         "description": "Sweeping Rule not found!"
      }
   ]
}

// Case where deletion failed

{
   "is_successful": false,
   "messages": {
      "stat": "Sweeping Rule delete not successful!"
   },
   "stat": "Sweeping Rule delete not successful!"
}

POST List sweep rule

Endpoint: /v2/sweeping_rules_list

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id`	Sweep Rule ID	Integer	-	No	-
`rule_name`	Sweep rule name, accept latinise ASCI characters	Varchar	500	No	-
`currency`	3 letter currency ISO code of the global account sweeping from	Varchar	3	No	-
`sweepin_to`	“Currency-Global account ID”	Varchar	-	No	-
`pulling_from`	“Currency-Global account ID”	Varchar	-	No	-
`applies_to_accounts`	-	-	-	No	-
`from_date`	Start date	Date	-	No	-
`to_date`	Start date	Last date of the sweep rule	-	No	-

Example Request

{
   "id": "",
   "rule_name": "",
   "currency": "",
   "sweepin_to": "",
   "pulling_from": "",
   "applies_to_accounts": "",
   "from_date": "",
   "to_date": "",
   "p_number": 1,
   "p_number_rows": 10
}

Response Body Payload Example

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`page`	The current page number	Integer
`pages_count`	Total amount of pages	Integer
`records_per_page`	Amount of transaction records per page	Integer
`total_records`	Total records in the Quote Batch	Integer
`data`	List with sweeping rules	List

Example Success Response

The JSON structure in a successful response is as follows:

{
   "is_successful": true,
   "messages": {
      "success": "Action performed successfully."
   },
   "page": 1,
   "pages_count": 1,
   "records_per_page": 10,
   "total_records": 1,
   "data": [
      {
         "id": "129",
         "rule_name": "Sweeping Rule 41",
         "last_updated": "2025/01/14",
         "rule_for": "Max Account Balance",
         "applies_to": "Test - RON - 0 RON",
         "sweep_to": "Test - NZD - 0 NZD",
         "rule_when": "Weekly",
         "status": "1",
         "status_name": "Active",
         "start_date": "2025-01-16",
         "last_date": "2026-01-01",
         "is_tm_rule": "0"
      }
   ]
}

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`is_successful`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	List
`global_errors`	Global errors associated with the request.	List
`input_errors`	Input errors associated with the request.	List

{
   "is_successful": false,
   "messages": {
      "rule_last_updated_from": "Please enter correct information!Date format error: Y-m-d 2025-02/03! Unexpected data found."
   },
   "global_errors": [],
   "input_errors": [
      {
         "ID": "from_date",
         "description": "Please enter correct information!Date format error: Y-m-d 2025-02/03! Unexpected data found."
      }
   ]
}

Third Party Flow

This gives you the ability to add, view, edit and delete ultimate debtors on your account.

Add an Ultimate Debtor
View an Ultimate Debtor
Edit an Ultimate Debtor
Delete an Ultimate Debtor
Lock in an Exchange Rate for a Payment Transaction with Third Party Flow

POST Add an Ultimate Debtor

You can add an ultimate debtor by sending a HTTP POST request to the `/add_ultimate_debtor` endpoint.

Endpoint: /add_ultimate_debtor

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`ultimate_debtor_type`	The type of the debtor. There are 2 options: 1: Corporate, 2:Individual	Interger	-	Yes	-
`ultimate_debtor_name`	The name of the debtor.	Varchar	-	Yes	-
`ultimate_debtor_acc_number_iban`	Account number of the debtor.	Varchar	-	Yes	-
`ultimate_debtor_reconciliation_id`	User defined reconciliation id.	Varchar	-	Yes	-
`ultimate_debtor_country`	The country of the debor. See list of country IDs.	Integer	-	Yes	-
`ultimate_debtor_address`	The address of the debtor.	Varchar	-	Yes	-
`ultimate_debtor_city`	The city of the debtor.	Varchar	-	Yes	-
`ultimate_debtor_state`	The state of the debtor (If in US or Canada).	Varchar	-	No	-
`ultimate_debtor_zip_postcode`	The Zip or Post code of the debtor.	Varchar	-	Yes	-
`ultimate_debtor_email`	The email address of the debtor.	Varchar	-	No	-

Example Success Request

An example of the JSON structure in the request is as follows:

{
"ultimate_debtor_type": "1",
  "ultimate_debtor_name": "Debtor INC",
  "ultimate_debtor_acc_number_iban": "IE64IRCE92050112345678",
  "ultimate_debtor_reconciliation_id": "DebtorINC123",
  "ultimate_debtor_country": "113",
  "ultimate_debtor_address": "1 Grafton Street",
  "ultimate_debtor_city": "Dublin",
  "ultimate_debtor_state": "",
  "ultimate_debtor_zip_postcode": "D02 K033",
  "ultimate_debtor_email": "debtor@dinc.com"
}

Response Body Payload Example

If add an ultimate debtor request is successful, the service returns a response.

The response body includes the following parameters:

Field	Description	Type
`stat`	A message to tell if the request has been successful.	Varchar
`ultimate_debtor_id`	The ID of the Ultimate Debtor that has been created	Integer

Example Success Response

The JSON structure in a successful response is as follows:

{
"stat": "success",
"ultimate_debtor_id": 81
}

Example Error Responses

If adding an ultimate debtor is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`global_errors`	Global errors associated with the request.	Varchar
`input_errors`	Input errors associated with the request.	Varchar
`description`	Description of the issue	Varchar

Error Code 521 - Error adding debtor

{
"global_errors": [],
  "input_errors": [
      {
          "ID": "ultimate_debtor_type",
          "description": "Please enter correct information!"
      },
      {
        "ID": "ultimate_debtor_acc_number_iban",
        "description": "This Account Number or IBAN is already used by another Ultimate Debtor!"
      }
  ]
}

POST View an Ultimate Debtor

You can view the detials of ultimate debtors by sending a HTTP POST request to the `/view_ultimate_debtor` endpoint.

Endpoint: /view_ultimate_debtor

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`id_or_name`	The ID or Name of the Debtor you want to view. If left blank, all debtors will be returned.	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"id_or_name": "81"
}

Response Body Payload Example

If add an ultimate debtor request is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`tm_id`	The ID of the debtor	Varchar
`reconciliation_id`	The reconciliation_id associated.	Varchar
`ultimate_debtor_type`	The type of ultimate debtor. Either "corporate" or "individual".	Varchar
`name`	The name of ultimate debtor.	Varchar
`country`	The country of ultimate debtor.	Varchar
`state`	The state of ultimate debtor if applicable.	Varchar
`city`	The city of ultimate debtor.	Varchar
`active`	The active status of ultimate debtor. 1 is active, 0 is deactivated.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
"tm_id": "81",
  "reconciliation_id": "debtorinc123",
  "ultimate_debtor_type": "1",
  "name": "debtor inc",
  "country": "ireland",
  "state": "-",
  "city": "dublin",
  "active": "1"
}

Example Error Responses

If viewing a debtor is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	Global errors associated with the request.	Varchar

Error Code 404 - Error adding debtor

{
"stat": "No users found"
}

POST Edit an Ultimate Debtor

You can edit the detials of ultimate debtors by sending a HTTP POST request to the `/edit_ultimate_debtor` endpoint.

Endpoint: /edit_ultimate_debtor

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`ultimate_debtor_id`	The ID of the Debtor you want to edit.	Varchar	-	Yes	-
`ultimate_debtor_country`	The country of the debor. See list of country IDs.	Integer	-	No	-
`ultimate_debtor_address`	The address of the debtor.	Varchar	-	No	-
`ultimate_debtor_city`	The city of the debtor.	Varchar	-	No	-
`ultimate_debtor_zip_postcode`	The Zip or Post code of the debtor.	Varchar	-	No	-
`ultimate_debtor_email`	The ID or Namr of the Debtor you want to view. If left blank, all debtors will be returned.	Varchar	-	No	-
`ultimate_debtor_activate_deactivate`	The active status of the debtor. Use 1: active and 2: deactivate	Integer	-	No	-
`ultimate_debtor_name`	The name of the debtor. This can only be changed if no payments have been made with this debtor yet.	Varchar	-	No	-
`ultimate_debtor_type`	The type of the debtor. There are 2 options: 1: Corporate, 2:Individual This can only be changed if no payments have been made with this debtor yet.	Integer	-	No	-
`ultimate_debtor_acc_number_iban`	The account number of the debtor. This can only be changed if no payments have been made with this debtor yet.	Varchar	-	No	-
`ultimate_debtor_reconciliation_id`	User defined reconciliation id. This can only be changed if no payments have been made with this debtor yet.	Varchar	-	No	-

Example Request

An example of the JSON structure in the request is as follows:

{
"ultimate_debtor_id": "81",
  "ultimate_debtor_country": 238,
  "ultimate_debtor_address": "1 Main St",
  "ultimate_debtor_city": "New York",
  "ultimate_debtor_zip_postcode": "NY01",
  "ultimate_debtor_email": "debtnewyork@debtinc.com",
  "ultimate_debtor_activate_deactivate": 1
}

Response Body Payload Example

If editing an ultimate debtor is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`tm_id`	The ID of the debtor	Varchar
`reconciliation_id`	The reconciliation_id associated.	Varchar
`ultimate_debtor_type`	The type of ultimate debtor. Either "corporate" or "individual".	Varchar
`name`	The name of ultimate debtor.	Varchar
`country`	The country of ultimate debtor.	Varchar
`state`	The state of ultimate debtor if applicable.	Varchar
`city`	The city of ultimate debtor.	Varchar
`active`	The active status of ultimate debtor. 1 is active, 0 is deactivated.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
"stat": "81 successfully updated"
}

Example Error Responses

If editing a debtor is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`global_errors`	Global errors associated with the request.	Varchar
`input_errors`	Input errors associated with the request.	Varchar

Error Code 521 - Error editing a debtor

{
"global_errors": [
      "No ultimate debtor with such ID!"
  ],
  "input_errors": []
}

POST Delete an Ultimate Debtor

You can delete an ultimate debtor if they have no transactions associated with them by sending a HTTP POST request to the `/delete_ultimate_debtor` endpoint.

Endpoint: /delete_ultimate_debtor

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`ultimate_debtor_id`	The ID of the Debtor you want to delete.	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"ultimate_debtor_id": "81"
}

Response Body Payload Example

If deleting an ultimate debtor is successful, the service returns a response.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A message to tell if the request has been successful.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
"stat": "Deleted debtor with ID: 81"
}

Example Error Responses

If deleting a debtor is not successful, the service responds with an error code, and rejects the request. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A message to tell if the request has been unsuccessful.	Varchar

Error Code 200 - Error deleting a debtor

{
"stat": "No ultimate debtor with such ID!"
}

POST Lock in an Exchange Rate for a Payment Transaction with Third Party Flow

You lock in a currency exchange rate for your transaction by sending an HTTP POST request with the required information to the /api/book endpoint.

Notes regarding bookings:

If /connect is called between the /book and /authorize call, the session will be reset and the quoted rate will be refreshed.

The recommended maximum number of transactions that you can book is 150 per request. The max number of transactions for a single beneficiary is 100 transactions per request - ONLY the first transaction will be submitted

Endpoint: /book

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`bank_id_from`	The ID of the bank from which the funds originate. This is the bank's own account ID.	Integer	-	Yes	-
`bank_pay_type`	The payment type. Possible values are: 1: Direct Debit/ACH - 2: Wire Transfer - 3: Withdrawal - 21: Reverse Wire	Integer	-	Yes	-
`use_client_id`	A flag to indicate whether the user is passing in the standard beneficiary ID: 0, or the custom client ID: 1.	Integer	-	No	0
`choose_an_ultimate_debtor`	Determines if the payment is to be made using the third-party flow. 2 options: 1: On behalf of someone else 2:Myself.	Varchar	-	No	Myself
`beneficiary_data`	A list of beneficiary payment attribute groups.	List	-	Yes	-
`beneficiary_data_id`	The ID of the beneficiary to whom the payment is to be made. This can be either the beneficiary ID or the client ID. Please note that if sending a request involving multiple beneficiaries, the format for this field must remain consistent. i.e., all beneficiary IDs or all client IDs.	Varchar	-	Yes	1
`beneficiary_data_currency`	The ID of the currency corresponding to the beneficiary account. Accounts can have more than one currency. See View Beneficiary Accounts to retrieve this information. To pay in a fixed domestic currency, put switch. before the currency value eg, switch.EUR	Varchar	5	Yes	-
`beneficiary_data_amount`	The amount of money to send to the beneficiary in their currency.	Decimal	11,2	Yes	0
`beneficiary_data_user_reference`	A reference to be sent to the receiving bank. Note '&' cannot be used in the field, please use 'and' or '&'	Varchar	18	Yes	-
`beneficiary_data_transfer_reason`	The transfer reason. Typically set to the default value, Bill payment. See the Transfer Reasons section for more information.	Varchar	20	Yes	Bill Payment
`beneficiary_data_transfer_reason_id`	The transfer reason code. Typically set to the default value 7 (Bill payment). See the Transfer Reasons section for more information.	Varchar	20	Yes	7
`beneficiary_data_value_date`	A date given in the format of YYYY-MM-DD, on which the funds are to be in the beneficiary bank account. This is either enabled and therefore becomes mandatory or is not enabled and is not taken into consideration.	Varchar	-	No	-
`reconciliation_id`	An optional custom identifier for client-side reconciliation.	Varchar	52	No	-
`client_transaction_id`	An optional custom identifier for transactions supplied by the user. This is a client-specific, unique reference. Must be at least 8 characters long and not start with "0", "T", "t", "B", or "b".	Varchar	100	yes	-
`beneficiary_data_payment_type`	The type of payment rail by which the beneficiary is to be paid. Possible values:60 - ACH Same Day,20 - ACH Next Day,2 - Domestic Wire,63 - International Wire,64 - Instant	Integer	-	No	ACH
`beneficiary_data_ultimate_debtors_id`	The ID of the Ultimate Debtor to use for Third Party Flow payments	Integer	-	No	-

Example Request

An example of the JSON structure in the request is as follows:

{
"bank_id_from": 63645,
  "bank_pay_type": 2,
  "use_client_id": 0,
  "choose_an_ultimate_debtor": "On behalf of someone else",
  "beneficiary_data": [
      {
          "beneficiary_data_id": "220865",
          "beneficiary_data_currency": "EUR",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 8",
          "beneficiary_data_transfer_reason": "Bill Payment",
          "beneficiary_data_transfer_reason_id": "7",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "beneficiary_data_ultimate_debtors_id": 258,
          "client_transaction_id": "123456",
          "beneficiary_data_payment_type": "20"
      },
      {
          "beneficiary_data_id": "199641",
          "beneficiary_data_currency": "NOK",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 9",
          "beneficiary_data_transfer_reason": "Expense Reimbursement",
          "beneficiary_data_transfer_reason_id": "30",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "client_transaction_id": "123ABC",
          "beneficiary_data_payment_type": "20"
}
]
}

Response Body Payload Example

If the request is successful, the service responds with details of the booking.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`uid`	The internal unique ID of the beneficiary.	Integer
`payee_name`	The name of the payee.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`service_type`	The type of the service.	Varchar
`bene_payment_type`	The type of the payment.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`conversion_meta`	A container for conversion details.	-
`conversion`	Sub-containers for conversion details.	-
`inverse`	Sub-containers for conversion details.	-
`from`	The type of the payment.	Varchar
`to`	The currency to convert to.	Varchar
`input`	The amount to convert.	Decimal/Float
`output`	The exchange rate.	Decimal
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee	Decimal
`transfer_reason`	The reason for the transfer, typically 7 (Bill Pay).	Varchar
`transfer_reason_id`	The ID of the transfer reason.	Varchar
`reference`	A reference for the transaction.	Varchar
`forbidden`	A flag that indicates if the transaction can be processed or not. A value of 0 indicates that the transaction can be processed normally. A value of 1 indicates that the transaction cannot be processed.	Varchar
`alerts`	A message to draw the user's attention to a possible anomaly that the user should check.	Varchar
`transaction_id`	The ID assigned to the transaction.	Varchar
`user_id`	The client_transaction_id that was passed in the request. If not passed, value will be null	Varchar
`ultimate_debtors_id`	The ID of the Ultimate Debtor used in Third Party Flow payments.	Integer

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 1000000.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "rail_type": "ACH Next Day",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
        },
          "inverse": {
              "from": "EUR",
              "to": "EUR",
            "input": 1,
            "output": 1
        }
    },
      "amount_from_bef_fee": "EUR 1000000.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 1000115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 9",
      "ultimate_debtors_id": "The Debtor Company",
      "forbidden": "1",
      "alerts": "Further information is required to book this amount.Please contact funds@transfermate.com in order to continue with your booking.",
      "user_uid": null
}
]

The JSON structure in a successful response is as follows:

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 100.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          },
          "inverse": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          }
      },
      "amount_from_bef_fee": "EUR 100.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 8",
      "forbidden": "0",
      "alerts": "Please note for same currency payments outside the SEPA area, the receiving bank may charge a receiving fee to the receiver.For more info click www.transfermate.com/chat,,NB: You have submitted a transaction with the same parameters (amount, currency and beneficiary details) in the last 24 hours. To ensure this is not a duplicate payment, check previous submissions on your Accounts Summary.",
      "transaction_id": "T684736",
      "user_uid": "123456"
  },
  {
      "uid": 199641,
      "payee_name": "Norwegian Supplier",
      "foreign_ammount": "NOK 100.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 9.37072 NOK,1 NOK = 0.10672 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "NOK",
              "input": 1,
            "output": 9.37072
          },
        "inverse": {
            "from": "NOK",
              "to": "EUR",
            "input": 1,
            "output": 0.10672
        }
      },
      "amount_from_bef_fee": "EUR 10.67",
      "fee": "5.00",
      "total_trans_amount_from": "EUR 15.67",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "None",
      "reference": "api ref 9",
      "forbidden": "0",
      "alerts": "NB: You have submitted a transaction with the same parameters (amount, currency and beneficiary details) in the last 24 hours.To ensure this is not a duplicate payment, check previous submissions on your Accounts Summary.",
      "transaction_id": "T684737",
      "user_uid": null
}
]

Example Error Responses

If the lock-in exchange rate request is not successful, the service responds with an error code, rejects the request, and does not lock in the exchange rate. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar
`ID`	The ID of the error message.	Varchar
`description`	A descirption of the error.	Varchar

Error Code 542 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 1000000.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "EUR",
            "input": 1,
            "output": 1
          },
        "inverse": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          }
      },
      "amount_from_bef_fee": "EUR 1000000.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 1000115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 9",
      "forbidden": "1",
      "alerts": "Further information is required to book this amount.Please contact funds@transfermate.com in order to continue with your booking.",
      "user_uid": null
}
]

Error Code 545 - One or More JSON Attributes Missing or Malformed

{
"stat": "one or more JSON attributes missing or malformed: currency_type"
}

Error Code 546 - One or More JSON Attributes Failed Validation

{
"stat": "contents of one or more JSON attributes failed validation"
}

Error Code 404 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

{
"stat": "Beneficiary does not exist or has been disabled"
}

Performing Payment Transactions

The TransferMate Payments service enables you to make payments to third parties.

Using the Payments API, you make a payment using the following three steps, the first of which is optional:

Get a Currency Exchange Rate for Review (Optional)
You can query the exchange rate for a currency. The Payments service does not create a record in the TransferMate system in this case.).
Get a Currency Exchange Rate for Review (Optional)
You can query the exchange rate for a currency. The Payments service does not create a record in the TransferMate system in this case.).
Lock in an Exchange Rate for a Payment Transaction
This operation is similar to the action in the previous step. In this case however, the Payments service creates a record in the TransferMate system. The returned rate remains valid for 90 seconds between the lock-in time and authorization (see the next step).
Authorize One or More Payment Transactions
You can authorize one or more payments in a batch transaction. If the batch transaction includes payment transactions that are not recognized by the service, these are highlighted as erroneous payment transactions.
Convert Global/Virtual Account Funds
This operation can be used to convert funds from one currency to another in a Global/Virtual account.
Convert Global/Virtual Account Funds V2
This operation can be used to convert funds from one currency to another in a Global/Virtual account.

In addition to the steps provided above, the Payments API provides other useful features that relate to transactions:

Get Transaction Summary Get Transaction Summary V2
Using this feature, you can retrieve details of a specific transaction or group of transactions. You can specify filter values to narrow the returned transactions to exactly the subset you want. For example, you can set a filter value on the ref_number field to retrieve just the details of the one transaction that matches the value of ref_number field. Alternatively, you can set filters on the bank_id_from field, the date_from field, and the date_to field, to retrieve transactions associated with a specific bank between the from and to dates you specify.

Get Spot Rates
Using this feature, you can retrieve spot rates for currency exchange transactions. You specify the amount you want to exchange and the pairs of to/from currencies for which you wish to get the relevant exchange rate information. The Payments service responds with bid, ask, and middle rates and the corresponding amounts in both the to and from currencies you specify. The times associated with the quoted rates are also included. The quoted rates are the market rates. Margins and commissions are not applied.

Get Global/Virtual Convert Exchange Rate for Review
Get Global/Virtual Convert Exchange Rate for Review V2
Using this feature, you can retrieve a review rate for a conversion.

The following figure shows the get spot rates flow:

POST Get a Currency Exchange Rate for Review

You can retrieve and review a currency exchange rate by sending an HTTP POST request with the required information to the /get_booking_rate endpoint. Please note that if this endpoint is being used, the exchange rate will be locked in for 90s.

In request responses: If a field exists and is not empty (for example, it contains an error message or a notice), the transaction may not be processed. Always display messages of this type to the user or client. For example, if same currency payments/transactions are not allowed, notify the user. If the value of the forbidden field is 1, the current transaction is not allowed and is not processed. The default value is 0, that is, a transaction is processed normally.

Endpoint: /get_booking_rate

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`bank_id_from`	The ID of the bank from which the funds originate. This is the bank's own account ID.	Integer	-	Yes	-
`bank_pay_type`	The payment type. Possible values are: 1: Direct Debit/ACH - 2: Wire Transfer - 3: Withdrawal - 21: Reverse Wire	Integer	-	Yes	-
`use_client_id`	A flag to indicate whether the user is passing in the standard beneficiary ID: 0, or custom client ID: 1.	Integer	-	No	0
`beneficiary_data`	A list of beneficiary payment attribute groups.	List	-	Yes	-
`beneficiary_data_id`	The ID of the beneficiary to whom the payment is to be made. This can be either the beneficiary ID or the client ID. Please note that if sending a request involving multiple beneficiaries the formation for this field must remain consistent. i.e. all beneficiary IDs or all client IDs. If sending the beneficiary ID, please send as an integer, if sending as client ID send as a string.	Varchar/Integer	-	Yes	-
`beneficiary_data_currency`	The ID of the currency corresponding to the beneficiary account. Accounts can have more than one currency. See View Beneficiary Accounts to retrieve this information. To pay in a fixed domestic currency, put switch. before the currency value eg. switch.EUR	Varchar	5	Yes	-
`beneficiary_data_amount`	The amount of money to send to the beneficiary in their currency.	Decimal	11,2	Yes	0
`beneficiary_data_user_reference`	A reference to be sent to the receiving bank. Note '&' cannot be used in the field please us 'and' or '&'	Varchar	18	Yes	-
`beneficiary_data_transfer_reason`	The transfer reason. Typically set to the default value Bill payment. See the Transfer Reasons section for more information.	Varchar	20	Yes	Bill Payment
`beneficiary_data_transfer_reason_id`	The transfer reason code. Typically set to the default value 7 (Bill payment). See the Transfer Reasons section for more information.	Varchar	20	Yes	7
`beneficiary_data_value_date`	A date given in the format of YYYY-MM-DD, on which the funds are to be in the beneficiary bank account. This is either enabled and therefore becomes mandatory or is not enabled and is not taken into consideration.	Varchar	-	No	-
`beneficiary_data_payment_type`	The type of payment rail, the beneficiary is to be paid by. Possible values:60 - ACH Same Day,20 - ACH Next Day,2 - Domestic Wire,63 - International Wire,64 - Instant	Integer	-	No	ACH
`reconciliation_id`	An optional custom identifier for client-side reconciliation.	Varchar	52	No	-
`client_transaction_id`	An optional custom identifier for transactions supplied by the user. This is a client specific unique reference. Must be atleast 8 character long and not start with "0", "T", "t", "B", or "b".	Varchar	100	yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"bank_id_from": 63645,
  "bank_pay_type": 2,
  "use_client_id": 0,
  "beneficiary_data": [
      {
          "beneficiary_data_id": 220865,
          "beneficiary_data_currency": "EUR",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 8",
          "beneficiary_data_transfer_reason": "Bill Payment",
          "beneficiary_data_transfer_reason_id": "7",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "client_transaction_id": "123456",
          "beneficiary_data_payment_type": "20"
      },
      {
          "beneficiary_data_id": 199641,
          "beneficiary_data_currency": "NOK",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 9",
          "beneficiary_data_transfer_reason": "Expense Reimbursement",
          "beneficiary_data_transfer_reason_id": "30",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "client_transaction_id": "123ABC",
          "beneficiary_data_payment_type": "20"
      }
]
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	Type
`uid`	The internal unique ID of the beneficiary.	Integer
`payee_name`	The name of the payee.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`service_type`	The type of the service.	Varchar
`bene_payment_type`	The type of the payment.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`conversion_meta`	A container for conversion details.	-
`conversion`	Sub-containers for conversion details.	-
`inverse`	Sub-containers for conversion details.	-
`from`	The type of the payment.	Varchar
`to`	The currency to convert to.	Varchar
`input`	The amount to convert.	Decimal/Float
`output`	The exchange rate.	Decimal
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee	Decimal
`transfer_reason`	The reason for the transfer, typically 7 (Bill Pay).	Varchar
`transfer_reason_id`	The ID of the transfer reason.	Varchar
`reference`	A reference for the transaction.	Decimal
`forbidden`	A flag that indicates if the transaction can be processed or not. A value of 0 indicates that the transaction can be processed normally. A value of 1 indicates that the transaction cannot be processed.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "uid": 9875641,
      "payee_name": "China Beneficiary XXX",
      "foreign_amount": "USD 2000.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "rail_type": "ACH Next Day",
      "currency_rate_per_unit": "1 CAD = 0.76449 USD,1 USD = 1.30806 CAD",
      "conversion_meta": {
  "conversion": {
              "from": "CAD",
            "to": "USD",
              "input": 1,
            "output": 0.76449
  },
          "inverse": {
              "from": "USD",
              "to": "CAD",
            "input": 1,
              "output": 1.30806
          }
      },
      "amount_from_bef_fee": "CAD 2616.12",
      "fee": "5.00",
      "total_trans_amount_from": "CAD 2621.12",
      "transfer_reason": "7",
      "transfer_reason_id": "None",
      "reference": "tst ref 246",
      "forbidden": "0"
}
]

Example Error Responses

If the get and review exchange rate request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar
`ID`	The ID of the error message.	Varchar
`description`	A descirption of the error.	Varchar

Error Code 541 - Payment Type Invalid

[
{
      "ID": "bank_pay_type",
      "description": "Payment type is not valid!"
  },
  {
      "ID": "db_action",
      "description": "Operation is not successful! Please try again."
  }
]

Error Code 543 - Invalid Combination of Parameters or Payment Type Not Supported

{
"stat": "invalid combination of bank/beneficiary currency parameters or payment type not supported for beneficiary"
}

Error Code 545 - One or More JSON Attributes Missing or Malformed

{
"stat": "one or more JSON attributes missing or malformed: currency_type"
}

Error Code 546 - One or More JSON Attributes Failed Validation

{
"stat": "contents of one or more JSON attributes failed validation"
}

POST Lock in an Exchange Rate for a Payment Transaction

You lock in a currency exchange rate for your transaction by sending an HTTP POST request with the required information to the /api/book endpoint.

Notes regarding bookings:

If /connect is called between the /book and /authorize call, the session will be reset and the quoted rate will be refreshed.

The recommended maximum number of transactions that you can book is 150 per request. The max number of transactions for a single beneficiary is 100 transactions per request - ONLY the first transaction will be submitted

Endpoint: /book

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`bank_id_from`	The ID of the bank from which the funds originate. This is the bank's own account ID.	Integer	-	Yes	-
`bank_pay_type`	The payment type. Possible values are: 1: Direct Debit/ACH - 2: Wire Transfer - 3: Withdrawal - 21: Reverse Wire	Integer	-	Yes	-
`use_client_id`	A flag to indicate whether the user is passing in the standard beneficiary ID: 0, or custom client ID: 1.	Integer	-	No	0
`beneficiary_data`	A list of beneficiary payment attribute groups.	List	-	Yes	-
`beneficiary_data_id`	The ID of the beneficiary to whom the payment is to be made. This can be either the beneficiary ID or the client ID. Please note that if sending a request involving multiple beneficiaries the formation for this field must remain consistent. i.e. all beneficiary IDs or all client IDs. If sending the beneficiary ID, please send as an integer, if sending as client ID send as a string.	Varchar/Integer	-	Yes	1
`beneficiary_data_currency`	The ID of the currency corresponding to the beneficiary account. Accounts can have more than one currency. See View Beneficiary Accounts to retrieve this information. To pay in a fixed domestic currency, put switch. before the currency value eg. switch.EUR	Varchar	5	Yes	-
`beneficiary_data_amount`	The amount of money to send to the beneficiary in their currency.	Decimal	11,2	Yes	0
`beneficiary_data_user_reference`	A reference to be sent to the receiving bank. Note '&' cannot be used in the field please us 'and' or '&'	Varchar	18	Yes	-
`beneficiary_data_transfer_reason`	The transfer reason. Typically set to the default value, Bill payment. See the Transfer Reasons section for more information.	Varchar	20	Yes	Bill Payment
`beneficiary_data_transfer_reason_id`	The transfer reason code. Typically set to the default value 7 (Bill payment). See the Transfer Reasons section for more information.	Varchar	20	Yes	7
`beneficiary_data_value_date`	A date given in the format of YYYY-MM-DD, on which the funds are to be in the beneficiary bank account. This is either enabled and therefore becomes mandatory or is not enabled and is not taken into consideration.	Varchar	-	No	-
`reconciliation_id`	An optional custom identifier for client-side reconciliation.	Varchar	52	No	-
`client_transaction_id`	An optional custom identifier for transactions supplied by the user. This is a client-specific, unique reference. Must be at least 8 characters long and not start with "0", "T", "t", "B", or "b".	Varchar	100	Yes	-
`beneficiary_data_payment_type`	The type of payment rail, the beneficiary is to be paid by. Possible values:60 - ACH Same Day,20 - ACH Next Day,2 - Domestic Wire,63 - International Wire,64 - Instant	Integer	-	No	AC

Example Request

An example of the JSON structure in the request is as follows:

{
"bank_id_from": 63645,
  "bank_pay_type": 2,
  "use_client_id": 0,
  "beneficiary_data": [
      {
          "beneficiary_data_id": 220865,
          "beneficiary_data_currency": "EUR",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 8",
          "beneficiary_data_transfer_reason": "Bill Payment",
          "beneficiary_data_transfer_reason_id": "7",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "client_transaction_id": "123456",
          "beneficiary_data_payment_type": "20"
      },
      {
          "beneficiary_data_id": 199641,
          "beneficiary_data_currency": "NOK",
          "beneficiary_data_amount": 100,
          "beneficiary_data_user_reference": "api ref 9",
          "beneficiary_data_transfer_reason": "Expense Reimbursement",
          "beneficiary_data_transfer_reason_id": "30",
          "beneficiary_data_value_date": "2022-01-11",
          "reconciliation_id": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "client_transaction_id": "123ABC",
          "beneficiary_data_payment_type": "20"
      }
]
}

Response Body Payload Example

If the request is successful, the service responds with details of the booking.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`uid`	The internal unique ID of the beneficiary.	Integer
`payee_name`	The name of the payee.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`service_type`	The type of the service.	Varchar
`bene_payment_type`	The type of the payment.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`conversion_meta`	A container for conversion details.	-
`conversion`	Sub-containers for conversion details.	-
`inverse`	Sub-containers for conversion details.	-
`from`	The type of the payment.	Varchar
`to`	The currency to convert to.	Varchar
`input`	The amount to convert.	Decimal/Float
`output`	The exchange rate.	Decimal
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee	Decimal
`transfer_reason`	The reason for the transfer, typically 7 (Bill Pay).	Varchar
`transfer_reason_id`	The ID of the transfer reason.	Varchar
`reference`	A reference for the transaction.	Varchar
`forbidden`	A flag that indicates if the transaction can be processed or not. A value of 0 indicates that the transaction can be processed normally. A value of 1 indicates that the transaction cannot be processed.	Varchar
`alerts`	A message to draw the user's attention to a possible anomaly that the user should check.	Varchar
`transaction_id`	The ID assigned to the transaction.	Varchar
`user_id`	The client_transaction_id that was passed in the request. If not passed, value will be null	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 1000000.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "rail_type": "ACH Next Day",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          },
          "inverse": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          }
      },
      "amount_from_bef_fee": "EUR 1000000.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 1000115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 9",
      "forbidden": "1",
      "alerts": "Further information is required to book this amount.Please contact funds@transfermate.com in order to continue with your booking.",
      "user_uid": null
}
]

The JSON structure in a successful response is as follows:

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 100.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
            "to": "EUR",
              "input": 1,
              "output": 1
          },
          "inverse": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          }
      },
      "amount_from_bef_fee": "EUR 100.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 8",
      "forbidden": "0",
      "alerts": "Please note for same currency payments outside the SEPA area, the receiving bank may charge a receiving fee to the receiver.For more info click www.transfermate.com/chat,,NB: You have submitted a transaction with the same parameters (amount, currency and beneficiary details) in the last 24 hours. To ensure this is not a duplicate payment, check previous submissions on your Accounts Summary.",
      "transaction_id": "T684736",
      "user_uid": "123456"
},
{
      "uid": 199641,
      "payee_name": "Norwegian Supplier",
      "foreign_ammount": "NOK 100.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 9.37072 NOK,1 NOK = 0.10672 EUR",
      "conversion_meta": {
          "conversion": {
            "from": "EUR",
            "to": "NOK",
            "input": 1,
              "output": 9.37072
          },
          "inverse": {
            "from": "NOK",
              "to": "EUR",
              "input": 1,
              "output": 0.10672
          }
      },
      "amount_from_bef_fee": "EUR 10.67",
      "fee": "5.00",
      "total_trans_amount_from": "EUR 15.67",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "None",
      "reference": "api ref 9",
      "forbidden": "0",
      "alerts": "NB: You have submitted a transaction with the same parameters (amount, currency and beneficiary details) in the last 24 hours. To ensure this is not a duplicate payment, check previous submissions on your Accounts Summary.",
      "transaction_id": "T684737",
      "user_uid": null
}
]

Example Error Responses

If the lock-in exchange rate request is not successful, the service responds with an error code, rejects the request, and does not lock in the exchange rate. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION
`stat`	A status message that describes the error encountered.	Varchar
`ID`	The ID of the error message.	Varchar
`description`	A descirption of the error.	Varchar

Error Code 542 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

[
{
      "uid": 220865,
      "payee_name": "Maginot Line",
      "foreign_ammount": "EUR 1000000.00",
      "service_type": "Standard",
      "bene_payment_type": "Wire Transfer",
      "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
      "conversion_meta": {
          "conversion": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          },
          "inverse": {
              "from": "EUR",
              "to": "EUR",
              "input": 1,
              "output": 1
          }
      },
      "amount_from_bef_fee": "EUR 1000000.00",
      "fee": "15.00",
      "total_trans_amount_from": "EUR 1000115.00",
      "transfer_reason": "Bill Pay",
      "transfer_reason_id": "Bill payment",
      "reference": "api ref 9",
      "forbidden": "1",
      "alerts": "Further information is required to book this amount.Please contact funds@transfermate.com in order to continue with your booking.",
      "user_uid": null
}
]

Error Code 545 - One or More JSON Attributes Missing or Malformed

{
"stat": "one or more JSON attributes missing or malformed: currency_type"
}

Error Code 546 - One or More JSON Attributes Failed Validation

{
"stat": "contents of one or more JSON attributes failed validation"
}

Error Code 404 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

{
"stat": "Beneficiary does not exist or has been disabled"
}

POST Authorize One or More Payment Transactions

You authorize one or more payment transactions by sending an HTTP POST request with the required information to the /authorize endpoint.

All transactions to be authorized must be from the same source bank account. If there are transactions with different source bank accounts sent in the call none of the tranactions will be authorized.

Note: Including metadata has an impact on how quickly the request is processed.

Endpoint: /authorize

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`login_terms_of_use`	A flag to indicate that the user has accepted the terms and conditions. The agreed terms and conditions should be shown to all users prior to payment authorization.	Bit	1	Yes	1
`approve`	Indicates the action to take. Set to 1 to approve payments. Set to 0 to cancel payments.	Bit	1	Yes	-
`auth_trans_ids`	A list of transaction IDs to be approved/cancelled. NOTE: client_transaction_id cannot be used when cancelling a payment.	List	-	Yes	-
`metadata`	A flag to include payment transaction metadata with the authorization request. Set to 1 to include metadata. Set to 0 to exclude metadata. Including metadata has an impact on how quickly the request is processed.	Boolean	-	No	0

Example Request

An example of the JSON structure in the request is as follows (TIDs):

{
"login_terms_of_use": 1,
  "approve": 1,
  "auth_trans_ids": [
      "T784880",
      "T784881",
      "TXXXXX"
  ],
  "metadata": 1
}

Response Body Payload Example

If the request is successful, the service responds with details of the authorize request.

The response body includes the following parameters:

Field	Description	Type
`transactions`	A list of one or more payment transactions.	List
`benef_id`	The ID of the beneficiary.	Varchar
`payee_name`	The name of the beneficiary.	Varchar
`t_datetime_submitted`	The date and time at which the transaction was submitted.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`client_id`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar
`client_data`	A custom statement associated with the payment transaction. (reconciliation_id)	Varchar
`user_uid`	The client_transaction_id which may be passed in at the time of booking. This is a unique alpha-numeric string to identify the transaction.	Varchar
`unknown_tids`	A list of erroneous payment transaction IDs that the system does not recognized.	List
`metadata`	A list of metadata associated with the batch payment transaction.	List
`batch_sum_details`	A text description that summarizes the batch transaction.	Varchar
`usr_bank_from_data`	A text description that summarizes the source bank account information.	Varchar
`transfer_type`	The type of payment transaction. (Wire transfer only)	Varchar
`currency`	The currency of the payment transaction. (Wire transfer only)	Varchar
`amount`	The payment transaction amount with currency indicated.(Wire transfer only)	Varchar
`particular`	A custom statement associated with the batch payment transaction.(Wire transfer only)	Varchar
`account_name`	The name of the source bank account.(Wire transfer only)	Varchar
`bank_name`	The name of the source bank.(Wire transfer only)	Varchar
`bank_country`	The country of the source bank.(Wire transfer only)	Varchar
`account_number`	The source bank account number.(Wire transfer only)	Varchar
`transit_code or sort_code`	The transit code or sort code. See Transit Code Values for possible values.(Wire transfer only)	Varchar
`swift_bic`	The SWIFT or Bank Identification Code (BIC) of the source bank account.(Wire transfer only)	Varchar
`aba_number`	The ABA Routing number, USA only (Wire transfer only)	Varchar
`ref_number`	The reference number of the batch in which multiple payment transactions are included for approval.(Wire transfer only)	Varchar

Example Success Response

The JSON structure in a successful response with a Wire Transfer (bank_pay_type: 2)

{
"transactions": [
      {
          "benef_id": "231426",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784880",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_id": null,
          "client_data": "Some Reconcile Ident",
          "user_uid": "123456"
      },
      {
          "benef_id": "231427",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784881",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_id": null,
          "client_data": "Some Reconcile Ident 2",
          "user_uid": "567891"
      }
  ],
  "unknown_tids": [
      "TXXXXX"
  ],
  "metadata": [
      {
          "batch_sum_details": "Domestic Amount: CAD 5,456.53 Reference Number: B544748",
          "usr_bank_from_data": "Wire Transfer from your bank account: Bank Name: TORONTO DOMINION BANK Bank Country: Canada Account Number: 1xxxxxx-xx11 Transit Number & Institution Number: 0xx-xxxx-xx60 SWIFT/BIC Code: Txx-xxxx-xxOR Currency: CAD",
          "transfer_type": "Country Local Bank Transfer",
          "currency": "CAD",
          "amount": "CAD 5456.53",
          "particular": "Mr Test Test",
          "account_name": "Interpay Ltd",
          "bank_name": "ROYAL BANK OF CANADA",
          "bank_country": "Canada",
          "account_number": "1071596",
          "sort_code": "000306702",
          "swift": "ROYCCAT2",
          "ref_number": "B544748"
      }
]
}

The JSON structure in a successful response with a Direct Debit/ACH (bank_pay_type: 1)

{
"transactions": [
      {
          "benef_id": "231428",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:53:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 250",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Direct Debit",
          "batch_ref_num": "B544748",
          "ref_number": "T784888",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_id": null,
          "client_data": "Some Reconcile Ident 3",
          "user_uid": "5789"
      },
      {
          "benef_id": "231429",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:54:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 250",
          "tran_type": "Direct Debit",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784889",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_id": null,
          "client_data": "Some Reconcile Ident 4",
          "user_uid": "9874"
      }
  ],
  "unknown_tids": [
      "TXXXXX"
  ],
  "metadata": [
      {
          "batch_sum_details": "Domestic Amount: CAD 5,456.53 Reference Number: B544748",
          "usr_bank_from_data": "Wire Transfer from your bank account: Bank Name: TORONTO DOMINION BANK Bank Country: Canada Account Number: 1xxxxxx-xx11 Transit Number & Institution Number: 0xx-xxxx-xx60 SWIFT/BIC Code: Txx-xxxx-xxOR Currency: CAD"
      }
]
}

The returned JSON structure for a cancelled payment request is as follows

{
"transactions": [
      {
          "benef_id": "220865",
          "payee_name": "Maginot Line",
          "t_datetime_submitted": "2022-01-11 12:27:00",
          "foreign_amount": "EUR 328.00",
          "currency_rate_per_unit": "0.66060",
          "amount_from_bef_fee": "CAD 496.52",
          "fee": "15.00",
          "total_trans_amount_from": "CAD 511.52",
          "reference": "api ref 99",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T760840",
          "payment_status": "Cancelled by approver",
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": "Test reconcile 3",
          "user_uid": "567891"
      },
      {
          "benef_id": "197279",
          "payee_name": "Singapore Beneficiary 1",
          "t_datetime_submitted": "2022-01-11 12:27:00",
          "foreign_amount": "USD 428.00",
          "currency_rate_per_unit": "0.77224",
          "amount_from_bef_fee": "CAD 554.23",
          "fee": "15.00",
          "total_trans_amount_from": "CAD 569.23",
          "reference": "api ref 98",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T760841",
          "payment_status": "Cancelled by approver",
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": "Test reconcile 3",
          "user_uid": "123456"
      }
]
}

Example Error Responses

If the lock-in exchange rate request is not successful, the service responds with an error code, rejects the request, and does not lock in the exchange rate. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 544 - Terms and Conditions Not Agreed

{
"stat": "terms and conditions not signed"
}

Error Code 547 - None of the Submitted Transaction IDs Are Recognized

{
"stat": "no valid transactions ids submitted"
}

POST Get Global/Virtual Convert Exchange Rate for Review

You can retrieve and review a convert exchange rate by sending an HTTP POST request with the required information to the /convert_rate_quote endpoint.

Endpoint: /convert_rate_quote

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id_from`	The ID of the bank from which the funds originate.	Varchar	-	Yes	-
`amount_from`	The amount of funds to be converted.	Varchar	-	Yes	-
`user_bank_id_to`	The ID of the bank from which the funds are to sent	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"user_bank_id_from": "135066",
"amount_from": 1,
"user_bank_id_to": "135092"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`currency_from`	The currency of which the funds originated	Varchar
`amount_from`	The value of the funds being converted in the currency it originated.	Varchar
`currency_to`	The currency of which the funds were moved to.	Varchar
`amount_to`	The value of the funds after conversion.	Varchar
`rate`	The exchance rate at which the funds where converted.	Varchar
`reverse_rate`	The inverse exchance rate at which the funds where converted.	Varchar
`estimated_rate_expiry`	An estimated time at which the rate will expire	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
    "currency_from": "eur",
    "amount_from": "1.00",
      "currency_to": "usd",
      "amount_to": "1.11",
      "rate": "0.89853",
      "reverse_rate": "1.11293",
      "estimated_rate_expiry": "2022-01-20 13:52:32"
  }
]

Example Error Responses

If the get and review exchange rate request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 404 - Not Found

{
"stat": "user_bank_id_from 394530 does not exist for this account"
}

Error Code 404 - Not Found

{
"stat": "user_bank_id_to 394530 does not exist for this account"
}

Error Code 422 - Unprocessable Entity

{
"stat": "amount_from: Please enter a valid number"
}

Error Code 552 -

{
"stat": "One or more JSON attributes missing or malformed: 'user_bank_id_to'"
}

POST Get Global/Virtual Convert Exchange Rate for Review V2

You can retrieve and review a convert exchange rate by sending an HTTP POST request with the required information to the v2/convert_rate_quote endpoint.

Endpoint: /v2/convert_rate_quote

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id_from`	The ID of the bank from which the funds originate.	Varchar	-	Yes	-
`amount_from`	The amount of funds to be converted.	Varchar	-	No	-
`amount_to`	The amount of funds to be converted to	Varchar	-	No	-
`user_bank_id_to`	The ID of the bank from which the funds are to sent	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"user_bank_id_from": "152220",
  "amount_from": "100.00",
  "amount_to": null,
  "user_bank_id_to": "208988"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`currency_from`	The currency of which the funds originated	Varchar
`amount_from`	The value of the funds being converted in the currency it originated.	Varchar
`currency_to`	The currency of which the funds were moved to.	Varchar
`amount_to`	The value of the funds after conversion.	Varchar
`rate`	The exchance rate at which the funds where converted.	Varchar
`reverse_rate`	The inverse exchance rate at which the funds where converted.	Varchar
`estimated_rate_expiry`	An estimated time at which the rate will expire	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "currency_from": "EUR",
      "amount_from": "100.00",
      "currency_to": "USD",
      "amount_to": "106.68",
      "rate": "0.93737",
      "reverse_rate": "1.06682",
      "estimated_rate_expiry": "2024-03-07 10:42:34"
  }
]

Example Error Responses

If the get and review exchange rate request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 404 - Not Found

{
"stat": "user_bank_id_from 394530 does not exist for this account"
}

Error Code 404 - Not Found

{
"stat": "user_bank_id_to 394530 does not exist for this account"
}

Error Code 422 - Unprocessable Entity

{
"stat": "amount_from: Please enter a valid number"
}

Error Code 552 -

{
"stat": "One or more JSON attributes missing or malformed: 'user_bank_id_to'"
}

POST Convert Global/Virtual Account Funds

You can convert funds from a Global/Virtual account to another currency by sending an HTTP POST request with the required information to the /convert endpoint.

Endpoint: /convert

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id_from`	The ID of the bank from which the funds originate.	Varchar	-	Yes	-
`amount_from`	The amount of funds to be converted.	Varchar	-	Yes	-
`user_bank_id_to`	The ID of the bank from which the funds are to be sent.	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"user_bank_id_from": "135066",
"amount_from": 1,
"user_bank_id_to": "135092"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`currency_from`	The currency of which the funds originated	Varchar
`amount_from`	The value of the funds being converted in the currency it originated.	Varchar
`currency_to`	The currency of which the funds were moved to.	Varchar
`amount_to`	The value of the funds after conversion.	Varchar
`rate`	The exchance rate at which the funds where converted.	Varchar
`reverse_rate`	The inverse exchance rate at which the funds where converted.	Varchar
`ref_number`	Transaction ID for the convert transaction	Varchar
`batch_ref_num`	Batch number for the convert transaction	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "currency_from": "eur",
      "amount_from": "1.00",
      "currency_to": "usd",
      "amount_to": "1.11",
      "rate": "0.89853",
      "reverse_rate": "1.11293",
      "ref_number": "T784880",
      "batch_ref_num": "B544748"
  }
]

Example Error Responses

If the convert request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 404 - Not Found

{
"stat": "user_bank_id_from 394530 does not exist for this account"
}

Error Code 404 - Not Found

{
"stat": "user_bank_id_to 394530 does not exist for this account"
}

Error Code 422 - Unprocessable Entity

{
"stat": "amount_from: Please enter a valid number"
}

Error Code 422 - Unprocessable Entity

{
"stat": "Insufficient Funds"
}

Error Code 552 -

{
"stat": "One or more JSON attributes missing or malformed: 'user_bank_id_to'"
}

POST Convert Global/Virtual Account Funds V2

Request Body Payload Example – Please note that amount_to or amount_from will be mandatory.The client_transaction_id will provide uniqueness for each convert and cannot be re-used.

Endpoint: /v2/convert

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`user_bank_id_from`	The ID of the bank from which the funds originate.	Varchar	-	Yes	-
`amount_from`	The amount of funds to be converted.	Varchar	-	Yes	-
`amount_to`	The amount of funds to be converted to	Varchar	-	Yes	-
`user_bank_id_to`	The ID of the bank from which the funds are to be sent.	Varchar	-	Yes	-
`client_transaction_id`	An optional custom identifier for transactions supplied by the user. This is a client specific unique reference. Must be atleast 8 character long and not start with "0", "T", "t", "B", or "b".	Varchar	100	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"user_bank_id_from": "152220",
  "amount_from": 100,
  "amount_to": null,
  "user_bank_id_to": "208988",
  "client_transaction_id": "12435598034ur908wfe823491yrn23914rg431"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`currency_from`	The currency in which the funds originated	Varchar
`amount_from`	The value of the funds being converted into the currency they originated.	Varchar
`currency_to`	The currency in which the funds were moved.	Varchar
`amount_to`	The value of the funds after conversion.	Varchar
`rate`	The exchange rate at which the funds were converted.	Varchar
`reverse_rate`	The inverse exchange rate at which the funds were converted.	Varchar
`ref_number`	Transaction ID for the conversion transaction	Varchar
`batch_ref_num`	Batch number for the conversion transaction	Varchar
`user_uid`	The client transaction ID that was passed in the request. If not passed, the value will be null	Varchar
`estimated_rate_expiry`	An estimated time at which the rate will expire	Varchar
`conversion_rate`	Тhe exchange rate at which the funds were converted	Varchar
`inverse_rate`	The inverse exchange rate at which the funds were converted	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
"currency_from": "DKK",
"amount_from": "2041.59",
"currency_to": "USD",
"amount_to": "320.57",
"rate": "6.36862",
"reverse_rate": "0.15702",
"estimated_rate_expiry": "2025-09-09 09:17:02",
"conversion_rate": "0.15702",
"inverse_rate": "6.36862",
"ref_number": "T14280829",
"batch_ref_num": "B3417744",
"user_uid": "payment-ref-testing-320h"
}
]

Example Error Responses

If the convert request is not successful, the service responds with an error code, rejects the request, and does not retrieve the exchange rate information. Some example error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 404 - Not Found

{
"is_successful": false,
  "messages": {
      "stat": "user_bank_id_from 394530 does not exist for this account"
  }
}

Error Code 404 - Not Found

{
"is_successful": false,
  "messages": {
      "client_transaction_id": "Please enter correct information! "
  },
  "stat": "User UID must be unique containing only Latin letters A-Za-z, 0-9 numbers, -, _, . max lenght 100"
}

Error Code 404 - Not Found

{
"stat": "user_bank_id_to 394530 does not exist for this account"
}

Error Code 422 - Unprocessable Entity

{
"is_successful": false,
  "messages": {
  "amount_from": "Please enter a valid number",
      "ga_rate_calc_reverse": "Please enter a valid number"
  }
}

Error Code 422 - Unprocessable Entity

{
"is_successful": false,
  "messages": {
      "stat": "Insufficient Funds"
  }
}

Error Code 552 -

{
"is_successful": false,
  "messages": {
      "stat": "One or more JSON attributes missing or malformed: 'amount_from'"
  }
}

POST Get Transaction Summary

You retrieve a summary of transactions by sending an HTTP POST request with the required information to the /get_summary endpoint.

Endpoint: /get_summary

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency_from`	Specify a currency ID to filter transactions that have only used a specific from currency.	Varchar	10	No	-
`bank_id_from`	Specific a home/company bank ID to filter transactions for that specific bank account.	Integer	-	No	-
`ref_number`	Specify a batch (B) or transaction (T) number to filter transactions associated with that B or T number. If included, this field cannot be left blank. Must contain a T or B followed by at least 6 digits.	Varchar	20	No	-
`username`	Specify a user name to filter transactions associated with that user.	Varchar	20	No	-
`beneficiary`	Specific a beneficiary ID to filter transactions for that beneficiary.	Integer	-	No	-
`reconciliation_id`	Apply a full or partial case-sensitive search on the stored client_data field. This field is used in combination with other search parameters (such as bank_id_from or beneficiary) for optimum performance.	Varchar	-	No	-
`date_from`	Specify a date (in the format dd/mm/yyyy) to filter transactions that occurred after that date.	Date	-	No	-
`date_to`	Specify a date (in the format dd/mm/yyyy) to filter transactions that occurred before that date.	Date	-	No	-
`transactions_statuses`	Specify one or more status values to use to filter transactions. See Payment Status Code for possible values.	List/Integer	-	No	-
`client_transaction_id`	Specify a client_transaction_id to filter transactions associated with that client_transaction_id. If this field is used, other fields in the request will be ignored. Max number of IDs that can be input is 30. If you require the full list, please use the batch number.	Varchar	-	Yes	-

Example Request

An example of a request with just the ref_number:

{
"ref_number": "B544748"
}

An example of a request with multiple TID's:

{
"ref_number": "T3587618, T3587619, T3587620"
}

An example of a request with date, to and from, and the id of the origin bank:

{
"bank_id_from": "45240",
"date_from": "01/01/2022",
"date_to": "30/01/2022"
}

An example of a request searching for specific status:

{
"transactions_statuses": [
      1,
      6
  ]
}

An example of a request searching for ONE specific status:

{
"transactions_statuses": 6
}

An example of a request searching for a certain client:

{
"client_transaction_id": "12345678"
}

Response Body Payload Example

If the request is successful, the response includes the following parameters:

FIELD	DESCRIPTION	TYPE
`transactions`	A list of one or more payment transactions.	List
`benef_id`	The ID of the beneficiary.	Varchar
`payee_name`	The name of the beneficiary.	Varchar
`t_datetime_submitted`	The date and time at which the transaction was submitted.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`client_data`	A custom statement associated with the payment transaction.	Varchar
`client_id`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar
`user_uid`	The client_transaction_id which may be passed in at the time of booking. This is a unique alpha-numeric string to identify the transaction.	Varchar
`metadata`	A list of metadata associated with the batch payment transaction.	List
`batch_sum_details`	A text description that summarizes the batch transaction.	Varchar
`usr_bank_from_data`	A text description that summarizes the source bank account information.	Varchar
`transfer_type`	The type of payment transaction.	Varchar
`currency`	The currency of the payment transaction.	Varchar
`amount`	The payment transaction amount with currency indicated.	Varchar
`particular`	A custom statement associated with the batch payment transaction.	Varchar
`account_name`	The name of the source bank account.	Varchar
`bank_name`	The name of the source bank.	Varchar
`bank_country`	The country of the source bank.	Varchar
`account_number`	The source bank account number.	Varchar
`transit_code`	The transit code. See Transit Code Values for possible values.	Varchar
`swift`	The SWIFT or Bank Identification Code (BIC) of the source bank account.	Varchar
`ref_number`	The reference number of the batch in which multiple payment transactions are included for approval.	Varchar

Example Success Response

An example of the JSON structure in the response is as follows. In this case, the request returns all transactions that have a batch_ref_num value of B544748.

{
"transactions": [
      {
          "benef_id": "231426",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784880",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident",
          "user_uid": "123456"
      },
      {
          "benef_id": "231427",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784881",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident 2",
          "user_uid": null
      }
  ],
"metadata": [
      {
          "batch_sum_details": "Domestic Amount: CAD 5,456.53 Reference Number: B544748",
          "usr_bank_from_data": "Wire Transfer from your bank account: Bank Name: TORONTO DOMINION BANK Bank Country: Canada Account Number: 1xxxxxx-xx11 Transit Number & Institution Number: 0xx-xxxx-xx60 SWIFT/BIC Code: Txx-xxxx-xxOR Currency: CAD",
          "transfer_type": "Country Local Bank Transfer",
          "currency": "CAD",
          "amount": "CAD 5456.53",
          "particular": "Mr Test Test",
          "account_name": "Interpay Ltd",
          "bank_name": "ROYAL BANK OF CANADA",
          "bank_country": "Canada",
          "account_number": "1071596",
          "transit_code": "000306702",
          "swift": "ROYCCAT2",
          "ref_number": "B544748"
      }
]
}

The following is a second example. In this case, the request returns transactions where the source bank ID, bank_id_from is 45240 and the transaction date is between September 1 and September 30, 2018.

{
"transactions": [
      {
          "benef_id": "231426",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784880",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident",
          "user_uid": null
      },
      {
          "benef_id": "231427",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784881",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident 2",
          "user_uid": null
      },
      {
          "benef_id": "197279",
          "payee_name": "Singapore Beneficiary 1",
          "t_datetime_submitted": "2022-01-11 11:02:00",
          "foreign_amount": "USD 428.00",
          "currency_rate_per_unit": "0.77173",
          "amount_from_bef_fee": "CAD 554.60",
          "fee": "15.00",
          "total_trans_amount_from": "CAD 569.60",
          "reference": "api ref 98",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T763646",
          "payment_status": "Awaiting Authorization",
          "approve": "\n ",
          "payment_status_abrv": "await_auth",
          "client_data": "Immedis59",
          "user_uid": null
      }
  ],
"metadata": []
}

The following is a third example. In this case, the request returns transactions where the status matches the status sent in the call, "transactions_statuses" : [1, 6], Awaiting Funds and Cancelled by approver.

{
"transactions": [
      {
          "benef_id": "489337",
          "payee_name": "Dupe Harryp",
          "t_datetime_submitted": "2022-01-11 09:51:00",
          "foreign_amount": "EUR 103.00",
          "currency_rate_per_unit": "0.88979",
          "amount_from_bef_fee": "USD 115.76",
          "fee": "10.00",
          "total_trans_amount_from": "USD 125.76",
          "reference": "api ref 8",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B954972",
          "ref_number": "T1554224",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_id": "225523",
          "client_data": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "user_uid": null
      },
      {
          "benef_id": "483809",
          "payee_name": "Boris Bene",
          "t_datetime_submitted": "2022-01-11 08:55:00",
          "foreign_amount": "GBP 500.00",
          "currency_rate_per_unit": "0.90358",
          "amount_from_bef_fee": "EUR 553.35",
          "fee": "0.00",
          "total_trans_amount_from": "EUR 553.35",
          "reference": "Bill Payment",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T1554071",
          "payment_status": "Cancelled by approver",
          "approve": null,
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": null,
          "user_uid": null
      }
  ],
"metadata": []
}

The following is a fourth example. In this case, the request returns transactions where the status matches the status sent in the call, "transactions_statuses" : 6, Cancelled by approver.

{
"transactions": [
      {
          "benef_id": "483809",
          "payee_name": "Boris Bene",
          "t_datetime_submitted": "2022-01-11 08:55:00",
          "foreign_amount": "GBP 500.00",
          "currency_rate_per_unit": "0.90358",
          "amount_from_bef_fee": "EUR 553.35",
          "fee": "0.00",
          "total_trans_amount_from": "EUR 553.35",
          "reference": "Bill Payment",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T1554071",
          "payment_status": "Cancelled by approver",
          "approve": null,
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": null,
          "user_uid": null
      }
  ],
"metadata": []
}

Example Error Responses

If the get transaction summary request is not successful, the service responds with an error code, rejects the request, and does not return any transaction data. An example error response is provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 200 - No data

{
"stat": "no data for given search criteria"
}

POST Get Transaction Summary V2

You retrieve a summary of transactions by sending an HTTP POST request with the required information to the /v2/get_summary endpoint.

Endpoint: /v2/get_summary

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRITION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`currency_from`	Specify a currency ID to filter transactions that have only used a specific from currency.	Varchar	10	No	-
`bank_id_from`	Specify a home/company bank ID to filter transactions for that specific bank account.	Integer	-	No	-
`ref_number`	Specify a batch (B) or transaction (T) number to filter transactions associated with that B or T number. If included, this field cannot be left blank. Must contain a T or B followed by at least 6 digits.	Varchar	20	No	-
`username`	Specify a user name to filter transactions associated with that user.	Varchar	20	No	-
`beneficiary`	Specify a beneficiary ID to filter transactions for that beneficiary.	Integer	-	No	-
`reconciliation_id`	Apply a full or partial case-sensitive search on the stored client_data field. This field is used in combination with other search parameters (such as bank_id_from or beneficiary) for optimum performance.	Varchar	-	No	-
`date_from`	Specify a date (in the format dd/mm/yyyy) to filter transactions that occurred after that date.	Date	-	No	-
`date_to`	Specify a date (in the format dd/mm/yyyy) to filter transactions that occurred before that date.	Date	-	No	-
`transactions_statuses`	Specify one or more status values to use to filter transactions. See Payment Status Code for possible values.	List/Integer	-	No	-
`client_transaction_id`	Specify a client_transaction_id to filter transactions associated with that client_transaction_id. If this field is used, other fields in the request will be ignored. The maximum number of IDs that can be input is 30. If you require the full list, please use the batch number.	Varchar	-	Yes	-
`p_number`	Pagination Set to 1 to call page 1, set to 2 to call page 2, etc. Defaults to 1 if not provided.	Integer	-	No	1

Example Request

An example of a request with just the ref_number:

{
"ref_number": "B544748"
}

An example of a request with multiple TID's:

{
"ref_number": "T3587618, T3587619, T3587620"
}

An example of a request with date, to and from, and the id of the origin bank:

{
"bank_id_from": "45240",
"date_from": "01/01/2022",
"date_to": "30/01/2022"
}

An example of a request searching for specific status:

{
"transactions_statuses": [
      1,
      6
  ]
}

An example of a request searching for ONE specific status:

{
"transactions_statuses": [
6
]
}

An example of a request searching for a certain client:

{
"client_transaction_id": "12345678"
}

Response Body Payload Example

If the request is successful, the response includes the following parameters:

FIELD	DESCRIPTION	TYPE
`transactions`	A list of one or more payment transactions.	List
`benef_id`	The ID of the beneficiary.	Varchar
`payee_name`	The name of the beneficiary.	Varchar
`t_datetime_submitted`	The date and time at which the transaction was submitted.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`client_data`	A custom statement associated with the payment transaction.	Varchar
`client_id`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar
`user_uid`	The client_transaction_id which may be passed in at the time of booking. This is a unique alpha-numeric string to identify the transaction.	Varchar
`metadata`	A list of metadata associated with the batch payment transaction.	List
`batch_sum_details`	A text description that summarizes the batch transaction.	Varchar
`usr_bank_from_data`	A text description that summarizes the source bank account information.	Varchar
`transfer_type`	The type of payment transaction.	Varchar
`currency`	The currency of the payment transaction.	Varchar
`amount`	The payment transaction amount with currency indicated.	Varchar
`particular`	A custom statement associated with the batch payment transaction.	Varchar
`account_name`	The name of the source bank account.	Varchar
`bank_name`	The name of the source bank.	Varchar
`bank_country`	The country of the source bank.	Varchar
`account_number`	The source bank account number.	Varchar
`transit_code`	The transit code. See Transit Code Values for possible values.	Varchar
`swift`	The SWIFT or Bank Identification Code (BIC) of the source bank account.	Varchar
`ref_number`	The reference number of the batch in which multiple payment transactions are included for approval.	Varchar

Example Success Response

An example of the JSON structure in the response is as follows. In this case, the request returns all transactions that have a batch_ref_num value of B544748.

{
"is_successful": true,
      "messages": {
      "success": "Action performed successfully."
  },
  "page": 1,
  "pages_count": 1,
  "records_per_page": 30,
  "total_records": 2,
  "csv_export_url": "https://uat-payments-api.transfermate.com/reports?exp=texport_trans_ref_num&tp=csv&dummy=20240307134433",
  "xls_export_url": "https://uat-payments-api.transfermate.com/reports?exp=texport_trans_ref_num&tp=excel&dummy=20240307134433",
  "transactions": [
      {
          "benef_id": "231426",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784880",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident",
          "user_uid": "123456"
      },
      {
          "benef_id": "231427",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784881",
          "payment_status": "Awaiting Funds",
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident 2",
          "user_uid": null
      }
  ],
  "metadata": [
  {
          "batch_sum_details": "Domestic Amount: CAD 5,456.53 Reference Number: B544748",
          "usr_bank_from_data": "Wire Transfer from your bank account: Bank Name: TORONTO DOMINION BANK Bank Country: Canada Account Number: 1xxxxxx-xx11 Transit Number & Institution Number: 0xx-xxxx-xx60 SWIFT/BIC Code: Txx-xxxx-xxOR Currency: CAD",
          "transfer_type": "Country Local Bank Transfer",
          "currency": "CAD",
          "amount": "CAD 5456.53",
          "particular": "Mr Test Test",
          "account_name": "Interpay Ltd",
          "bank_name": "ROYAL BANK OF CANADA",
          "bank_country": "Canada",
          "account_number": "1071596",
          "transit_code": "000306702",
          "swift": "ROYCCAT2",
          "ref_number": "B544748"
      }
]
}

The following is a second example. In this case, the request returns transactions where the source bank ID, bank_id_from is 45240 and the transaction date is between September 1 and September 30, 2018.

{
"transactions": [
      {
          "benef_id": "231426",
          "payee_name": "China Beneficiary 1003",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2106.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2722.62",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2727.62",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784880",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident",
          "user_uid": null
      },
      {
          "benef_id": "231427",
          "payee_name": "China Beneficiary 963",
          "t_datetime_submitted": "2022-01-11 09:52:00",
          "foreign_amount": "USD 2107.00",
          "currency_rate_per_unit": "0.77352",
          "amount_from_bef_fee": "CAD 2723.91",
          "fee": "5.00",
          "total_trans_amount_from": "CAD 2728.91",
          "reference": "tst ref 246",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B544748",
          "ref_number": "T784881",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_data": "Some Reconcile Ident 2",
          "user_uid": null
      },
      {
          "benef_id": "197279",
          "payee_name": "Singapore Beneficiary 1",
          "t_datetime_submitted": "2022-01-11 11:02:00",
          "foreign_amount": "USD 428.00",
          "currency_rate_per_unit": "0.77173",
          "amount_from_bef_fee": "CAD 554.60",
          "fee": "15.00",
          "total_trans_amount_from": "CAD 569.60",
          "reference": "api ref 98",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T763646",
          "payment_status": "Awaiting Authorization",
          "approve": "\n ",
          "payment_status_abrv": "await_auth",
          "client_data": "Immedis59",
          "user_uid": null
      }
  ],
"metadata": []
}

The following is a third example. In this case, the request returns transactions where the status matches the status sent in the call, "transactions_statuses" : [1, 6], Awaiting Funds and Cancelled by approver.

{
"transactions": [
      {
          "benef_id": "489337",
          "payee_name": "Dupe Harryp",
          "t_datetime_submitted": "2022-01-11 09:51:00",
          "foreign_amount": "EUR 103.00",
          "currency_rate_per_unit": "0.88979",
          "amount_from_bef_fee": "USD 115.76",
          "fee": "10.00",
          "total_trans_amount_from": "USD 125.76",
          "reference": "api ref 8",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": "B954972",
          "ref_number": "T1554224",
          "payment_status": "Awaiting Funds",
          "approve": null,
          "payment_status_abrv": "pending",
          "client_id": "225523",
          "client_data": "6300fb78-fa97-4f2a-9b6e-1028199a35ea",
          "user_uid": null
      },
      {
          "benef_id": "483809",
          "payee_name": "Boris Bene",
          "t_datetime_submitted": "2022-01-11 08:55:00",
          "foreign_amount": "GBP 500.00",
          "currency_rate_per_unit": "0.90358",
          "amount_from_bef_fee": "EUR 553.35",
          "fee": "0.00",
          "total_trans_amount_from": "EUR 553.35",
          "reference": "Bill Payment",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T1554071",
          "payment_status": "Cancelled by approver",
          "approve": null,
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": null,
          "user_uid": null
      }
  ],
"metadata": []
}

The following is a fourth example. In this case, the request returns transactions where the status matches the status sent in the call, "transactions_statuses" : 6, Cancelled by approver.

{
"transactions": [
{
          "benef_id": "483809",
          "payee_name": "Boris Bene",
          "t_datetime_submitted": "2022-01-11 08:55:00",
          "foreign_amount": "GBP 500.00",
          "currency_rate_per_unit": "0.90358",
          "amount_from_bef_fee": "EUR 553.35",
          "fee": "0.00",
          "total_trans_amount_from": "EUR 553.35",
          "reference": "Bill Payment",
          "tran_type": "Wire Transfer",
          "bene_payment_type": "Wire Transfer",
          "batch_ref_num": null,
          "ref_number": "T1554071",
          "payment_status": "Cancelled by approver",
          "approve": null,
          "payment_status_abrv": "cancelled_by_approver",
          "client_id": null,
          "client_data": null,
          "user_uid": null
      }
  ],
"metadata": []
}

POST Get Spot Rates

You get spot exchange rates for specific currency pairs by sending an HTTP POST request with the required information to the /get_rate endpoint. The quoted rates market rates without the application of margins or commissions.

Endpoint: /get_rate

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`amount`	The amount to convert.	Decimal	[11,2]	Yes	-
`pairs`	A list of the source and destination currency pairs to obtain conversion information for.	List		Yes	-
`src`	The source currency.	Varchar		Yes	-
`dst`	The destination currency.	Varchar		Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"amount": 1511,
  "pairs": [
      {
          "src": "GBP",
          "dst": "EUR"
      },
      {
          "src": "GBP",
          "dst": "USD"
      },
      {
          "src": "GBP",
          "dst": "HKD"
      },
      {
          "src": "GBP",
          "dst": "NZD"
      }
  ]
}

Response Body Payload Example

If the retrieve spot rates request is successful, the service provides a response.

The response body includes the following parameters:

Field	Description	Type
`curr`	A representation describing the from/to currency pair for a conversion. For example, GBPNZD represents a British pound to New Zealand dollar conversion.	Varchar
`bid`	The bid exchange rate.	Varchar
`bid_dt`	The time associated with the bid exchange rate.	Varchar
`ask`	The ask exchange rate.	Varchar
`ask_dt`	The time associated with the ask exchange rate.	Varchar
`mid`	The middle exchange rate.	Varchar
`mid_dt`	The time associated with the middle exchange rate.	Varchar
`bid_amount_to`	The bid rate amount in the to currency.	Varchar
`bid_amount_from`	The bid rate amount in the from currency.	Varchar
`ask_amount_to`	The ask rate amount in the to currency.	Varchar
`ask_amount_from`	The ask rate amount in the from currency.	Varchar
`mid_amount_to`	The middle rate amount in the to currency.	Varchar
`mid_amount_from`	The middle rate amount in the from currency.	Varchar
`tm_gmt_time`	The time of the conversion in Greenwich Mean Time (GMT).	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "curr": "GBPEUR",
      "bid": "1.13820",
      "bid_dt": "2022-01-11 09:57:19",
      "ask": "1.13832",
      "ask_dt": "2022-01-19 09:57:19",
      "mid": "1.13826",
      "mid_dt": "2022-01-24 09:57:19",
      "bid_amount_to": "1719.82",
      "bid_amount_from": "1511.00",
      "ask_amount_to": "1720.00",
      "ask_amount_from": "1511.00",
      "mid_amount_to": "1719.91",
      "mid_amount_from": "1511.00",
      "tm_gmt_time": "2022-01-11 09:57:19"
  },
  {
      "curr": "GBPUSD",
      "bid": "1.33904",
      "bid_dt": "2022-01-11 09:57:19",
      "ask": "1.33914",
      "ask_dt": "2022-01-19 09:57:19",
      "mid": "1.33910",
      "mid_dt": "2022-01-24 09:57:19",
      "bid_amount_to": "2023.29",
      "bid_amount_from": "1511.00",
      "ask_amount_to": "2023.44",
      "ask_amount_from": "1511.00",
      "mid_amount_to": "2023.38",
      "mid_amount_from": "1511.00",
      "tm_gmt_time": "2022-01-11 09:57:23"
  },
  {
      "curr": "GBPHKD",
      "bid": "10.50636",
      "bid_dt": "2022-01-11 09:57:19",
      "ask": "10.50736",
      "ask_dt": "2022-01-19 09:57:19",
      "mid": "10.50686",
      "mid_dt": "2022-01-24 09:57:19",
      "bid_amount_to": "15875.11",
      "bid_amount_from": "1511.00",
      "ask_amount_to": "15876.62",
      "ask_amount_from": "1511.00",
      "mid_amount_to": "15875.87",
      "mid_amount_from": "1511.00",
      "tm_gmt_time": "2022-01-11 09:57:27"
  },
  {
      "curr": "GBPNZD",
      "bid": "1.90757",
      "bid_dt": "2022-01-11 09:57:19",
      "ask": "1.90825",
      "ask_dt": "2022-01-19 09:57:19",
      "mid": "1.90733",
      "mid_dt": "2022-01-24 09:57:29",
      "bid_amount_to": "2882.34",
      "bid_amount_from": "1511.00",
      "ask_amount_to": "2883.37",
      "ask_amount_from": "1511.00",
      "mid_amount_to": "2881.98",
      "mid_amount_from": "1511.00",
      "tm_gmt_time": "2022-01-11 09:57:27"
}
]

Example Error Responses

If the retrieve spot rates request is not successful, the service responds with an error code, rejects the request, and does not return exchange rate information. Some examples of the error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 403 - Source/Destination currency is not available

{
"stat": "Source/Destination currency is not available"
}

POST Dynamic Pricing

This endpoint will allow Brokers to manipulate either the margin or the exchange rate before authorizing the transaction.

Endpoint: /v2/dynamic_pricing

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRITION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`ref_number`	Specify a transaction (T) number. Must contain a T followed by at least 6 digits.	Varchar	20	yes	-
`margin_applied`		Varchar		No	-
`amount`		Varchar		No	-
`rate`	The exchange rate at which the funds were converted.	Varchar		No	-
`apply`	Do you wish to recalculate or reset the current changes? 1= recalculate or 0 = reset. Accepts: 0, 1, "1", "0", true, false, "true", and"false"	varchar	6	yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"ref_number": "T158831",
"margin_applied": "1.555",
"amount": "",
"rate": ""
"apply": "1" -> 0|1|"1"|"0"|true|false|"true"|"false"
}

Response Body Payload Example

Upon a successful response (where the system recalculates the data successfully), the client will see all transactional data.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`transactions`	A list of one or more payment transactions.	List
`benef_id`	The ID of the beneficiary.	Varchar
`payee_name`	The name of the beneficiary.	Varchar
`t_datetime_submitted`	The date and time at which the transaction was submitted.	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`client_data`	A custom statement associated with the payment transaction.	Varchar
`client_id`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar
`user_uid`	The client_transaction_id which may be passed in at the time of booking. This is a unique alpha-numeric string to identify the transaction.	Varchar
`metadata`	A list of metadata associated with the batch payment transaction.	List
`batch_sum_details`	A text description that summarizes the batch transaction.	Varchar
`usr_bank_from_data`	A text description that summarizes the source bank account information.	Varchar
`transfer_type`	The type of payment transaction.	Varchar
`currency`	The currency of the payment transaction.	Varchar
`amount`	The payment transaction amount with currency indicated.	Varchar
`particular`	A custom statement associated with the batch payment transaction.	Varchar
`account_name`	The name of the source bank account.	Varchar
`bank_name`	The name of the source bank.	Varchar
`bank_country`	The country of the source bank.	Varchar
`account_number`	The source bank account number.	Varchar
`transit_code`	The transit code. See Transit Code Values for possible values.	Varchar
`swift`	The SWIFT or Bank Identification Code (BIC) of the source bank account.	Varchar
`ref_number`	The reference number of the batch in which multiple payment transactions are included for approval.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

{
"is_successful": true,
"messages": {
"success": "Action performed successfully."
},
"transactions": [
{
"t_datetime_auth": "",
"benef_id": "380",
"payee_name": "Bene403",
"t_datetime_submitted": "2025-09-18 09:49:00",
"foreign_amount": "USD 1113.00",
"currency_rate_per_unit": "1.16381",
"amount_from_bef_fee": "EUR 956.34",
"fee": "0.00",
"fee_type": "IOF",
"total_trans_amount_from": "EUR 959.97\nMarginID# 2534\nMargin %: 1.50000\nBank FX Margin ID# \nBank FX Margin %: \nFeeID# 26358\nFee: 0.00\nFee %: 0.38000\nFee Add: 0.38\nFee type: IOF\nMargin override ID#: \nBID override: \nBID before override: \nDate before override: \nRate type: bid\nBuy now (BARX): 2 | BARX #2995\nRate per unit bef mrg: 1.18219\nAmount from bef fee, bef mrg: 941.47\nAmount to bef fee, bef mrg: 1113.00\nAmount margin save: 0.00\nRate round decimal point: 5\nRate real date: 2025-09-18 11:44:40",
"reference": "Ref: Fingal County",
"tran_type": "Wire Transfer",
"bene_payment_type": "Domestic Wire",
"rail_type": "Domestic Wire",
"value_date": "12/12/2025",
"batch_ref_num": null,
"ref_number": "T158834",
"payment_status": "Awaiting Authorization",
"approve": "158834",
"payment_status_abrv": "await_auth",
"client_id": null,
"client_data": null,
"user_uid": null,
"users_authorised": "",
"vop_verification_status_txt": "Null",
"vop_name_found": "",
"vop_date_added": "",
"margin_applied": "1.55500",
"fee_fixed": "3.63"
}
]
}

Example Error Responses

The JSON structure for the error responses includes the following parameters.

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 522- Bad request, or when the field "apply" is missing from the request.

{
"is_successful": false,
"messages": {
"stat": "One or more JSON attributes missing or malformed: "apply"
}
}

Error Code 521 - Bad request when "apply" aluves is not valid.

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
"ID": "apply",
"description": "Please enter correct information!"
}
]
}

Error Code 521 - Bad request when Functionality is not available for the user.

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
"ID": "db_action",
"description": "Functionality not enabled, please contact your account manager."
}
]
}

Error Code 521 - Bad request when an Invalid "ref_number" OR the transaction is not editable

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
"ID": "ref_number",
"description": "Invalid ID provided"
}
]
}

Error Code 521 - Bad request when an Invalid margin percent is provided -> for example "margin_applied": "Test"

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
ID": "margin_applied",
"description": "Please enter a valid number"
}
]
}

Error Code 521 - Bad request when an Invalid rate is provided

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
ID": "rate",
"description": "Please enter a valid number"
}
]
}

Error Code 521 - Bad request when MULTIPLE request parameters were provided

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
ID": "db_action",
"description": "Only one value can be changed"
}
]
}

Error Code 521 - Bad request when Restricted input is submitted. For example, we first edit the "margin_applied" field. Then we try to submit a second time with the "amount" parameter

{
"is_success": false,
"messages": [],
"global_errors": [],
"input_errors": [
{
ID": "db_action",
"description": "Restricted input submitted"
}
]
}

Performing Large Batch Payment Transactions

Using the Payments API, you create large batch payment transaction by using the following steps.

Please contact your partner manager if you would like access to this functionality.

Quote Batch New
This operation creates the batch booking and is the start of the process. Creating the batch will require the funding account ID, the funding account type and the currency of the batch.
Quote Batch Add
Once you have created the batch, you will then be required to add transactions to the batch. All these transactions are required to be the same currency as the batch. This step creates a transaction record in the TransferMate system. This can be done multiple times as you create the batch.
Quote Get Rate
This step provides the FX conversion rate for the entire batch. The returned rate remains valid for 90 seconds between the lock-in time and authorization
Quote Authorize
Authorizing or cancelling the entire batch.

In addition to the steps provided above, the Payments API provides other useful features that relate to transactions:

Quote Summary
Using this feature, you can retrieve details of a batch that was booked and authorized utilizing the Quote Batch functionality. This response is paginated and with a default of 30 transaction records per page but can be set to 50 or 100 records per page.

POST Create a New Batch

You can create a new Quote Batch by sending an HTTP POST request with the required information to the /quote_batch_new endpoint.

Endpoint: /quote_batch_new

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`bank_id_from`	The ID of the bank from which the funds originate. This is the bank 's own account ID.	Integer	-	Yes	-
`bank_pay_type`	The payment type. Possible values are: 1: Direct Debit/ACH - 2: Wire Transfer - 3: Withdrawal - 21: Reverse Wire	Integer	-	Yes	-
`currency_to_quote`	ISO Currency of the Batch – The Batch can only contain transactions in this currency	Varchar	3	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"bank_id_from": 94872,
"bank_pay_type": 2,
"currency_to_quote": "USD"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_success`	Either True or False If false an error message will be populated in the messages field	Integer
`messages`	Reason the call failed	Varchar
`quote_batch_id`	The Quote Batch ID that will be used in when adding transactions to the batch, getting a quote and authorising/cancelling the batch	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "is_success": true,
      "messages": {},
      "quote_batch_id": "QB1604210"
  }
]

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 400 - Incorrect bank_id_from

{
"is_success": false,
  "messages": {
      "bank_id_from": "Bank doesn't exist or is not active!"
  }
}

Error Code 400 - Incorrect bank_pay_type

{
"is_success": false,
  "messages": {
      "bank_id_from": "Bank doesn't exist or is not active!",
      "bank_pay_type": "Please enter correct information!"
  }
}

Error Code 400 - Incorrect currency

{
"is_success": false,
"messages": {
"currency_to_quote": "Field currency_to_quote must be a valid ISO currency!"
}
}

POST Quote Batch Add

Once you have created the batch, you will then be required to add transactions to the batch. All these transactions are required to be the same currency as the batch. This step creates a transaction record in the TransferMate system. This can be done multiple times as you create the batch.

Endpoint: /quote_batch_add

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`use_client_id`	A flag to indicate whether the user is passing in the standard beneficiary ID: 0, or custom client ID: 1.	Integer	-	No	0
`beneficiary_data`	A list of beneficiary payment attribute groups.	List	-	Yes	-
`beneficiary_data_id`	The ID of the beneficiary to whom the payment is to be made. This can be either the beneficiary ID or the client ID. Please note that if sending a request involving multiple beneficiaries the formation for this field must remain consistent. i.e. all beneficiary IDs or all client IDs.	Varchar	-	Yes	1
`beneficiary_data_currency`	The ID of the currency corresponding to the beneficiary account. Accounts can have more than one currency. See View Beneficiary Accounts to retrieve this information. To pay in a fixed domestic currency, put switch. before the currency value eg. switch.EUR	Varchar	5	Yes	-
`beneficiary_data_amount`	The amount of money to send to the beneficiary in their currency.	Decimal	11,2	yes	0
`beneficiary_data_user_reference`	A reference to be sent to the receiving bank. Note '&' cannot be used in the field please us 'and' or '&'	Varchar	18	yes	-
`beneficiary_data_transfer_reason`	The transfer reason. Typically set to the default value Bill payment. See the Transfer Reasons section for more information.	Varchar	20	yes	Bill Payment
`beneficiary_data_transfer_reason_id`	The transfer reason code. Typically set to the default value 7 (Bill payment). See the Transfer Reasons section for more information.	Varchar	20	yes	7
`beneficiary_data_value_date`	A date given in the format of YYYY-MM-DD, on which the funds are to be in the beneficiary bank account. This is either enabled and therefore becomes mandatory or is not enabled and is not taken into consideration.	Varchar	-	No	-
`reconciliation_id`	An optional custom identifier for client-side reconciliation.	Varchar	52	No	-
`client_transaction_id`	An optional custom identifier for transactions supplied by the user. This is a client specific unique reference. Must be atleast 8 character long and not start with 0, T, t, B, or b.	Varchar	100	yes	-
`beneficiary_data_payment_type`	The type of payment rail, the beneficiary is to be paid by. Possible values:60 - ACH Same Day,20 - ACH Next Day,2 - Domestic Wire,63 - International Wire,64 - Instant	Integer	-	No	ACH

Example Request

An example of the JSON structure in the request is as follows:

{
"quote_batch_id": "QB1604210",
  "use_client_id": 1,
"beneficiary_data": [
    {
        "beneficiary_data_id": "1003",
        "beneficiary_data_currency": "USD",
        "beneficiary_data_amount": "1000",
        "beneficiary_data_bene_payment_type": 2,
        "beneficiary_data_user_reference": "Bill Payment",
        "beneficiary_data_transfer_reason": "Bill Payment",
        "beneficiary_data_transfer_reason_id": "7",
        "reconciliation_id": "",
        "beneficiary_data_value_date": "2024-06-17"
    }
]
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`uid`	uid The internal unique ID of the beneficiary.	Integer
`payee_name`	payee_name The name of the payee. Varchar	Varchar
`foreign_amount`	foreign_amount The amount to be paid in the source bank's currency.	Varchar
`service_type`	The type of the service.	Varchar
`bene_payment_type`	The type of the payment.	Varchar
`rail_type`	Reason the call failed	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse	Varchar
`conversion_meta`	conversion_meta A container for conversion details.	-
`conversion`	Sub-containers for conversion details.	Varchar
`inverse`	Sub-containers for conversion details.	-
`from`	The type of the payment.	Varchar
`to`	The currency to convert to.	Varchar
`input`	The amount to convert.	Decimal/Float
`output`	The exchange rate.	Decimal
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee	Varchar
`transfer_reason`	The reason for the transfer, typically 7 (Bill Pay).	Varchar
`transfer_reason_id`	The ID of the transfer reason.	Varchar
`reference`	A reference for the transaction.	Varchar
`forbidden`	A flag that indicates if the transaction can be processed or not. A value of 0 indicates that the transaction can be processed normally. A value of 1 indicates that the transaction cannot be processed.	Varchar
`alerts`	A message to draw the user's attention to a possible anomaly that the user should check.	Varchar
`transaction_id`	The ID assigned to the transaction.	Varchar
`user_id`	The client_transaction_id that was passed in the request. If not passed, value will be null	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
     "uid": "1003",
     "payee_name": "Test3",
     "foreign_amount": "USD 1000.00",
     "service_type": "Standard",
     "bene_payment_type": "ACH",
     "rail_type": "ACH",
     "currency_rate_per_unit": "1 EUR = 1.09562 USD\n1 USD = 0.91273 EUR",
     "conversion_meta": {
         "conversion": {
             "from": "EUR",
             "to": "USD",
             "input": 1,
             "output": 1.09562
       },
         "inverse": {
             "from": "USD",
             "to": "EUR",
             "input": 1,
             "output": 0.91273
         }
     },
     "amount_from_bef_fee": "EUR 912.73",
     "fee": "0.00",
     "total_trans_amount_from": "EUR 912.73",
     "transfer_reason": "7",
     "transfer_reason_id": "Bill payment",
     "reference": "Bill Payment",
     "forbidden": "0",
     "alerts_dup_payment": "NB: You have submitted a transaction with the same parameters (amount, currency and beneficiary details) in the last 24 hours. To ensure this is not a duplicate payment, check previous submissions on your Accounts Summary.",
     "transaction_id": "T6079712",
     "user_uid": null
}
]

Example Error Responses

If the Quote Batch Add request is not successful, the service responds with an error code, rejects the request, and does not lock in the transaction. Some examples of error responses are provided.

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar
`ID`	The ID of the error message.	Varchar
`descirption`	A descirption of the error.	Varchar

Error Code 542 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

{
"uid": 220865,
  "payee_name": "Maginot Line",
  "foreign_ammount": "EUR 1000000.00",
  "service_type": "Standard",
  "bene_payment_type": "Wire Transfer",
  "currency_rate_per_unit": "1 EUR = 1.00000 EUR,1 EUR = 1.00000 EUR",
  "conversion_meta": {
      "conversion": {
          "from": "EUR",
          "to": "EUR",
          "input": 1,
          "output": 1
      },
      "inverse": {
          "from": "EUR",
          "to": "EUR",
          "input": 1,
          "output": 1
      }
  },
  "amount_from_bef_fee": "EUR 1000000.00",
  "fee": "15.00",
  "total_trans_amount_from": "EUR 1000115.00",
  "transfer_reason": "Bill Pay",
  "transfer_reason_id": "Bill payment",
  "reference": "api ref 9",
  "forbidden": "1",
  "alerts": "Further information is required to book this amount.Please contact funds@transfermate.com in order to continue with your booking.",
  "user_uid": null
}

Error Code 545 - One or More JSON Attributes Missing or Malformed

{
"stat": "one or more JSON attributes missing or malformed: currency_type"
}

Error Code 546 - One or More JSON Attributes Failed Validation

{
"stat": "contents of one or more JSON attributes failed validation"
}

Error Code 404 - Payment Blocked, NOTE: the 'forbidden' value and 'alerts'

{
"stat": "Beneficiary does not exist or has been disabled"
}

POST Get a Quote Batch Rate

You can retrieve and review a currency exchange rate by sending an HTTP POST request with the required information to the /quote_get_rate endpoint. Please note that if this endpoint is being used, the exchange rate will be locked in for 90s.

Endpoint: /quote_get_rate

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`quote_batch_id`	The ID of the quote batch you wish to get the rate quote for	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"quote_batch_id": "QB1549532"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_success`	This is either true of false	Varchar
`messages`	If the the success is false, the reason message will be displayed here	Varchar
`bank_id_from`	The ID of the funding account for the Batch	Varchar
`bank_pay_type`	The funding type of the batch	Varchar
`total_transactions`	The total transactions in the batch	-
`total_currency_from`	The amount on which the transaction fee is based.	Varchar
`total_currency_to`	The amount on which the transaction fee is based.	Varchar
`quote_total_amount_from_bef_fee`	The total amount for the transaction, which excludes the transaction fee	Varchar
`quote_total_trans_amount_from`	The total amount for the transaction, which Includes the transaction fee	Varchar
`quote_total_fee`	Total fees of the batch	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`conversion_meta`	A container for conversion details.	-
`conversion`	Sub-containers for conversion details.	-
`inverse`	Sub-containers for conversion details.	-
`from`	The currency converted from.	Varchar
`to`	The currency to convert to.	Varchar
`input`	The amount to convert.	Decimal/Float
`output`	The exchange rate.	Decimal

Example Success Response

The JSON structure in a successful response is as follows:

[
{
      "is_success": true,
      "messages": {},
      "bank_id_from": "94872",
      "bank_pay_type": "2",
      "total_transactions": "3",
      "total_currency_from": "EUR 2738.19",
      "total_currency_to": "USD 3000.00",
      "quote_total_amount_from_bef_fee": "EUR 2738.19",
      "quote_total_trans_amount_from": "EUR 2738.19",
      "quote_total_fee": "0.00",
      "currency_rate_per_unit": "1 EUR = 1.09562 USD\nUSD = 0.91273 EUR",
      "conversion_meta": {
          "conversion": {
            "from": "eur",
              "to": "usd",
            "input": "1.0",
              "output": "1.09562"
          },
          "inverse": {
              "from": "usd",
              "to": "eur",
              "input": "1.0",
              "output": "0.91273"
          }
      }
  }
]

Example Error Responses

The JSON structure associated with the error responses has the following parameters.

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Error Code 400 - The quote id is already authorized/canceled or invalid!

{
"is_success": false,
  "messages": {
      "quote_batch_id": "The quote id is already authorized/canceled or invalid!"
  }
}

POST Authorize the Quote Batch

You authorize the quote batch by sending an HTTP POST request with the required information to the /quote_authorize endpoint. This authorise will always contain metadata.

Endpoint: /quote_authorize

Request Body Payload Example

The request body includes the following parameters:

PARAMETER	DESCRIPTION	TYPE	SIZE	MANDATORY	DEFAULT VALUE
`login_terms_of_use`	A flag to indicate that the user has accepted the terms and conditions. The agreed terms and conditions should be shown to all users prior to payment authorization.	Bit	1	Yes	1
`approve`	Indicates the action to take. Set to 1 to approve payments. Set to 0 to cancel payments.	Bit	1	Yes	1
`quote_batch_id`	The quote batch ID of the batch you are authorising	List	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"login_terms_of_use": 1,
"approve": 1,
"quote_batch_id": "QB1604210"
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

FIELD	DESCRIPTION	TYPE
`is_success`	Either true or false, if false then the quote authorize has not been successful.	Integer
`messages`	If this filed is populated then the quote authorize call has failed and will give the error message.	Varchar
`quote_batch_id`	The quote batch ID that has been authorized or cancelled	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based.	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`bank_id_from`	The bank ID that is used to fund the batch	Varchar
`total_currency_from`	The total funding currency value	Varchar
`currency_rate_per_unit`	The currency exchange rate	List
`quote_total_amount_from_bef_fee`	The total funding amount before fees are added	List
`quote_total_fee`	Total fees in the batch	Varchar
`quote_total_trans_amount_from`	Total funding amount including fees	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`total_transactions`	The amount of transactions in the batch	Varchar
`total_currency_to`	The total of the payment currency	Varchar
`metadata`	A list of metadata associated with the batch payment transaction.	List
`currency`	The currency of the payment transaction.	Varchar
`amount`	The payment transaction amount with currency indicated.(Wire transfer only)	Varchar
`particular`	A custom statement associated with the batch payment transaction.	Varchar
`account_name`	The name of the source bank account.(Wire transfer only)	Varchar
`bank_name`	The name of the source bank.(Wire transfer only)	Varchar
`bank_country`	The country of the source bank.(Wire transfer only)	Varchar
`account_number`	The source bank account number.(Wire transfer only)	Varchar
`transit_code or sort_code`	The transit code or sort code. See Transit Code Values for possible values.(Wire transfer only)	Varchar
`swift_bic`	The SWIFT or Bank Identification Code (BIC) of the source bank account.(Wire transfer only)	Varchar
`aba_number`	The ABA Routing number, USA only (Wire transfer only)	Varchar
`batch_sum_details`	The reference number of the batch in which multiple payment transactions are included for approval.(Wire transfer only).	Varchar
`usr_bank_from_data`	Funding the batch instructions	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
"is_success": true,
  "messages": {},
  "bank_id_from": "94872",
  "bank_pay_type": "2",
  "total_transactions": "3",
  "total_currency_from": "EUR 2738.19",
  "total_currency_to": "USD 3000.00",
  "quote_total_amount_from_bef_fee": "EUR 2738.19",
  "quote_total_trans_amount_from": "EUR 2738.19",
  "quote_total_fee": "0.00",
  "currency_rate_per_unit": "1 EUR = 1.09562 USD\nUSD = 0.91273 EUR",
  "conversion_meta": {
      "conversion": {
          "from": "eur",
          "to": "usd",
          "input": "1.0",
          "output": "1.09562"
      },
      "inverse": {
          "from": "usd",
          "to": "eur",
          "input": "1.0",
          "output": "0.91273"
      }
      }
}
]

Example Error Responses

The JSON structure associated with the error responses has the following parameters:

FIELD	DESCRIPTION	TYPE
`stat`	A status message that describes the error encountered.	Varchar

Get Quote Batch Summary

You retrieve a summary of transactions by sending an HTTP POST request with the required information to the /quote_summary endpoint.

Endpoint: /quote_summary

Request Body Payload Example

The request body includes the following parameters:

Input Parameter	Description	Type	Size	Mandatory	Default Value
`quote_batch_id`	The Quote Batch ID of the Quote Batch being requested	Varchar	10	Yes	-
`page_size`	Results per page. Default is 100, options are 30/50/100	Integer	-	No	100
`page_no`	Specify the page number.	Varchar	20	No	1

Example Request

An example of the JSON structure in the request is as follows:

{
"quote_batch_id": "QB1603637",
"page_size": 30,
"page_no": 1
}

Response Body Payload Example

If the request is successful, the service responds with details to be reviewed.

The response body includes the following parameters:

Field	Description	Type
`is_success`	Either true or false, if false then the quote authorize has not been successful.	Integer
`messages`	If this filed is populated then the quote authorize call has failed and will give the error message.	Varchar
`page`	The current page number	Varchar
`pages_count`	Total amount of pages	Varchar
`records_per_page`	Amount of transaction records per page	Integer
`total_records`	Total records in the Quote Batch	Integer
`transactions`	A list of one or more payment transactions.	List
`benef_id`	The ID of the beneficiary.	Varchar
`payee_name`	The name of the beneficiary.	Varchar
`t_datetime_submitted`	The date and time at which the transaction was submitted	Varchar
`foreign_amount`	The amount to be paid in the source bank's currency.	Varchar
`currency_rate_per_unit`	The currency exchange rate and its inverse.	Varchar
`amount_from_ben_fee`	The amount on which the transaction fee is based	Decimal
`fee`	The fee for the payment transaction.	Decimal
`total_trans_amount_from`	The total amount for the transaction, which includes the transaction fee.	Decimal
`reference`	A reference for the payment transaction.	Varchar
`tran_type`	The payment transaction type. See Payment Method/Transaction Type Values for possible values.	Varchar
`bene_payment_type`	The beneficiary payment type. See Payment Method/Transaction Type Values for possible values.	Varchar
`batch_ref_num`	The reference number of a batch process into which several payment transactions are combined.	Varchar
`ref_num`	The reference number of a payment transaction.	Varchar
`payment_status`	The status of a payment transaction. See Payment Status Codes for possible values.	Varchar
`payment_status_abrv`	An abbreviation of the payment status.	Varchar
`client_data`	A custom statement associated with the payment transaction.	Varchar
`client_id`	A unique alpha-numeric string which may be given in order to identify the beneficiary account.	Varchar
`user_uid`	The client_transaction_id which may be passed in at the time of booking. This is a unique alpha-numeric string to identify the transaction.	Varchar
`metadata`	A list of metadata associated with the quote batch.	List
`batch_sum_details`	A text description that summarizes the batch transaction.	Varchar
`usr_bank_from_data`	A text description that summarizes the source bank account information.	Varchar
`transfer_type`	The type of payment transaction.	Varchar
`currency`	The currency of the payment transaction.	Varchar
`amount`	The payment transaction amount with currency indicated.	Varchar
`particular`	A custom statement associated with the batch payment transaction.	Varchar
`account_name`	The name of the source bank account.	Varchar
`bank_name`	The name of the source bank.	Varchar
`bank_country`	The country of the source bank.	Varchar
`account_number`	The source bank account number.	Varchar
`account_number`	The source bank account number.	Varchar
`transit_code`	The transit code. See Transit Code Values for possible values.	Varchar
`ref_number`	The reference number of the batch in which multiple payment transactions are included for approval.	Varchar

Example Success Response

The JSON structure in a successful response is as follows:

[
{
"is_success": true,
  "messages": {},
  "page": 1,
  "pages_count": 1,
  "records_per_page": 50,
  "total_records": 3,
  "transactions": [
{
      "benef_id": "1684927",
      "payee_name": "Test3",
      "t_datetime_submitted": "2023-07-13 12:06:00",
      "foreign_ammount": "USD 1000.00",
      "currency_rate_per_unit": "1.09562",
      "amount_from_bef_fee": "EUR 912.73",
      "fee": "0.00",
      "total_trans_amount_from": "EUR 912.73",
      "reference": "Bill Payment",
      "ultimate_debtors_id": null,
      "tran_type": "Wire Transfer",
      "bene_payment_type": "ACH",
      "rail_type": "ACH",
    "batch_ref_num": "B1604210",
      "ref_number": "T6079712",
      "payment_status": "Awaiting Funds",
      "payment_status_abrv": "pending",
      "client_id": "1003",
      "client_data": null,
      "user_uid": null,
      "users_authorised": "Test Test",
      "auth_one": "Test Test",
      "auth_two": null
},
{
      "benef_id": "1684921",
      "payee_name": "Test2",
      "t_datetime_submitted": "2023-07-13 12:05:00",
      "foreign_ammount": "USD 1000.00",
      "currency_rate_per_unit": "1.09562",
      "amount_from_bef_fee": "EUR 912.73",
      "fee": "0.00",
      "total_trans_amount_from": "EUR 912.73",
      "reference": "Bill Payment",
      "ultimate_debtors_id": null,
      "tran_type": "Wire Transfer",
      "bene_payment_type": "ACH",
      "rail_type": "ACH",
      "batch_ref_num": "B1604210",
      "ref_number": "T6079711",
      "payment_status": "Awaiting Funds",
      "payment_status_abrv": "pending",
      "client_id": "1002",
      "client_data": null,
      "user_uid": null,
      "users_authorised": "Test Test",
      "auth_one": "Test Test",
      "auth_two": null
},
{
      "benef_id": "1684915",
      "payee_name": "Test1",
      "t_datetime_submitted": "2023-07-13 12:05:00",
      "foreign_ammount": "USD 1000.00",
      "currency_rate_per_unit": "1.09562",
      "amount_from_bef_fee": "EUR 912.73",
      "fee": "0.00",
      "total_trans_amount_from": "EUR 912.73",
      "reference": "Bill Payment",
      "ultimate_debtors_id": null,
      "tran_type": "Wire Transfer",
      "bene_payment_type": "ACH",
      "rail_type": "ACH",
      "batch_ref_num": "B1604210",
      "ref_number": "T6079710",
      "payment_status": "Awaiting Funds",
      "payment_status_abrv": "pending",
      "client_id": "1001",
      "client_data": null,
      "user_uid": null,
      "users_authorised": "Test Test",
      "auth_one": "Test Test",
      "auth_two": null
}
  ],
  "metadata": {
"batch_sum_details": "Domestic Amount: EUR 2,738.19 Reference Number: B1604210",
"usr_bank_from_data": "Wire Transfer from your bank account: Account Holder Name: Account name Bank Name: ALLIED IRISH BANKS P.L.C. Bank Country: Ireland IBAN: Ixx-xxxx-5678 Sort Code: 9xx-xxxx-xx52 SWIFT/BIC Code: Axx-xxxx-xxXX Currency: EUR",
"transfer_type": "Internal Bank Transfer",
"currency": "EUR",
"amount": "EUR 2738.19",
"particular": "Mr Test Test",
"account_name": "Interpay Ltd",
"bank_name": "ALLIED IRISH BANKS P.L.C.",
"bank_country": "Ireland",
"bank_address": "High Street, Kilkenny",
"iban": "IE71 AIBK 9334 2271 1780 83",
"account_number": "71178083",
"sort_code": "933422",
"swift_bic": "AIBKIE2DXXX",
"ref_number": "B1604210"
  }
}
]

Example Error Responses

If the get transaction summary request is not successful, the service responds with an error code, rejects the request, and does not return any transaction data. An example error response is provided.

The JSON structure associated with the error responses has the following parameters:

Field	Description	Type
`is_success`	A status message that is either true or false	Varchar
`messages`	The reason of any failure	Varchar

Error Code 400 - No data

{
"is_success": false,
"messages": {
"quote_batch_id": "No data found"
},
"page": null,
"pages_count": null,
"records_per_page": null,
"total_records": null,
"transactions": [],
"metadata": {}
}

Error Code 400 - Field Page size incorrect

{
"is_success": false,
"messages": {
"quote_batch_id": "Field page_size must be one of the following values: 30, 50, 100!"
},
"page": null,
"pages_count": null,
"records_per_page": null,
"total_records": null,
"transactions": [],
"metadata": {}
}

POST Check For Holiday

You check for a holiday by sending an HTTP POST request with the required information to the /check_holiday endpoint.

Endpoint: /check_holiday

Request Body Payload Example

The request body includes the following parameters:

Input Parameter	Description	Type	Size	Mandatory	Default Value
`country`	Region to be checked for a holiday. See the Example Response to the Get Supported Holiday Regions API for supported values.	Varchar	-	Yes	-
`date`	The date to be checked for a holiday.	Varchar	-	Yes	-

Example Request

An example of the JSON structure in the request is as follows:

{
"country": "irish",
"date": "2022-01-11"
}

Response Body Payload Example

If the request is successful, the service responds with a list of holidays.

The response body includes the following parameters:

Field	Description	Type
`supplied_date`	The date provided by the user.	Varchar
`holidays`	A list of one or more holiday descriptions.	List

Example Success Response

The JSON structure in a successful response is as follows:

{
"supplied_date": "2022-01-11",
"holidays": [
"St. Patrick's Day"
]
}

Example Error Responses

If the request is not successful, the service responds with an error code, rejects the request, and does not provide holiday information. Some examples of the error responses are provided.

The JSON structure associated with the error responses has the following parameters:

Field	Description	Type
`stat`	A status message that describes the error encountered.	Varchar

Error Code XXX - No Holiday Event

{
"stat": "no holiday event on 2022-01-11"
}

Error Code XXX - Incorrect Data Format

{
"stat": "incorrect data format, should be YYYY-MM-DD"
}

Get Supported Holiday Regions

You request a list of the supported holiday regions by sending an HTTP GET request with the required information to the /get_holiday_regions endpoint.

Endpoint: /get_holiday_regions

Response Body Payload Example

If the request is successful, the service returns a response. The response contains a list of supported holiday regions.

The response body includes the following parameters:

Field	Description	Type
`-`	List of supported holiday regions	List

Example Success Response

[
"australian",
"austrian",
"brazilian",
"canadian",
"china",
"christian",
"danish",
"dutch",
"finnish",
"french",
"german",
"greek",
"hong_kong_c",
"hong_kong",
"indian",
"indonesian",
"iranian",
"irish",
"islamic",
"italian",
"japanese",
"jewish",
"malaysia",
"mt",
"mexican",
"new_zealand",
"norwegian",
"philippines",
"polish",
"portuguese",
"russian",
"singapore",
"sa",
"south_korea",
"spain",
"swedish",
"taiwan",
"thai",
"uk",
"usa",
"vietnamese"
]

Frequently Asked Questions

Do you have callback notifications for status updates, or should I use polling?
We do not have callback notifications. However, we have a separate webhook system that can do callbacks with integration information shared between the sales team and the customer. This is available on a case-by-case basis on request because it involves direct integration work between Transfermate and the client.
For add_beneficiary What is the difference between the "state" and "State" params?
They should be grouped as they are either/or. The state parameter is a legacy internal reference ID to the country. The State parameter is the two-character ISO state code for the US.
What does the def_payment_reference parameter mean?
Default Payment Reference. It is a free text string with a maximum length of 250 characters. The “fixed category” was removed.
Is payee_name just an ID and could be random, or should it be a real client name?
It should identify the account holder because this information can be passed together with the account number in some banking backend systems. Sometimes, providing an incorrect payee_name can cause transaction delays in some jurisdictions.
Is it possible to get beneficiary data with uid instead of payee_name?
No. You can get beneficiary data either by name or by country. If you choose the country option, you retrieve the data for all beneficiary accounts in that country with pagination.
"Country reference by system ID" is marked as deprecated. Should we use text code?
Yes. Both are supported, but you should pass the two-character ISO code for the country as the country_code parameter instead of country or country_id.
If I send a request with { validate_only: 1 } and receive a valid response, can I be sure that if I send the same without validate_only, it will create a new beneficiary?
Yes. You can see this in action in your sandbox.
Regarding get_booking_rate, I made some test queries EUR-to-EUR with "wire transfer" for SEPA accounts (EST to LT), and I see minimal fee 15EUR. Is it correct? Do you support some options to make transfers cheaper (SEPA, etc.)?
Not without prior contractual agreement with the Treasury. Please contact your Transfermate customer service representative to see if this is possible.
get_info {"ref_number":"T1234567"} Returns a "Failed to fetch" error in Swagger. I'm doing it directly with curl:{"message":"MY_TOKEN' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer MY_TOKEN'."}. What could be wrong?
The get_info The request is retired and no longer supported. The get_summary request now incorporates the retired get_info request functionality.
What characters can be used in the beneficiary payee_name and the bank account_name?
You can only use alphanumeric characters for the beneficiary payee_name and the bank account_name. Other characters will be stripped and replaced with spaces.
What characters can be used in the beneficiary payee_address and the bank_branch_address ?
You can only use alphanumeric characters for the beneficiary payee_address and the bank_branch_address. Entering non-alphanumeric characters will cause a 521 error to be returned. {"id":"payee_address", "description":"This field does not allow entering characters other than latin alphabet letters and numbers."}
Why can I not activate a global_account ?
Prior to any global_account being activated, there is a requirement for a minimum of one bank_account to be added. Once a bank_account is added, full functionality of the account is established.
additional_routing_numberis used for the USA only, and this field must contain the ABA Routing number for WIRE- this then allows payment rail granularity to be used. Please note, not all USA accounts will have two routing numbers. If the incorrect routing number is used, this might cause funds to be rejected by the beneficiary bank. Please always use the field transit_code for the ACH routing number as this is the default method of payment. Once this field is added, it cannot be edited.
Please note that adding a beneficiary that is a Global Account cannot be added, even if the Duplicate Account flag is used. When each Global Account is activated, a beneficiary ID is created and should be used if required. If attempting to add a beneficiary that is a Global Account, the error521 "description": "This Beneficiary bank already exists. It was automatically created upon a Global Account activation." will be displayed.
Unless specified, Allowed characters: Latin letters A-Za-z, 0-9 numbers, - _ : & ; , # / and space

Payments API Overview

Getting Started

Authentication

POST Connect to the Payments Service

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

GET Disconnect from the Payments Service

Response Body Payload Example

Example Success Response

Example Error Responses

POST Retrieve Historical Connection Information

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Change password for the Payment Service

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

Treasury Account Management

POST Add a New Bank Account

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Verify Existing Bank Account Details

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Edit Existing Bank Account Details

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Verify Existing Bank Account Details

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

Beneficiary Account Management

POST Add a New Beneficiary Account- Scheduled for depreciation 29th September 2025

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Add a New Beneficiary Account V2

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Disable an Existing Beneficiary Account

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Edit an Existing Beneficiary Account- - Scheduled for depreciation 29th September 2025

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response

Example Error Responses

POST Edit an Existing Beneficiary Account V2

Request Body Payload Example

Example Request

Response Body Payload Example

Example Success Response