Gemba Open Banking API (0.1)

The Gemba Open Banking API allows secure and easy integration with banking services. It provides endpoints for managing accounts, payments, messaging, and webhooks. This API supports operations like account retrieval, transaction processing, and sending messages securely.

Authentication

All requests to the Gemba Open Banking API require an Authorization header containing a valid bearer access token. Example:

Authorization: Bearer ${access_token}

The access token is valid for 10 minutes. Once expired, a new token must be generated to continue using the API.

Request an access token

This endpoint allows clients to request an access token using the application client credentials. The obtained token can be used to authenticate subsequent API requests.

header Parameters
x-client-id
required
string
Example: client_123456

The unique identifier of the client application

x-client-secret
required
string
Example: Y1Xv24MUhuaej0ZRBor6bWakK1jfU8faJgAKQ7ad9huAWkYFObsIEcIHsy8M708P

The unique identifier of the client application making the request

Responses

Response Schema: application/json
access_token
string

The access token to be used for authenticated requests.

expires_in
integer

The number of seconds until the token expires.

token_type
string

The type of token issued, typically "Bearer" for OAuth 2.0.

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Clients

Endpoints related to retrieving user clients.

Retrieve user clients

This endpoint retrieves a list of user clients. It returns an array of client objects, each containing client details.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array
id
required
string <uuid>
name
required
string [ 1 .. 255 ] characters

Client name

isActive
required
boolean
createdAt
required
string <date-time>

Timestamp of opening

updatedAt
required
string <date-time>

Last update timestamp

deletedAt
string or null <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "123f4567-d89b-12d3-a456-436614174000",
    • "name": "Sample Client",
    • "isActive": true,
    • "createdAt": "2022-01-01T00:00:00Z",
    • "updatedAt": "2023-01-01T00:00:00Z",
    • "deletedAt": null
    }
]

Retrieve account details

Retrieves detailed information for a specific client.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

Responses

Response Schema: application/json
id
required
string <uuid>
name
required
string [ 1 .. 255 ] characters

Client name

isActive
required
boolean
createdAt
required
string <date-time>

Timestamp of opening

updatedAt
required
string <date-time>

Last update timestamp

deletedAt
string or null <date-time>

Response samples

Content type
application/json
{
  • "id": "550e8400-e29b-41d4-a716-446655440000",
  • "name": "Sample Client",
  • "isActive": true,
  • "createdAt": "2022-01-01T10:00:00Z",
  • "updatedAt": "2023-06-15T14:30:00Z",
  • "deletedAt": null
}

Accounts

Endpoints related to managing user accounts, such as retrieving account details, balances, and performing account-based operations.

Retrieve user accounts

This endpoint retrieves a list of user accounts. It returns an array of account objects, each containing details such as account ID, client ID, name, status, associated IBANs, and available currencies.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

Responses

Response Schema: application/json
Array
id
required
string <uuid>
clientId
required
string <uuid>
name
required
string [ 1 .. 255 ] characters

Account name

isActive
required
boolean
status
required
string (AccountStatusEnum)
Enum: "active" "blockedCredit" "blockedDebit" "blockedAll"
endDate
required
string or null <date-time>

Planned date of closure

createdAt
required
string <date-time>

Timestamp of opening

updatedAt
required
string or null <date-time>

Last update timestamp

closedAt
required
string or null <date-time>

Date of closure

deletedAt
required
string or null <date-time>
required
Array of objects (IBANResponse)

Account numbers

required
Array of objects (CurrencyResponse)

Available currencies

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "clientId": "123e4567-e89b-12d3-a456-426614174000",
    • "name": "Sample Account",
    • "isActive": true,
    • "status": "active",
    • "endDate": "2025-12-31T00:00:00Z",
    • "createdAt": "2022-01-01T00:00:00Z",
    • "updatedAt": "2023-01-01T00:00:00Z",
    • "closedAt": null,
    • "deletedAt": null,
    • "numbers": [
      • {
        • "sortCode": "123456",
        • "accountNumber": "12345678",
        • "IBAN": "GB29NWBK60161331926819"
        },
      • {
        • "sortCode": "654321",
        • "accountNumber": "87654321",
        • "IBAN": "GB29NWBK60161331926820"
        }
      ],
    • "currencies": [
      • {
        • "name": "United States Dollar",
        • "code": "USD"
        },
      • {
        • "name": "Euro",
        • "code": "EUR"
        }
      ]
    }
]

Retrieve account details

Retrieves detailed information for a specific account. This endpoint returns a single account object containing comprehensive data such as account ID, client ID, name, status, associated IBANs, and available currencies.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) of the account to retrieve

Responses

Response Schema: application/json
id
required
string <uuid>
clientId
required
string <uuid>
name
required
string [ 1 .. 255 ] characters

Account name

isActive
required
boolean
status
required
string (AccountStatusEnum)
Enum: "active" "blockedCredit" "blockedDebit" "blockedAll"
endDate
required
string or null <date-time>

Planned date of closure

createdAt
required
string <date-time>

Timestamp of opening

updatedAt
required
string or null <date-time>

Last update timestamp

closedAt
required
string or null <date-time>

Date of closure

deletedAt
required
string or null <date-time>
required
Array of objects (IBANResponse)

Account numbers

required
Array of objects (CurrencyResponse)

Available currencies

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "clientId": "98765432-e89b-12d3-a456-426614174000",
  • "name": "Premium Savings Account",
  • "isActive": true,
  • "status": "active",
  • "endDate": "2025-12-31T23:59:59Z",
  • "createdAt": "2022-01-01T10:00:00Z",
  • "updatedAt": "2023-06-15T14:30:00Z",
  • "closedAt": null,
  • "deletedAt": null,
  • "numbers": [
    • {
      • "sortCode": "123456",
      • "accountNumber": "12345678",
      • "IBAN": "GB29NWBK60161331926819"
      }
    ],
  • "currencies": [
    • {
      • "name": "British Pound Sterling",
      • "code": "GBP"
      }
    ]
}

Retrieve account statement

This endpoint retrieves an account statement for a specific account, providing transaction history and balance information for a given time period. The response can be filtered by date range and currency.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>

The unique identifier for the account. This is a GUID that represents the account for which the statement is being requested.

query Parameters
from
string <date>

The start date for the statement period (inclusive). Only transactions from this date onward will be included in the statement. Format: YYYY-MM-DD.

to
string <date>

The end date for the statement period (inclusive). Only transactions up to this date will be included in the statement. Format: YYYY-MM-DD.

currencyCode
string

