Transaction

This endpoint retrieves available payment schemes between an origin and destination bank account. Each scheme might also come with extra parameters required by the provider to process the payment. These fields will be dynamically rendered on the UI to match the integrator's payment flow.

The response includes:

  • A list of available payment schemes
  • Optional metadata (like form fields) required for each scheme
  • A status object describing the success of the API call

Response structure

{
    "data": [
        {
            "code": "PAYMENT_SCHEME",
            "customParameter": {
                "label": {
                    "en": "string",
                    "es": "string",
                    "zh": "string"
                },
                "hint": {
                    "en": "string",
                    "es": "string",
                    "zh": "string"
                },
                "type": "select | text",
                "required": boolean,
                "editable": boolean,
                "options": [
                    {
                        "id": "string",
                        "name": {
                            "en": "string",
                            "es": "string",
                            "zh": "string"
                        }
                    },
                    {
                        "id": "string",
                        "name": {
                            "en": "string",
                            "es": "string",
                            "zh": "string"
                        }
                    }
                ]
            }
        },
        {
            "code": "PAYMENT_SCHEME"
        }
    ],
    "code": "OK",
    "errorSeverity": "NONE",
    "message": "Ok",
    "httpStatus": 200,
    "requestId": "833e05a3-a7f0-4ead-9570-210931ccecd1",
    "date": "2025-04-02T11:57:48.576Z"
}

Response breakdown

data[] should return a list of available payment schemes. Each item contains:

  • code (required): A string indicating the payment scheme (e.g. SEPA, SWIFT). Read full list here.
  • If there are any other keys (like SDR, purpose code ), treat them as custom parameters (one or more are allowed to be sent per payment scheme). Each custom parameter object includes:

Field

Required

Purpose

parameterName

Name of the custom parameter. ❗ DO NOT use purposeCode as a parameter key — it’s reserved internally by Toqio. To prevent conflicts with reserved parameters, consider using a custom name like purposeCode_integrationName.

label

User-facing name of the field; "en" is required. Others (es, zh,) are optional.

type

Determines input field type. "text" or "select"

hint

Extra info below the label

required

Boolean, for form validation

editable

Boolean, controls if field is user-editable

options

Required if type = select

Array of selector values; "en" is required. Others (es, zh, etc.) are optional.

Example

{
    "data": [
        {
            "code": "UK_FASTER_PAYMENTS"
        },
        {
            "code": "CHAPS",
            "paymentPurpose": {
                "label": {
                    "en": "Purpose code",
                    "es": "Código de propósito",
                    "zh": "用途代碼"
                },
                "hint": {
                    "en": "Field clarification text",
                    "es": "Texto clarificativo del campo",
                    "zh": "..."
                },
                "type": "select",
                "required": true,
                "editable": true,
                "options": [
                    {
                        "id": "CODE_1",
                        "name": {
                            "en": "Purpose code 1",
                            "es": "Nombre en español CODE_1",
                            "zh": "中文名称 CODE_1"
                        }
                    },
                    {
                        "id": "CODE_2",
                        "name": {
                            "en": "Purpose code 2",
                            "es": "Nombre en español CODE_2",
                            "zh": "中文名称 CODE_2"
                        }
                    }
                ]
            }
        }
    ],
    "code": "OK",
    "errorSeverity": "NONE",
    "message": "Ok",
    "httpStatus": 200,
    "requestId": "833e05a3-a7f0-4ead-9570-210931ccecd1",
    "date": "2025-04-02T11:57:48.576Z"
}

Toqio includes the custom fields exactly as they were defined in the Get Payment Schemes response — using the same parameterName. System integrators should expect those fields (with user input) in the body of the Save Transfer https://integrate.toq.io/reference/savetransfer#/ request from Toqio to the integrator.

Example request body:

..., // transfer object  
paymentPurpose: "CODE_1"

Display custom parameter data to enduser

The custom parameter is dynamic and not stored by Toqio. By default, it will not be displayed to the end user. If the integrator wishes to display it in the transaction details, it must be included in the dynamicFields object of the Save Transaction webhook.

Read more here.

Additional information:

If your integration is sending the response in the old format (as shown below), it is also accepted by Toqio — there is no need to update.

{  
    “data”: [
        “SEPA”, “SEPA_INSTANT”
    ],
    “code”: “OK”,
    “errorSeverity”: “NONE”,
    “message”: “Ok”,
    “httpStatus”: 200,
    “requestId”: “b2e98b35-63cd-4fcc-8452-ea030161d532",
    “date”: “2025-02-05T07:54:47.392Z”
}