The currency code (ISO 4217) to filter the statement by a specific currency. Example: USD, EUR, GBP. If not provided, the default currency of the account will be used.

Responses

Response Schema: application/json
required
object (BalanceResponse)
required
Array of objects (StatementRecord)

Response samples

Content type
application/json
{
  • "balance": {
    • "accountId": "123e4567-e89b-12d3-a456-426614174000",
    • "currencyCode": "str",
    • "issuedAt": "2019-08-24T14:15:22Z",
    • "opening": 0,
    • "closing": 0,
    • "openingDate": "2019-08-24T14:15:22Z",
    • "closingDate": "2019-08-24T14:15:22Z"
    },
  • "records": [
    • {
      • "id": "123e4567-e89b-12d3-a456-426614174000",
      • "documentRef": "DOC-2023-09-15-001",
      • "transactionRef": "TRANS-20230915-001",
      • "date": "2023-09-15T14:30:00Z",
      • "type": "SEPA Transfer",
      • "amount": 100000,
      • "currencyCode": "EUR",
      • "details": "Monthly salary payment",
      • "recipientBIC": "DEUTDEFFXXX",
      • "recipientAccount": "DE89370400440532013000",
      • "recipientName": "John Doe",
      • "senderBIC": "BOFAUS3NXXX",
      • "senderAccount": "US29NWBK60161331926819",
      • "senderName": "Alice Smith"
      }
    ]
}

Retrieve account balance

This endpoint allows you to retrieve the balance of a specific account. You must specify the account ID and currency code, and optionally, you can provide a date range using the opening and closing date query parameters.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier for the account. This is a GUID that represents the account for which the balance is being requested.

currencyCode
required
string <= 3 characters
Example: USD

The 3-letter currency code (ISO 4217) for which the balance is requested. Example: USD, EUR, GBP.

query Parameters
openingDate
string <date>
Example: openingDate=2023-09-01

The starting date for the balance inquiry. This date marks the opening of the period for which you want to retrieve the account balance.

closingDate
string <date>
Example: closingDate=2023-09-15

The ending date for the balance inquiry. This date marks the closure of the period for which you want to retrieve the account balance.

Responses

Response Schema: application/json
accountId
required
string <uuid>
currencyCode
required
string <= 3 characters

Currency in ISO 4217 alpha-3 format

issuedAt
required
string <date-time>
opening
required
integer <int64>

Amount specified in minor units of currency

closing
required
integer <int64>

Amount specified in minor units of currency

openingDate
required
string <date-time>
closingDate
required
string <date-time>

Response samples

Content type
application/json
Example
{
  • "accountId": "123e4567-e89b-12d3-a456-426614174000",
  • "currency": "USD",
  • "balance": 1000000,
  • "availableBalance": 950000,
  • "pendingTransactions": 50000,
  • "reservedBalance": 0,
  • "asOf": "2023-09-15T14:30:00Z"
}

Payments

This tag covers endpoints for processing various types of payments, including internal, international, and UK-based transfers.

Create an internal transfer

This endpoint initiates an internal transfer between accounts. The transfer requires specifying the recipient's account details, the amount, and the currency code.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which the internal transfer will be initiated.

Request Body schema: application/json
amount
required
integer <int64>

The amount to be transferred. Must be a positive integer.

currencyCode
required
string <= 3 characters

The 3-letter ISO 4217 currency code for the transfer. Example: USD, EUR, GBP.

description
string

A brief description or reference for the transfer. This field is optional.

recipientName
string

The name of the recipient for this transfer.

recipientAccountNumber
required
string

The recipient's account number (IBAN) to which the funds will be transferred.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The IBAN (International Bank Account Number) of the recipient's account.

createdAt
string <date-time>

Timestamp when the transfer was created.

Request samples

Content type
application/json
{
  • "amount": 100000,
  • "currencyCode": "USD",
  • "description": "Monthly rent payment",
  • "recipientName": "John Doe",
  • "recipientAccountNumber": "DE89370400440532013000"
}

Response samples

Content type
application/json
{
  • "id": "234e5678-e89b-12d3-a456-426614174000",
  • "status": "completed",
  • "amount": 100000,
  • "fee": 500,
  • "total": 100500,
  • "currencyCode": "USD",
  • "description": "Monthly rent payment",
  • "recipientName": "John Doe",
  • "recipientAccountNumber": "DE89370400440532013000",
  • "createdAt": "2023-09-15T14:30:00Z"
}

Retrieve internal transfers

This endpoint retrieves a list of internal transfers for a specific account. The result can be paginated using offset and limit query parameters.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which internal transfers will be fetched.

query Parameters
from
string <date>

The start date for the period (inclusive). Format: YYYY-MM-DD.

to
string <date>

The end date for the statement period (inclusive). Format: YYYY-MM-DD.

offset
integer
Default: 0

The number of records to skip from the beginning of the result set. Default is 0.

limit
integer
Default: 10
Example: limit=10

The maximum number of records to return. Default is 10.

Responses

Response Schema: application/json
Array
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The IBAN (International Bank Account Number) of the recipient's account.

createdAt
string <date-time>

Timestamp when the transfer was created.

Response samples

Content type
application/json
[
  • {
    • "id": "234e5678-e89b-12d3-a456-426614174000",
    • "status": "completed",
    • "amount": 100000,
    • "currencyCode": "USD",
    • "description": "Monthly rent payment",
    • "recipientName": "John Doe",
    • "recipientAccountNumber": "DE89370400440532013000",
    • "createdAt": "2023-09-15T14:30:00Z"
    },
  • {
    • "id": "345e6789-e89b-12d3-a456-426614174000",
    • "status": "pending",
    • "amount": 50000,
    • "currencyCode": "EUR",
    • "description": "Invoice payment",
    • "recipientName": "Jane Smith",
    • "recipientAccountNumber": "FR1420041010050500013M02606",
    • "createdAt": "2023-09-15T14:30:00Z"
    }
]

Retrieve internal transfer fees

This endpoint retrieves fees for internal transfers for a specific account.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which internal transfers will be fetched.

query Parameters
amount
required
integer <int64>
Example: amount=100000

Amount of the internal transfer

currencyCode
required
string <= 3 characters
Example: currencyCode=USD

Currency code of the internal transfer. ISO 4217 3-letter currency code.

Responses

Response Schema: application/json
amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

Response samples

Content type
application/json
{
  • "fee": 500,
  • "amount": 100000,
  • "currencyCode": "USD"
}

Send a transfer confirmation code (OTP)

This endpoint send the OTP for a specific transfer.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which transfers will be fetched.

transferType
required
string
Enum: "internal" "international" "uk"
Example: international

The type of transfer to be confirmed.

transferId
required
string <uuid>
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

The unique identifier (GUID) for the transfer to be confirmed.

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the transfer confirmation.

type
required
string
Default: "sms"
Enum: "sms" "email"

The type of transfer confirmation.

code
string or null

The confirmation code. Sandbox only

status
required
string
Enum: "confirmed" "sent" "expired"

The status of the internal transfer confirmation

expiresAt
required
string <date-time>

The timestamp when the transfer was confirmed.

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "type": "sms",
  • "status": "sent",
  • "expiresAt": "2024-09-16T14:32:00Z"
}

Validate a transfer confirmation code (OTP)

This endpoint initiates an transfer between accounts. The transfer requires specifying the recipient's account details, the amount, and the currency code.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which the transfer will be initiated.

transferType
required
string
Enum: "internal" "international" "uk"
Example: international

The type of transfer to be confirmed.

transferId
required
string <uuid>
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

The unique identifier (GUID) for the transfer to be confirmed.

Request Body schema: application/json
code
required
string

The OTP to confirm the transfer.

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the transfer confirmation.

type
required
string
Default: "sms"
Enum: "sms" "email"

The type of transfer confirmation.

code
string or null

The confirmation code. Sandbox only

status
required
string
Enum: "confirmed" "sent" "expired"

The status of the internal transfer confirmation

expiresAt
required
string <date-time>

The timestamp when the transfer was confirmed.

Request samples

Content type
application/json
{
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "type": "sms",
  • "status": "confirmed",
  • "expiresAt": "2024-09-16T14:32:00Z"
}

Create an international transfer

This endpoint creates an international transfer. The transfer requires specifying details about the recipient, bank, and intermediary (if applicable), along with the amount and currency code.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>

The unique identifier (GUID) for the account from which the international transfer will be initiated.

Request Body schema: application/json
amount
required
integer <int64>

The amount to be transferred. Must be a positive integer.

currencyCode
required
string <= 3 characters

The 3-letter ISO 4217 currency code for the transfer. Example: USD, EUR, GBP.

description
string

A brief description or reference for the transfer.

recipientName
string

The name of the recipient for this transfer.

recipientAccountNumber
required
string

The recipient's account number (IBAN or another account format depending on the country).

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
recipientAddress
required
string <= 255 characters

The address of the recipient.

recipientCountry
required
string <= 2 characters

The 3-letter ISO 3166-1 alpha-2 country code for the recipient's country.

recipientRegistrationNumber
string

The recipient’s registration number (e.g., national ID or tax ID).

chargesType
required
string (InternationalTransferChargesTypeEnum)
Enum: "our" "sha"

Specifies who will bear the transfer charges. our means the sender covers all fees, while sha means the sender and recipient share the fees.

bankName
required
string

The name of the recipient's bank.

bankAddress
required
string

The address of the recipient's bank.

bankCountry
required
string <= 3 characters

The 3-letter ISO 3166-1 alpha-2 country code for the bank's location.

bankBIC
required
string

The Bank Identifier Code (BIC) or SWIFT code of the recipient's bank.

intermediaryBIC
string

The Bank Identifier Code (BIC) or SWIFT code of the intermediary bank, if applicable.

intermediaryName
string

The name of the intermediary bank, if applicable.

intermediaryAddress
string

The address of the intermediary bank, if applicable.

intermediaryAccountNumber
string

The account number at the intermediary bank, if applicable.

intermediaryCountry
string <= 3 characters

The 3-letter ISO 3166-1 alpha-2 country code for the intermediary bank's location.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The account number or IBAN of the recipient's account (individual or company).

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
recipientAddress
required
string <= 255 characters

The address of the recipient.

recipientCountry
required
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the recipient.

recipientRegistrationNumber
string

The registration number of the recipient (e.g., tax ID, company registration number).

chargesType
required
string (InternationalTransferChargesTypeEnum)
Enum: "our" "sha"

Specifies who will bear the transfer charges. our means the sender covers all fees, while sha means the sender and recipient share the fees.

bankName
required
string

The name of the recipient's bank.

bankAddress
required
string

The address of the recipient's bank.

bankCountry
required
string <= 3 characters

The ISO 3166-1 alpha-2 country code of the recipient's bank.

bankBIC
required
string

The Bank Identifier Code (BIC) or SWIFT code of the recipient's bank.

intermediaryBIC
string

The BIC of the intermediary bank, if applicable.

intermediaryName
string

The name of the intermediary bank, if applicable.

intermediaryAddress
string

The address of the intermediary bank, if applicable.

intermediaryAccountNumber
string

The account number at the intermediary bank, if applicable.

intermediaryCountry
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the intermediary bank, if applicable.

createdAt
string <date-time>

Timestamp when the transfer was created.

Request samples

Content type
application/json
{
  • "amount": 0,
  • "currencyCode": "str",
  • "description": "string",
  • "recipientName": "string",
  • "recipientAccountNumber": "string",
  • "recipientAccountType": "individual",
  • "recipientAddress": "7th Floor, The Bower Warehouse, 211 Old Street, London EC1V 9NR",
  • "recipientCountry": "st",
  • "recipientRegistrationNumber": "string",
  • "chargesType": "sha",
  • "bankName": "string",
  • "bankAddress": "string",
  • "bankCountry": "str",
  • "bankBIC": "string",
  • "intermediaryBIC": "string",
  • "intermediaryName": "string",
  • "intermediaryAddress": "string",
  • "intermediaryAccountNumber": "string",
  • "intermediaryCountry": "str"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "done",
  • "accountId": "234e5678-e89b-12d3-a456-426614174000",
  • "amount": 100000,
  • "fee": 500,
  • "total": 100500,
  • "currencyCode": "EUR",
  • "description": "Monthly rent payment",
  • "recipientName": "John Doe",
  • "recipientAccountNumber": "DE89370400440532013000",
  • "recipientAccountType": "individual",
  • "recipientAddress": "7th Floor, The Bower Warehouse, 211 Old Street, London EC1V 9NR",
  • "recipientCountry": "GB",
  • "recipientRegistrationNumber": "DE123456789",
  • "chargesType": "sha",
  • "bankName": "Deutsche Bank",
  • "bankAddress": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
  • "bankCountry": "DE",
  • "bankBIC": "DEUTDEFFXXX",
  • "intermediaryBIC": "BOFAUS3NXXX",
  • "intermediaryName": "Bank of America",
  • "intermediaryAddress": "100 West 33rd Street, New York, NY 10001, USA",
  • "intermediaryAccountNumber": 6550123456,
  • "intermediaryCountry": "US",
  • "createdAt": "2024-09-16T14:32:00Z"
}

Retrieve international transfers

This endpoint retrieves a list of international transfers for a specific account. The result can be paginated using offset and limit query parameters.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>

The unique identifier (GUID) for the account from which international transfers will be fetched.

query Parameters
from
string <date>

The start date for the period (inclusive). Format: YYYY-MM-DD.

to
string <date>

The end date for the statement period (inclusive). Format: YYYY-MM-DD.

offset
integer
Default: 0

The number of records to skip from the beginning of the result set. Default is 0.

limit
integer
Default: 10

The maximum number of records to return. Default is 10.

Responses

Response Schema: application/json
Array
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The account number or IBAN of the recipient's account (individual or company).

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
recipientAddress
required
string <= 255 characters

The address of the recipient.

recipientCountry
required
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the recipient.

recipientRegistrationNumber
string

The registration number of the recipient (e.g., tax ID, company registration number).

chargesType
required
string (InternationalTransferChargesTypeEnum)
Enum: "our" "sha"

Specifies who will bear the transfer charges. our means the sender covers all fees, while sha means the sender and recipient share the fees.

bankName
required
string

The name of the recipient's bank.

bankAddress
required
string

The address of the recipient's bank.

bankCountry
required
string <= 3 characters

The ISO 3166-1 alpha-2 country code of the recipient's bank.

bankBIC
required
string

The Bank Identifier Code (BIC) or SWIFT code of the recipient's bank.

intermediaryBIC
string

The BIC of the intermediary bank, if applicable.

intermediaryName
string

The name of the intermediary bank, if applicable.

intermediaryAddress
string

The address of the intermediary bank, if applicable.

intermediaryAccountNumber
string

The account number at the intermediary bank, if applicable.

intermediaryCountry
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the intermediary bank, if applicable.

createdAt
string <date-time>

Timestamp when the transfer was created.

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "status": "done",
    • "accountId": "234e5678-e89b-12d3-a456-426614174000",
    • "amount": 100000,
    • "fee": 500,
    • "total": 100500,
    • "currencyCode": "EUR",
    • "description": "Monthly rent payment",
    • "recipientName": "John Doe",
    • "recipientAccountNumber": "DE89370400440532013000",
    • "recipientAccountType": "individual",
    • "recipientAddress": "7th Floor, The Bower Warehouse, 211 Old Street, London EC1V 9NR",
    • "recipientCountry": "GB",
    • "recipientRegistrationNumber": "DE123456789",
    • "chargesType": "sha",
    • "bankName": "Deutsche Bank",
    • "bankAddress": "Taunusanlage 12, 60325 Frankfurt am Main, Germany",
    • "bankCountry": "DE",
    • "bankBIC": "DEUTDEFFXXX",
    • "intermediaryBIC": "BOFAUS3NXXX",
    • "intermediaryName": "Bank of America",
    • "intermediaryAddress": "100 West 33rd Street, New York, NY 10001, USA",
    • "intermediaryAccountNumber": 6550123456,
    • "intermediaryCountry": "US",
    • "createdAt": "2024-09-16T14:32:00Z"
    }
]

Retrieve international transfer fees

This endpoint retrieves a list of international transfer fees for a specific account.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which international transfers will be fetched.

query Parameters
amount
required
integer <int64>
Example: amount=100000

The amount of the international transfer.

currencyCode
required
string <= 3 characters
Example: currencyCode=EUR

The currency code of the international transfer. ISO 4217.

recipientAccountNumber
required
string
Example: recipientAccountNumber=DE89370400440532013000

The account number or IBAN of the recipient's account (individual or company).

recipientCountry
required
string <= 2 characters
Example: recipientCountry=DE

The country of the recipient's account. ISO 3166-1 alpha-2.

chargesType
required
string (InternationalTransferChargesTypeEnum)
Enum: "our" "sha"
Example: chargesType=sha

Specifies who pays the transfer fees. 'our' means the sender pays all fees, 'sha' means fees are shared.

bankCountry
required
string <= 2 characters
Example: bankCountry=DE

The country of the recipient's bank. ISO 3166-1 alpha-2.

intermediaryAccountNumber
string
Example: intermediaryAccountNumber=6550123456

The account number at the intermediary bank, if applicable.

intermediaryCountry
string <= 2 characters
Example: intermediaryCountry=US

The country of the intermediary bank, if applicable. ISO 3166-1 alpha-2.

Responses

Response Schema: application/json
amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

recipientAccountNumber
required
string

The account number or IBAN of the recipient's account.

recipientCountry
required
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the recipient.

chargesType
required
string (InternationalTransferChargesTypeEnum)
Enum: "our" "sha"

Specifies who will bear the transfer charges. our means the sender covers all fees, while sha means the sender and recipient share the fees.

bankCountry
required
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the recipient's bank.

intermediaryAccountNumber
string

The account number at the intermediary bank, if applicable.

intermediaryCountry
string <= 2 characters

The ISO 3166-1 alpha-2 country code of the intermediary bank, if applicable.

Response samples

Content type
application/json
{
  • "amount": 100000,
  • "fee": 500,
  • "currencyCode": "EUR",
  • "recipientAccountNumber": "DE89370400440532013000",
  • "recipientCountry": "DE",
  • "chargesType": "sha",
  • "bankCountry": "DE",
  • "intermediaryAccountNumber": 6550123456,
  • "intermediaryCountry": "US"
}

Create a UK Transfer

Initiates a new UK transfer from the specified account. This endpoint supports both Faster Payments Service (FPS) and Clearing House Automated Payment System (CHAPS) transfers.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) of the source account

Request Body schema: application/json
amount
required
integer <int64>

The transfer amount in minor currency units (e.g., pence for GBP)

currencyCode
required
string <= 3 characters

The ISO 4217 currency code

description
string

A description or reference for the transfer

recipientName
string

The name of the transfer recipient

recipientAccountNumber
required
string

The recipient's account number

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
type
required
string (UKTransferTypeEnum)
Enum: "fps" "chaps"

The type of transfer, either 'fps' for Faster Payments Service or 'chaps' for CHAPS.

chapsPurpose
string or null (ChapsPurposeEnum)
Enum: "Deposit" "IntraCompanyPayment" "IntraPartyPayment" "AgriculturalTransfer" "CommercialPayment" "PurchaseSaleOfGoodsAndServices" "SupplierPayment" "CharityPayment" "CompensationPayment" "PropertyLoanRepayment" "PropertyLoanSettlement" "PaymentOfInsuranceClaim" "LoanRepayment" "TradeSettlementPayment" "PaymentOfFees" "Gift" "InvoicePayment" "ForeignExchange" "Savings" "TaxPayment" "Utilities" "LotteryPayment" "PropertyCompletionPayment" "PropertyDeposit" "PropertyLoanDisbursement" "PropertyLoanRefinancing"

Payment purpose for CHAPS payment type

chapsCategoryPurpose
string or null (ChapsCategoryPurposeEnum)
Enum: "TradeSettlementPayment" "PersonToPersonPayment" "GovernmentPayment" "IntraCompanyPayment" "Loan" "OtherPayment" "SupplierPayment" "TaxPayment" "Trade" "TreasuryPayment"

Payment category purpose for CHAPS payment type

sortCode
required
string

The sort code of the recipient's bank

bankName
required
string

The name of the recipient's bank

bankAddress
required
string

The address of the recipient's bank

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., pence for GBP).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The account number of the recipient.

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
type
required
string (UKTransferTypeEnum)
Enum: "fps" "chaps"

The type of transfer, either 'fps' for Faster Payments Service or 'chaps' for CHAPS.

chapsPurpose
string or null (ChapsPurposeEnum)
Enum: "Deposit" "IntraCompanyPayment" "IntraPartyPayment" "AgriculturalTransfer" "CommercialPayment" "PurchaseSaleOfGoodsAndServices" "SupplierPayment" "CharityPayment" "CompensationPayment" "PropertyLoanRepayment" "PropertyLoanSettlement" "PaymentOfInsuranceClaim" "LoanRepayment" "TradeSettlementPayment" "PaymentOfFees" "Gift" "InvoicePayment" "ForeignExchange" "Savings" "TaxPayment" "Utilities" "LotteryPayment" "PropertyCompletionPayment" "PropertyDeposit" "PropertyLoanDisbursement" "PropertyLoanRefinancing"

Payment purpose for CHAPS payment type

chapsCategoryPurpose
string or null (ChapsCategoryPurposeEnum)
Enum: "TradeSettlementPayment" "PersonToPersonPayment" "GovernmentPayment" "IntraCompanyPayment" "Loan" "OtherPayment" "SupplierPayment" "TaxPayment" "Trade" "TreasuryPayment"

Payment category purpose for CHAPS payment type

sortCode
required
string

The sort code of the recipient's bank.

bankName
required
string

The name of the recipient's bank.

bankAddress
required
string

The address of the recipient's bank.

createdAt
string <date-time>

Timestamp when the transfer was created.

Request samples

Content type
application/json
{
  • "amount": 10000,
  • "currencyCode": "GBP",
  • "description": "Monthly rent payment",
  • "recipientName": "John Doe",
  • "recipientAccountNumber": "12345678",
  • "recipientAccountType": "individual",
  • "type": "fps",
  • "chapsPurpose": "Deposit",
  • "chapsCategoryPurpose": "TradeSettlementPayment",
  • "sortCode": "123456",
  • "bankName": "Example Bank Ltd",
  • "bankAddress": "1 Bank Street, London, UK"
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "status": "inprogress",
  • "accountId": "987654321-e89b-12d3-a456-426614174000",
  • "amount": 10000,
  • "fee": 100,
  • "total": 10100,
  • "currencyCode": "GBP",
  • "description": "Monthly rent payment",
  • "recipientName": "John Doe",
  • "recipientAccountNumber": "12345678",
  • "recipientAccountType": "individual",
  • "type": "fps",
  • "sortCode": "123456",
  • "bankName": "Example Bank Ltd",
  • "bankAddress": "1 Bank Street, London, UK",
  • "createdAt": "2023-09-15T14:30:00Z"
}

Retrieve UK Transfers

Retrieves a list of UK transfers for the specified account. This endpoint supports pagination.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) of the account

query Parameters
from
string <date>

The start date for the period (inclusive). Format: YYYY-MM-DD.

to
string <date>

The end date for the statement period (inclusive). Format: YYYY-MM-DD.

offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

The maximum number of items to return

Responses

Response Schema: application/json
Array
id
required
string <uuid>

Unique identifier for the transfer.

status
required
string (TransferStatusEnum)
Enum: "inprogress" "done" "error" "rejected" "sign_required" "canceled"

Current status of the transfer. Can be "inprogress", "done", "error", "rejected" or "sign_required".

accountId
required
string <uuid>

Unique identifier of the account from which the transfer is made.

amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., pence for GBP).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

total
required
integer <int64>

The total amount debited, including the transfer amount and fee.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

description
string

A description or reference for the transfer.

recipientName
string

The name of the transfer recipient.

recipientAccountNumber
required
string

The account number of the recipient.

recipientAccountType
required
string (RecipientAccountTypeEnum)
Enum: "individual" "company"
type
required
string (UKTransferTypeEnum)
Enum: "fps" "chaps"

The type of transfer, either 'fps' for Faster Payments Service or 'chaps' for CHAPS.

chapsPurpose
string or null (ChapsPurposeEnum)
Enum: "Deposit" "IntraCompanyPayment" "IntraPartyPayment" "AgriculturalTransfer" "CommercialPayment" "PurchaseSaleOfGoodsAndServices" "SupplierPayment" "CharityPayment" "CompensationPayment" "PropertyLoanRepayment" "PropertyLoanSettlement" "PaymentOfInsuranceClaim" "LoanRepayment" "TradeSettlementPayment" "PaymentOfFees" "Gift" "InvoicePayment" "ForeignExchange" "Savings" "TaxPayment" "Utilities" "LotteryPayment" "PropertyCompletionPayment" "PropertyDeposit" "PropertyLoanDisbursement" "PropertyLoanRefinancing"

Payment purpose for CHAPS payment type

chapsCategoryPurpose
string or null (ChapsCategoryPurposeEnum)
Enum: "TradeSettlementPayment" "PersonToPersonPayment" "GovernmentPayment" "IntraCompanyPayment" "Loan" "OtherPayment" "SupplierPayment" "TaxPayment" "Trade" "TreasuryPayment"

Payment category purpose for CHAPS payment type

sortCode
required
string

The sort code of the recipient's bank.

bankName
required
string

The name of the recipient's bank.

bankAddress
required
string

The address of the recipient's bank.

createdAt
string <date-time>

Timestamp when the transfer was created.

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "status": "done",
    • "accountId": "987654321-e89b-12d3-a456-426614174000",
    • "amount": 10000,
    • "fee": 100,
    • "total": 10100,
    • "currencyCode": "GBP",
    • "description": "Monthly rent payment",
    • "recipientName": "John Doe",
    • "recipientAccountNumber": "12345678",
    • "recipientAccountType": "individual",
    • "type": "fps",
    • "sortCode": "123456",
    • "bankName": "Example Bank Ltd",
    • "bankAddress": "1 Bank Street, London, UK",
    • "createdAt": "2023-09-15T14:30:00Z"
    },
  • {
    • "id": "234567890-e89b-12d3-a456-426614174000",
    • "status": "inprogress",
    • "accountId": "987654321-e89b-12d3-a456-426614174000",
    • "amount": 50000,
    • "fee": 500,
    • "total": 50500,
    • "currencyCode": "GBP",
    • "description": "Business invoice payment",
    • "recipientName": "ABC Company Ltd",
    • "recipientAccountNumber": "87654321",
    • "recipientAccountType": "company",
    • "type": "chaps",
    • "sortCode": "654321",
    • "bankName": "Business Bank PLC",
    • "bankAddress": "10 Corporate Avenue, Manchester, UK",
    • "createdAt": "2023-09-15T14:30:00Z"
    }
]

Retrieve UK Transfer Fees

Retrieves a list of UK transfers fees for the specified account.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) of the account

query Parameters
amount
required
integer <int64>
Example: amount=100000

Amount of the internal transfer

currencyCode
required
string <= 3 characters
Example: currencyCode=USD

Currency code of the internal transfer. ISO 4217 3-letter currency code.

recipientAccountNumber
required
string

Recipient's account number

recipientCountry
required
string <= 2 characters
Example: recipientCountry=DE

The country of the recipient's account. ISO 3166-1 alpha-2.

type
required
string (UKTransferTypeEnum)
Enum: "fps" "chaps"
Example: type=fps

Type of the transfer

Responses

Response Schema: application/json
amount
required
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., pence for GBP).

fee
required
integer <int64>

The fee charged for the transfer, in the smallest unit of the currency.

currencyCode
required
string <= 3 characters

The ISO 4217 currency code for the transfer.

recipientAccountNumber
required
string

The account number of the recipient.

type
required
string (UKTransferTypeEnum)
Enum: "fps" "chaps"

The type of transfer, either 'fps' for Faster Payments Service or 'chaps' for CHAPS.

sortCode
required
string

The sort code of the recipient's bank.

Response samples

Content type
application/json
[
  • {
    • "amount": 10000,
    • "fee": 100,
    • "currencyCode": "GBP",
    • "recipientAccountNumber": "12345678",
    • "type": "fps"
    }
]

FX Trades (soon)

Endpoints related to foreign exchange (FX) trades, including getting quotes and executing trades.

Create a FX quote

Create a quote for a foreign exchange transaction. Quotes are valid for 30 seconds.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which the internal transfer will be initiated.

Request Body schema: application/json
amount
integer <int64>

The transfer amount in the smallest unit of the currency (e.g., cents for USD).

fixedSide
string
Enum: "sell" "buy"

The side of the transaction that is fixed. 'sell' or 'buy'

buyCurrency
string

The currency code of the currency being bought.

sellCurrency
string

The currency code of the currency being sold.

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the foreign exchange quote.

amount
required
integer <int64>

The amount of the foreign exchange transaction.

fixedSide
required
string
Enum: "sell" "buy"
buyCurrency
required
string

The currency code of the currency being bought.

sellCurrency
required
string

The currency code of the currency being sold.

status
required
string
Enum: "pending" "expired" "executed" "cancelled"

The status of the foreign exchange quote.

expiresAt
required
string <date-time>

The date and time at which the quote expires.

Request samples

Content type
application/json
{
  • "amount": 100000,
  • "fixedSide": "sell",
  • "buyCurrency": "USD",
  • "sellCurrency": "EUR"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "amount": 100000,
  • "fixedSide": "sell",
  • "buyCurrency": "USD",
  • "sellCurrency": "EUR",
  • "status": "pending",
  • "expiresAt": "2024-09-16T14:32:00Z"
}

Execute an FX quote

Execute a foreign exchange transaction quote.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

accountId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier (GUID) for the account from which the internal transfer will be initiated.

quoteId
required
string <uuid>

The unique identifier for the quote.

Request Body schema: application/json
status
string
Value: "executed"

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the foreign exchange quote.

amount
required
integer <int64>

The amount of the foreign exchange transaction.

fixedSide
required
string
Enum: "sell" "buy"
buyCurrency
required
string

The currency code of the currency being bought.

sellCurrency
required
string

The currency code of the currency being sold.

status
required
string
Enum: "pending" "expired" "executed" "cancelled"

The status of the foreign exchange quote.

expiresAt
required
string <date-time>

The date and time at which the quote expires.

Request samples

Content type
application/json
{
  • "status": "executed"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "amount": 100000,
  • "fixedSide": "sell",
  • "buyCurrency": "USD",
  • "sellCurrency": "EUR",
  • "status": "executed",
  • "expiresAt": "2024-09-16T14:32:00Z"
}

Messages (soon)

Manage secure communication via messages in threads, which allows users to exchange information within the API.

Get all threads

Retrieves a list of all message threads. This endpoint supports pagination.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

The maximum number of items to return

Responses

Response Schema: application/json
Array
id
required
string <uuid>

Unique identifier for the thread.

clientId
required
string <uuid>

Unique identifier for the client associated with the thread.

subject
string [ 1 .. 255 ] characters

Subject of the thread.

createdAt
string <date-time>

Timestamp when the thread was created.

updatedAt
string <date-time>

Timestamp when the thread was last updated.

deletedAt
string or null <date-time>

Timestamp when the thread was deleted. Null if not deleted.

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "clientId": "123e4567-e89b-12d3-a456-426614174001",
    • "subject": "Meeting Request: Project Kickoff",
    • "createdAt": "2024-09-16T14:32:00Z",
    • "updatedAt": "2024-09-17T09:21:00Z",
    • "deletedAt": null
    },
  • {
    • "id": "234e5678-e89b-12d3-a456-426614174000",
    • "clientId": "345e6789-e89b-12d3-a456-426614174001",
    • "subject": "Follow-up on Contract Terms",
    • "createdAt": "2024-09-18T10:15:00Z",
    • "updatedAt": "2024-09-18T10:15:00Z",
    • "deletedAt": null
    }
]

Post a new thread

Creates a new message thread with an initial message. This endpoint allows clients to start a new conversation thread.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

Request Body schema: application/json
subject
required
string [ 1 .. 255 ] characters

Subject of the new thread

text
required
string [ 1 .. 255 ] characters

Text of the first message in the thread

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the thread.

clientId
required
string <uuid>

Unique identifier for the client associated with the thread.

subject
string [ 1 .. 255 ] characters

Subject of the thread.

createdAt
string <date-time>

Timestamp when the thread was created.

updatedAt
string <date-time>

Timestamp when the thread was last updated.

deletedAt
string or null <date-time>

Timestamp when the thread was deleted. Null if not deleted.

Request samples

Content type
application/json
{
  • "subject": "Request for Product Information",
  • "text": "Hello, I would like to inquire about your latest product line. Can you provide more details?"
}

Response samples

Content type
application/json
{
  • "id": "345e6789-e89b-12d3-a456-426614174000",
  • "clientId": "456e7890-e89b-12d3-a456-426614174001",
  • "subject": "Request for Product Information",
  • "createdAt": "2024-09-19T11:30:00Z",
  • "updatedAt": "2024-09-19T11:30:00Z",
  • "deletedAt": null
}

Retrieve a email thread

Fetches the details of a specific message thread. This endpoint returns comprehensive information about the thread.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

threadId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

Unique identifier of the thread to retrieve.

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the thread.

clientId
required
string <uuid>

Unique identifier for the client associated with the thread.

subject
string [ 1 .. 255 ] characters

Subject of the thread.

createdAt
string <date-time>

Timestamp when the thread was created.

updatedAt
string <date-time>

Timestamp when the thread was last updated.

deletedAt
string or null <date-time>

Timestamp when the thread was deleted. Null if not deleted.

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "clientId": "123e4567-e89b-12d3-a456-426614174001",
  • "subject": "Meeting Request: Project Kickoff",
  • "createdAt": "2024-09-16T14:32:00Z",
  • "updatedAt": "2024-09-17T09:21:00Z",
  • "deletedAt": null
}

Retrieve thread messages

Retrieves messages from a specific thread. This endpoint supports pagination.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

threadId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier of the thread

query Parameters
offset
integer >= 0
Default: 0
Example: offset=0

The number of items to skip before starting to collect the result set

limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

The maximum number of items to return

Responses

Response Schema: application/json
Array
id
required
string <uuid>

Unique identifier for the message.

threadId
required
string <uuid>

Unique identifier of the thread this message belongs to.

clientId
string <uuid>

Unique identifier of the client associated with this message, if applicable.

employeeId
string <uuid>

Unique identifier of the employee associated with this message, if applicable.

text
required
string [ 1 .. 255 ] characters

The content of the message. Must be between 1 and 255 characters.

createdAt
required
string <date-time>

Timestamp of when the message was created.

updatedAt
string <date-time>

Timestamp of the last update to the message, if any.

deletedAt
string <date-time>

Timestamp of when the message was deleted, if applicable.

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "threadId": "234e5678-e89b-12d3-a456-426614174000",
    • "clientId": null,
    • "employeeId": "456e7890-e89b-12d3-a456-426614174000",
    • "text": "Hello, how can I assist you today?",
    • "createdAt": "2023-09-16T10:30:00Z",
    • "updatedAt": "2023-09-16T10:30:00Z",
    • "deletedAt": null
    },
  • {
    • "id": "567e8901-e89b-12d3-a456-426614174000",
    • "threadId": "234e5678-e89b-12d3-a456-426614174000",
    • "clientId": "345e6789-e89b-12d3-a456-426614174000",
    • "employeeId": null,
    • "text": "I have a question about my account balance.",
    • "createdAt": "2023-09-16T10:35:00Z",
    • "updatedAt": "2023-09-16T10:35:00Z",
    • "deletedAt": null
    }
]

Post a message

Adds a new message to a specific thread. This endpoint allows clients or employees to post messages in an ongoing conversation.

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

threadId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier of the thread to post the message to

Request Body schema: application/json
text
required
string [ 1 .. 255 ] characters

The content of the message

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier for the message.

threadId
required
string <uuid>

Unique identifier of the thread this message belongs to.

clientId
string <uuid>

Unique identifier of the client associated with this message, if applicable.

employeeId
string <uuid>

Unique identifier of the employee associated with this message, if applicable.

text
required
string [ 1 .. 255 ] characters

The content of the message. Must be between 1 and 255 characters.

createdAt
required
string <date-time>

Timestamp of when the message was created.

updatedAt
string <date-time>

Timestamp of the last update to the message, if any.

deletedAt
string <date-time>

Timestamp of when the message was deleted, if applicable.

Request samples

Content type
application/json
{
  • "text": "Thank you for your assistance."
}

Response samples

Content type
application/json
{
  • "id": "678e9012-e89b-12d3-a456-426614174000",
  • "threadId": "234e5678-e89b-12d3-a456-426614174000",
  • "clientId": "345e6789-e89b-12d3-a456-426614174000",
  • "employeeId": null,
  • "text": "Thank you for your assistance.",
  • "createdAt": "2023-09-16T11:00:00Z",
  • "updatedAt": "2023-09-16T11:00:00Z",
  • "deletedAt": null
}

Webhooks (soon)

Webhooks enable real-time notifications for specific events such as account updates, payments, and message delivery.

Retrieve all registered webhooks

Retrieves a list of all registered webhooks. This endpoint returns comprehensive information about each webhook, including its configuration, status, and last call details.

Authorizations:
bearerAuth

Responses

Response Schema: application/json
Array
id
string <uuid>
name
required
string

Webhook name

callbackURL
required
string <uri>
HMACKey
string

HMAC hash secret key

isActive
boolean
Default: true

status

lastCallAt
string or null <date-time>

Last call date

lastCallStatus
string or null

Last call status

createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>

Response samples

Content type
application/json
[
  • {
    • "id": "123e4567-e89b-12d3-a456-426614174000",
    • "name": "Account Updates Webhook",
    • "HMACKey": "secretkey123",
    • "isActive": true,
    • "lastCallAt": "2024-09-19T10:15:00Z",
    • "lastCallStatus": "success",
    • "createdAt": "2024-09-16T14:32:00Z",
    • "updatedAt": "2024-09-19T10:15:00Z",
    • "deletedAt": null
    },
  • {
    • "id": "234e5678-e89b-12d3-a456-426614174000",
    • "name": "Payment Notifications",
    • "HMACKey": "secretkey456",
    • "isActive": false,
    • "lastCallAt": "2024-09-18T09:30:00Z",
    • "lastCallStatus": "failed",
    • "createdAt": "2024-09-17T11:00:00Z",
    • "updatedAt": "2024-09-18T09:30:00Z",
    • "deletedAt": null
    }
]

Register a new webhook

Creates a new webhook registration. This endpoint allows you to set up a new webhook to receive notifications for specific events. The webhook will be created in an active state and will start receiving event notifications immediately.

Webhook will be deactivated if 10 consecutive calls fail.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

A descriptive name for the webhook

callbackURL
required
string <uri>

The URL where webhook notifications will be sent

Responses

Response Schema: application/json
id
string <uuid>
name
required
string

Webhook name

callbackURL
required
string <uri>
HMACKey
string

HMAC hash secret key

isActive
boolean
Default: true

status

lastCallAt
string or null <date-time>

Last call date

lastCallStatus
string or null

Last call status

createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "345e6789-e89b-12d3-a456-426614174000",
  • "name": "Gemba Webhook",
  • "HMACKey": "newlygeneratedsecretkey789",
  • "isActive": true,
  • "lastCallAt": null,
  • "lastCallStatus": null,
  • "createdAt": "2024-09-20T15:30:00Z",
  • "updatedAt": "2024-09-20T15:30:00Z",
  • "deletedAt": null
}

Activate or deactivate a registered webhook

This endpoint allows you to activate or deactivate a previously registered webhook. Activating a webhook enables it to receive event notifications, while deactivating it suspends notifications without deleting the webhook configuration.

Authorizations:
bearerAuth
path Parameters
webhookId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier of the webhook to update.

Request Body schema: application/json
isActive
required
boolean

Set to true to activate the webhook, false to deactivate it.

Responses

Response Schema: application/json
id
string <uuid>
name
required
string

Webhook name

callbackURL
required
string <uri>
HMACKey
string

HMAC hash secret key

isActive
boolean
Default: true

status

lastCallAt
string or null <date-time>

Last call date

lastCallStatus
string or null

Last call status

createdAt
string <date-time>
updatedAt
string or null <date-time>
deletedAt
string or null <date-time>

Request samples

Content type
application/json
{
  • "isActive": true
}

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "name": "Account Updates Webhook",
  • "callbackURL": "https://example.com/webhook",
  • "HMACKey": "secretkey123",
  • "isActive": true,
  • "lastCallAt": "2024-09-19T10:15:00Z",
  • "lastCallStatus": "success",
  • "createdAt": "2024-09-16T14:32:00Z",
  • "updatedAt": "2024-09-19T10:15:00Z",
  • "deletedAt": null
}

Delete a registered webhook

This endpoint allows you to permanently delete a registered webhook. Once deleted, the webhook will no longer receive any event notifications. This action cannot be undone.

Authorizations:
bearerAuth
path Parameters
webhookId
required
string <uuid>
Example: 123e4567-e89b-12d3-a456-426614174000

The unique identifier of the webhook to delete.

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Lists

Endpoints related to additional informational lists.

Prohibited industries

Retrieves the list of prohibited industries

Responses

Response Schema: application/json
Array
industryCode
integer

The code representing the industry

industryName
string

The name of the industry

Response samples

Content type
application/json
[
  • {
    • "industryCode": 7143746,
    • "industryName": "Arms Trade and defense"
    }
]

Restricted industries

Retrieves the list of restricted industries that require additional due diligence

Responses

Response Schema: application/json
Array
industryCode
integer

The code representing the industry

industryName
string

The name of the industry

Response samples

Content type
application/json
[
  • {
    • "industryCode": 7143722,
    • "industryName": "Gambling/gaming/betting activities"
    }
]

Elevated risk industries

The business has determined the following economic or other activities to be of elevated risk

Responses

Response Schema: application/json
Array
industryCode
integer

The code representing the industry

industryName
string

The name of the industry

Response samples

Content type
application/json
[
  • {
    • "industryCode": 7143767,
    • "industryName": "Consultancy services"
    }
]

High risk transaction fee (HRT) countries

Retrieves the list of high risk transaction fee countries. High risk transaction fee may be applied to payments to/from the following countries

Responses

Response Schema: application/json
Array
CountryISO
string

The ISO code of the country

countryFullName
string

The full name of the country

Response samples

Content type
application/json
[
  • {
    • "CountryISO": "ALB",
    • "countryFullName": "Albania"
    }
]

High risk countries

Retrieves the list of high risk countries.

Responses

Response Schema: application/json
Array
CountryISO
string

The ISO code of the country

countryFullName
string

The full name of the country

Response samples

Content type
application/json
[
  • {
    • "CountryISO": "ALB",
    • "countryFullName": "Albania"
    }
]

Prohibited countries

Retrieves the list of prohibited countries.

Responses

Response Schema: application/json
Array
CountryISO
string

The ISO code of the country

countryFullName
string

The full name of the country

Response samples

Content type
application/json
[
  • {
    • "CountryISO": "BLR",
    • "countryFullName": "Belarus"
    }
]

Services

Additional informational and utility services.

(Sandbox) Send operation confirmation code (OTP)

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

Request Body schema: application/json
objectType
string (OTPObjectTypeEnum)
Value: "transfer"
objectId
string <uuid>

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the transfer confirmation.

type
required
string
Default: "sms"
Enum: "sms" "email"

The type of transfer confirmation.

code
string or null

The confirmation code. Sandbox only

status
required
string
Enum: "confirmed" "sent" "expired"

The status of the internal transfer confirmation

expiresAt
required
string <date-time>

The timestamp when the transfer was confirmed.

Request samples

Content type
application/json
{
  • "objectType": "transfer",
  • "objectId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "type": "sms",
  • "status": "sent",
  • "expiresAt": "2024-09-16T14:32:00Z"
}

(Sandbox) Validate confirmation code (OTP)

Validate OTP code

Authorizations:
bearerAuth
path Parameters
clientId
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

The unique identifier for the client. This is a GUID that represents the client.

Request Body schema: application/json
objectType
string (OTPObjectTypeEnum)
Value: "transfer"
objectId
string <uuid>
code
required
string

The OTP to confirm the transfer.

Responses

Response Schema: application/json
id
required
string <uuid>

The unique identifier for the transfer confirmation.

type
required
string
Default: "sms"
Enum: "sms" "email"

The type of transfer confirmation.

code
string or null

The confirmation code. Sandbox only

status
required
string
Enum: "confirmed" "sent" "expired"

The status of the internal transfer confirmation

expiresAt
required
string <date-time>

The timestamp when the transfer was confirmed.

Request samples

Content type
application/json
{
  • "code": "123456"
}

Response samples

Content type
application/json
{
  • "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  • "type": "sms",
  • "status": "confirmed",
  • "expiresAt": "2024-09-16T14:32:00Z"
}