Multi-currency payments

You can send individual or bulk high value payments overseas in currencies other than GBP. Before making high value international payments, you'll first need to fund your simulation account in line with our fund assessment control framework.

ClearBank accepts inbound and outbound EUR payments via the payment schemes T2 and SEPA Credit Transfer (SCT). For more details about EUR payments processed via SCT, refer to SEPA Credit Transfer UK.

Non-EUR high value international payments are settled according to cut-off times specific to the currency in which the payment is made.

For up to date information on the countries you can send high value multi-currency payments to and the available currencies ClearBank supports (and their respective cut-off times), please speak with your Client Director.

If a multi-currency payment request is received outside of the payment window for a given currency, you will normally receive a success response (202 - Accepted) including an isScheduled Boolean field. This will be set to true, indicating that the payment was received out-of-window and will be processed on the next available business day. If the field is set to false, the payment will be processed in the currently open payment window.

When a payment is scheduled for processing on the next available business day, the time at which the payment will be processed will vary depending on the currency selected as follows:

Currency	Currency Code	Window Open Time	Window Close Time	Scheduled Payment Time
Canadian dollar	CAD	07:00 AM	17:00 PM	08:30 AM
Swiss franc	CHF	07:00 AM	11:00 AM	08:30 AM
Czech koruna	CZK	07:00 AM	08:30 AM	08:20 AM
Danish krone	DKK	07:00 AM	11:00 AM	08:30 AM
Euro	EUR	07:00 AM	14:30 PM	08:30 AM
Hungarian forint	HUF	07:00 AM	09:30 AM	08:30 AM
Norwegian krone	NOK	07:00 AM	11:00 AM	08:30 AM
Polish zloty	PLN	07:00 AM	09:30 AM	08:30 AM
Romanian leu	RON	07:00 AM	08:30 AM	08:20 AM
Swedish krona	SEK	07:00 AM	11:00 AM	08:30 AM
United States dollar	USD	07:00 AM	17:00 PM	08:30 AM

If you would prefer not to have the rescheduled payment processed, you can cancel the payment by using the cancellation endpoints. The cancellation must be received no later than 1 hour prior to the scheduled processing time. Note that to be able to cancel a payment, you must have specified a batch ID in the original payment request.

Use DELETE /v1/mccy/payments/{batchId} to cancel a whole batch of payments
Use DELETE /v1/mccy/payments/{batchId}/{endToEndId} to cancel a single payment or an individual payment within a batch

Fund your account in the simulation environment

post/v1/mccy/inboundpayment/{accountUniqueId}

This endpoint is meant for the simulation environment only as it enables you to make an inbound payment into your account in our simulation environment.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.
accountUniqueId string, path, Required
The unique identifier for the account. This will be the currency supported by the account e.g., EUR.

Request Payload (application/json)

instructedCurrency string, Required
Currency of the instructed payment. This is the three-letter ISO currency code.
Enum array
EUR, USD, CAD, CHF, CZK, DKK, HUF, NOK, PLN, RON, SEK
instructedAmount number, Required
Instructed payment amount.
Minimum
0.01
Maximum
999999999.99
reference string
Reference provided by the ultimate debtor for the payment.
Minimum length
0
Maximum length
140
endToEndId string
Unique identifier supplied by you in your API request to simulate the sending bank's reference.
Minimum length
0
Maximum length
15
ultimateCreditor object, Required
Information about the ultimate creditor of the transaction.
ultimateDebtor object
Information about the ultimate debtor of the transaction.

request

{
  "instructedCurrency": "EUR",
  "instructedAmount": 2345.67,
  "reference": "Human readable example text",
  "endToEndId": "87654321",
  "ultimateCreditor": {
    "iban": "GB14BARC20031838591122",
    "name": "Rob Robinson",
    "address": "1 High St Northleach Gloucestershire"
  },
  "ultimateDebtor": {
    "identifier": "IE29AIBK99082942345625",
    "name": "Joe Bloggs",
    "address": "2 Main St Dublin"
  }
}

Code copied

Response (application/json)

201 Successful operation.
400 Bad Request. Check query parameters.
404 Not Found. AccountUniqueId not recognized.

Successful operation.

{
  "transactionId": "c8f18c69-927a-5233-ab5a-14a8d60e754e",
  "instructedCurrency": "EUR",
  "instructedAmount": 2345.67,
  "reference": "Human readable example text",
  "endToEndId": "87654321",
  "ultimateCreditorIBAN": "GB14BARC20031838591122",
  "ultimateCreditorName": "Rob Robinson",
  "ultimateDebtorIdentifier": "IE29AIBK99082942345625",
  "ultimateDebtorName": "Joe Bloggs",
  "timestampCreated": "2025-02-19T11:32:10.934Z",
  "bankRefSearchable": "Reference generated by ClearBank"
}

Code copied

Bad Request. Check query parameters.

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found. AccountUniqueId not recognized.

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Initiate a payment

post/v1/mccy/payments

This endpoint is used to initiate payments.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

batchId string
Unique identifier for the batch in which the payment is being submitted. (GUID format 128-bit label). You must set a batch ID to be able to cancel a payment.
currencyCode string, Required
Three-letter ISO currency code for the outbound payment. This field is case insensitive.
Minimum length
3
Maximum length
3
Enum array
EUR, USD, CAD, CHF, CZK, DKK, HUF, NOK, PLN, RON, SEK
transactions array, Required
Array of transactions. The maximum batch size is 100.

request

{
  "batchId": "d7cc6fda-52a5-5ba8-a03e-303746dc2501",
  "currencyCode": "EUR",
  "transactions": [
    {
      "endToEndId": "pd0G4d9XCLOzpM5lBA86YNXU8KU3I0etZ5T",
      "reference": "Human readable example text",
      "amount": 1234.56,
      "creditor": {
        "name": "Newell Saunders",
        "address": {
          "addressLine1": "123A",
          "addressLine2": "Wren Way",
          "addressLine3": "Hamlinton",
          "postCode": "NN87 2335",
          "country": "PT"
        },
        "bic": "1A2BPT12AB3",
        "identification": {
          "organisationIdentification": {
            "Other": {
              "identification": "string",
              "schemeName": {
                "code": "BDID",
                "proprietary": "Other identification scheme name"
              },
              "issuer": "Identification authority name"
            }
          },
          "privateIdentification": {
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1995-12-27",
              "cityOfBirth": "Lisbon",
              "countryOfBirth": "PT"
            },
            "other": {
              "identification": "020696623",
              "schemeName": {
                "code": "CCPT",
                "proprietary": "Other identification scheme name"
              }
            }
          }
        },
        "countryOfResidence": "PT",
        "contactDetails": {
          "name": "Ryan Christensen",
          "emailAddress": "tokchri@business.eu"
        },
        "iban": "ES9242020418450222051122",
        "accountNumber": "0222051122",
        "schemeName": {
          "code": "TRAS",
          "proprietary": "Example other identification scheme"
        }
      },
      "debtorName": "Bradley Kennedy",
      "debtorAddress": {
        "addressLine1": "Green House",
        "addressLine2": "Purple Lane",
        "addressLine3": "Orange District",
        "postCode": "CB2 5AB",
        "country": "GB"
      },
      "debtorBic": "ABCDNLAA123",
      "debtorPrivateIdentification": {
        "dateAndPlaceOfBirth": {
          "dateOfBirth": "1962-02-21",
          "cityOfBirth": "Paris",
          "countryOfBirth": "France"
        },
        "other": {
          "identification": "string",
          "schemeName": {
            "code": "CCPT",
            "proprietary": "Other identification scheme name"
          }
        }
      },
      "accountIdentifier": {
        "kind": "AccountId",
        "identifier": "GB22CBUK60109839856819"
      },
      "debtorAccountCurrency": "EUR",
      "intermediaryAgent": {
        "FinancialInstitutionIdentification": {
          "bic": "NL91CBNL0215162201",
          "aba": "376582168",
          "name": "Intermediary Agent Financial Institution",
          "addressDetails": {
            "addressLine1": "12 Banking Building",
            "addressLine2": "Bank Street",
            "addressLine3": "Belfast",
            "postCode": "BT1 5GS",
            "country": "GB"
          }
        }
      },
      "creditorAgent": {
        "FinancialInstitutionIdentification": {
          "bic": "CBUKGBA132S",
          "aba": "853688941",
          "clearingSystemIdCode": "GBDSC",
          "memberId": "30-12-77",
          "name": "Big FI Corp",
          "addressDetails": {
            "addressLine1": "11 The Square",
            "addressLine2": "Circle District",
            "addressLine3": "Sphere City",
            "postCode": "SP1 8NY",
            "country": "GB"
          }
        },
        "branchId": "Big FI Outbound Salisbury"
      },
      "instructionForDebtorAgent": "Example further instruction text",
      "purpose": {
        "code": "SUPP",
        "proprietary": "Other non-codified purpose"
      },
      "remittanceInformation": {
        "additionalRemittanceInformation": "Example unstructured information"
      },
      "ultimateCreditor": {
        "name": "Amanda Myers",
        "address": {
          "addressLine1": "21 Cyan",
          "addressLine2": "Fontainebleau",
          "addressLine3": "Île-de-France",
          "postCode": "77300",
          "country": "FR"
        },
        "bic": "ABBAFRA112A",
        "identification": {
          "organisationIdentification": {
            "Other": {
              "identification": "BE29539003417022",
              "schemeName": {
                "code": "CUST",
                "proprietary": "Example other identification scheme"
              },
              "issuer": "string"
            }
          },
          "privateIdentification": {
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1975-11-22",
              "cityOfBirth": "Copenhagen",
              "countryOfBirth": "DK"
            },
            "other": {
              "identification": "139748154",
              "schemeName": {
                "code": "CCPT",
                "proprietary": "Example other identification scheme"
              }
            }
          }
        }
      }
    }
  ]
}

Code copied

Response (application/json)

202 Accepted
400 Bad Request
404 Not Found
406 Not Acceptable
409 Conflict
422 Unprocessable Entity
500 Server Error
503 Server Error

Accepted

{
  "isScheduled": true
}

Code copied

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Acceptable

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Conflict

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Unprocessable Entity

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Transaction Created webhook
Multi-currency Transaction Settled webhook
Multi-currency Transaction Cancelled webhook
Multi-currency Payment Assessment Failed webhook
Multi-currency Payment Validation Failed webhook

This webhook confirms that a multi-currency transaction has been created.

Request body

{
    "Type":"Payments.Mccy.TransactionCreated",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Min. Length: `1` Format: `GUID`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate creditor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`UltimateDebtorName`	Required Name of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateDebtorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate debtor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`SchemePaymentMethod`	Required Payment scheme used for submitting the transaction. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time transaction was created. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Identifiers`	Required List of identifiers. It is an array of objects with a `Scope`, `Name` and `Identifier`. Type: `array` `Scope` Type: `string` Min. Length: `1` Max. Lenght: `50` `Name` Type: `string` Min. Length: `1` Max. Lenght: `50` `Identifier` Type: `string` Min. Length: `1` Max. Lenght: `250`
`AdditionalProperties`	Required List of additional information. It is an array of objects with a `Key` and `Value`. Type: `array` `Key` Type: `string` Min. Length: `1` Max. Lenght: `50` `Value` Type: `string` Min. Length: `1` Max. Lenght: `250`

Example transaction created webhook request body

{
    "TransactionId":"fd7f3082-72d4-46b3-8e0e-1f66e4a91e13",
    "BatchId":"ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId":"08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId":"4026da87bb0f4a5",
    "AccountId":"50daac8a-72c3-4ae5-a6e3-e71b6187dbef",
    "Reference":"My payment reference 12345",
    "UltimateCreditorName":"John Baker",
    "UltimateCreditorAccountIdentifiers":[
        {
            "Kind":"AccountId",
            "Identifier":"fd75710b-4c0a-406d-a962-ef5c98836d3f"
        }
    ],
    "UltimateDebtorName":"Clark Kent",
    "UltimateDebtorAccountIdentifiers":[
        {
            "Kind":"IBAN",
            "Identifier":"GB33BUKB20201555555555"
        }
    ],
    "InstructedAmount":100.55,
    "InstructedCurrency":"EUR",
    "SchemePaymentMethod":"Partner 1",
    "TimestampCreated":"2021-05-22T00:00:00",
    "Identifiers":[
        {
            "Scope":"MCCYOutboundPayments",
            "Name":"SchemeEndToEndId",
            "Identifier":"4026da87bb0f4a5"
        }
    ],
    "AdditionalProperties":[
        {
            "Key":"DebtorName",
            "Value":"Acme Studios"
        },
        {
            "Key":"DebtorCountry",
            "Value":"GB"
        }
    ]
},
    "Nonce":748352091
}

Example webhook response

{
    "Nonce": 748352091
}

This webhook confirms that an inbound or outbound multi-currency transaction has settled.

Request body

{
    "Type":"Payments.Mccy.TransactionSettled",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Min. Length: `1` Format: `GUID`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate creditor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`UltimateDebtorName`	Required Name of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateDebtorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate debtor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`SchemePaymentMethod`	Required Payment scheme used for submitting the transaction. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time transaction was created. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Identifiers`	Required List of identifiers. It is an array of objects with a `Scope`, `Name` and `Identifier`. Type: `array` `Scope` Type: `string` Min. Length: `1` Max. Lenght: `50` `Name` Type: `string` Min. Length: `1` Max. Lenght: `50` `Identifier` Type: `string` Min. Length: `1` Max. Lenght: `250`
`AdditionalProperties`	Required List of additional information. It is an array of objects with a `Key` and `Value`. Type: `array` `Key` Type: `string` Min. Length: `1` Max. Lenght: `50` `Value` Type: `string` Min. Length: `1` Max. Lenght: `250`
`TimestampSettled`	Required Date and time the transaction settled. Type: `string` Min. Length: `1` Format: `date-time`
`TimestampSubmitted`	Required Date and time transaction was submitted. This should be the same as the date and time of TimestampSettled but will reflect a different time if the transaction settlement is delayed. This time will represent the time the transaction should have settled had it not been delayed. Type: `string` Min. Length: `1` Format: `date-time`

Example transaction settled webhook request body

{
    "TransactionId": "fd7f3082-72d4-46b3-8e0e-1f66e4a91e13",
    "BatchId": "ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId": "08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId": "4026da87bb0f4a5",
    "AccountId": "50daac8a-72c3-4ae5-a6e3-e71b6187dbef",
    "Reference": "My payment reference 12345",
    "UltimateCreditorName": "John Baker",
    "UltimateCreditorAccountIdentifiers": [
        {
            "Kind": "AccountId",
            "Identifier": "fd75710b-4c0a-406d-a962-ef5c98836d3f"
        }
    ],
    "UltimateDebtorName": "Clark Kent",
    "UltimateDebtorAccountIdentifiers": [
        {
            "Kind": "IBAN",
            "Identifier": "GB33BUKB20201555555555"
        }
    ],
    "InstructedAmount": 100.55,
    "InstructedCurrency": "EUR",
    "SchemePaymentMethod": "Partner 1",
    "TimestampCreated": "2021-05-22T00:00:00",
    "Identifiers": [
        {
            "Scope": "MCCYOutboundPayments",
            "Name": "SchemeEndToEndId",
            "Identifier": "4026da87bb0f4a5"
        }
    ],
    "AdditionalProperties": [
        {
            "Key": "DebtorName",
            "Value": "Acme Studios"
        },
        {
            "Key": "DebtorCountry",
            "Value": "GB"
        }
    ],
    "TimestampSettled": "2020-09-13T012:22:17.4",
    "TimestampSubmitted": "2020-09-13T011:26:15.1"
},
    "Nonce":761164091
}

Example webhook response

{
    "Nonce": 761164091
}

This webhook confirms that an outbound multi-currency transaction has been cancelled.

Request body

{
    "Type":"Payments.Mccy.TransactionCancelled",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Min. Length: `1` Format: `GUID`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate creditor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`UltimateDebtorName`	Required Name of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateDebtorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate debtor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`SchemePaymentMethod`	Required Payment scheme used for submitting the transaction. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time transaction was created. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Identifiers`	Required List of identifiers. It is an array of objects with a `Scope`, `Name` and `Identifier`. Type: `array` `Scope` Type: `string` Min. Length: `1` Max. Lenght: `50` `Name` Type: `string` Min. Length: `1` Max. Lenght: `50` `Identifier` Type: `string` Min. Length: `1` Max. Lenght: `250`
`AdditionalProperties`	Required List of additional information. It is an array of objects with a `Key` and `Value`. Type: `array` `Key` Type: `string` Min. Length: `1` Max. Lenght: `50` `Value` Type: `string` Min. Length: `1` Max. Lenght: `250`
`TimestampCancelled`	Required Date and time transaction was cancelled. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`CancellationCode`	Required Cancellation code. Type: `string` Min. Length: `1`
`CancellationReason`	Required Reason transaction was cancelled. Type: `string` Min. Length: `1`

Example transaction cancelled webhook request body

{
    "TransactionId": "fd7f3082-72d4-46b3-8e0e-1f66e4a91e13",
    "BatchId": "ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId": "08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId": "4026da87bb0f4a5",
    "AccountId": "50daac8a-72c3-4ae5-a6e3-e71b6187dbef",
    "Reference": "My payment reference 12345",
    "UltimateCreditorName": "John Baker",
    "UltimateCreditorAccountIdentifiers": [
        {
            "Kind": "AccountId",
            "Identifier": "fd75710b-4c0a-406d-a962-ef5c98836d3f"
        }
    ],
    "UltimateDebtorName": "Clark Kent",
    "UltimateDebtorAccountIdentifiers": [
        {
            "Kind": "IBAN",
            "Identifier": "GB33BUKB20201555555555"
        }
    ],
    "InstructedAmount": 100.55,
    "InstructedCurrency": "EUR",
    "SchemePaymentMethod": "Partner 1",
    "TimestampCreated": "2021-05-22T00:00:00",
    "Identifiers": [
        {
            "Scope": "MCCYOutboundPayments",
            "Name": "SchemeEndToEndId",
            "Identifier": "4026da87bb0f4a5"
        }
    ],
    "AdditionalProperties": [
        {
            "Key": "DebtorName",
            "Value": "Acme Studios"
        },
        {
            "Key": "DebtorCountry",
            "Value": "GB"
        }
    ],
    "TimestampCancelled": "2020-09-13T09:26:15.1762781",
    "CancellationCode": "RejectedByScheme",
    "CancellationReason": "Contact ClearBank for more details"
},
    "Nonce":748364091
}

Example webhook response

{
    "Nonce": 748364091
}

This webhook confirms that an outbound multi-currency payment has failed assessment.

Currently, the only scenario which can trigger this event includes insufficient balance to cover payments.

Request body

{
    "Type":"Payments.Mccy.PaymentAssessmentFailed",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`Error`	Required Error which caused the payment assessment to fail. Type: `string` Min. Length: `1` Max. Length: `280`
`UltimateDebtorName`	Optional Name of the ultimate debtor making the payment. Type: `string` Min. Length: `0` Max. Length: `143`
`UltimateDebtorAccount`	Required Account details of the ultimate debtor making the payment. Type: `string` Min. Length: `5` Max. Length: `36`
`UltimateDebtorAccountIdentifier`	Required Account identifier used to uniquely identify the ultimate debtor. Valid values are IBAN or AccountId. Type: `string` Min. Length: `1`
`UltimateDebtorAddressLine1`	Required First line of the ultimate debtor's address. Type: `string` Min. Length: `1` Max. Length: `70`
`UltimateDebtorAddressLine2`	Optional Second line of the ultimate debtor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateDebtorAddressLine3`	Optional Third line of the ultimate debtor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateDebtorPostCode`	Required Postcode of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `16`
`UltimateDebtorCountryCode`	Required Country code for the ultimate debtor's address. This is the 2-letter ISO country code. Type: `string` Min. Length: `2` Max. Length: `2` Pattern: `^[A-Z]{2}$`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-digit ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`UltimateCreditorIBAN`	Optional IBAN for the ultimate creditor. Mandatory only if Ultimate Creditor Account Number is not provided. Type: `string` Min. Length: `0` Max. Length: `34`
`UltimateCreditorAccountNumber`	Optional Account Number used to uniquely identify the ultimate creditor's account. Mandatory only if Ultimate Creditor IBAN is not provided. Type: `string` Min. Length: `0` Max. Length: `34`
`UltimateCreditorBic`	Optional BIC for the ultimate creditor. Type: `string` Min. Length: `8` Max. Length: `11` Pattern: `^[A-Z]{6}[A-Z2-9][A-NP-Z1-9]([A-Z0-9]{3})?$`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAddressLine1`	Required First line of the ultimate creditor's address. Type: `string` Min. Length: `1` Max. Length: `70`
`UltimateCreditorAddressLine2`	Optional Second line of the ultimate creditor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateCreditorAddressLine3`	Optional Third line of the ultimate creditor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateCreditorPostCode`	Required Postcode of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `16`
`UltimateCreditorCountryCode`	Required Country code for the ultimate creditor's address. This is the 2-letter ISO country code. Type: `string` Min. Length: `2` Max. Length: `2` Pattern: `^[A-Z]{2}$`
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`

Example Payment Assessment Failed webhook request body

{
    "Error":"Insufficient funds or other failure",
    "UltimateDebtorName":"Richard Douglas",
    "UltimateDebtorAccount":"57d06e62-efca-49e7-a71f-8eb18d72c162",
    "UltimateDebtorAccountIdentifier":"AccountId",
    "UltimateDebtorAddressLine1":"4th Floor, Prologue Works",
    "UltimateDebtorAddressLine2":"25 Marsh St",
    "UltimateDebtorAddressLine3":"Bristol",
    "UltimateDebtorPostCode":"BS1 4AX",
    "UltimateDebtorCountryCode":"GB",
    "InstructedAmount":100.55,
    "InstructedCurrency":"EUR",
    "Reference":"My payment reference 12345",
    "BatchId":"ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId":"08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId":"4026da87bb0f4a5",
    "UltimateCreditorIBAN":"GB33BUKB20201555555555",
    "UltimateCreditorAccountNumber":null,
    "UltimateCreditorBic":"IIIGGB22",
    "UltimateCreditorName":"John Baker",
    "UltimateCreditorAddressLine1":"Martin Place",
    "UltimateCreditorAddressLine2":"London",
    "UltimateCreditorAddressLine3":null,
    "UltimateCreditorPostCode":"SW1A 1AA",
    "UltimateCreditorCountryCode":"GB",
    "TransactionId":"fd7f3082-72d4-46b3-8e0e-1f66e4a91e13"
},
    "Nonce":748224091
}

Example webhook response

{
    "Nonce": 748224091
}

This webhook confirms that an outbound multi-currency payment has failed validation.

Scenarios which can trigger this event include sending the payment from a debtor account that does not exist, has not yet been enabled to send payments, or has not yet been enabled to send payments in the intended currency.

Request body

{
    "Type":"Payments.Mccy.PaymentValidationFailed",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`Errors`	Required Error(s) which caused the payment validation to fail. Type: `array` Min. Length: `1` Max. Length: `140`
`UltimateDebtorName`	Optional Name of the ultimate debtor making the payment. Type: `string` Min. Length: `0` Max. Length: `143`
`UltimateDebtorAccount`	Required Account details of the ultimate debtor making the payment. Type: `string` Min. Length: `5` Max. Length: `36`
`UltimateDebtorAccountIdentifier`	Required Account identifier used to uniquely identify the ultimate debtor. Valid values are IBAN or AccountId. Type: `string` Min. Length: `1`
`UltimateDebtorAddressLine1`	Required First line of the ultimate debtor's address. Type: `string` Min. Length: `1` Max. Length: `70`
`UltimateDebtorAddressLine2`	Optional Second line of the ultimate debtor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateDebtorAddressLine3`	Optional Third line of the ultimate debtor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateDebtorPostCode`	Required Postcode of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `16`
`UltimateDebtorCountryCode`	Required Country code for the ultimate debtor's address. This is the 2-letter ISO country code. Type: `string` Min. Length: `2` Max. Length: `2` Pattern: `^[A-Z]{2}$`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-digit ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`UltimateCreditorIBAN`	Optional IBAN for the ultimate creditor. Mandatory only if Ultimate Creditor Account Number is not provided. Type: `string` Min. Length: `0` Max. Length: `34`
`UltimateCreditorAccountNumber`	Optional Account Number used to uniquely identify the ultimate creditor's account. Mandatory only if Ultimate Creditor IBAN is not provided. Type: `string` Min. Length: `0` Max. Length: `34`
`UltimateCreditorBic`	Optional BIC for the ultimate creditor. Type: `string` Min. Length: `8` Max. Length: `11` Pattern: `^[A-Z]{6}[A-Z2-9][A-NP-Z1-9]([A-Z0-9]{3})?$`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAddressLine1`	Required First line of the ultimate creditor's address. Type: `string` Min. Length: `1` Max. Length: `70`
`UltimateCreditorAddressLine2`	Optional Second line of the ultimate creditor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateCreditorAddressLine3`	Optional Third line of the ultimate creditor's address. Type: `string` Min. Length: `0` Max. Length: `35`
`UltimateCreditorPostCode`	Required Postcode of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `16`
`UltimateCreditorCountryCode`	Required Country code for the ultimate creditor's address. This is the 2-letter ISO country code. Type: `string` Min. Length: `2` Max. Length: `2` Pattern: `^[A-Z]{2}$`
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`

Example Payment Validation Failed webhook request body

{
    "Errors":[
        "Account is not enabled",
        "EndToEndId already exists.",
        "Account does not belong to this institution"
    ],
    "UltimateDebtorName":"Richard Douglas",
    "UltimateDebtorAccount":"57d06e62-efca-49e7-a71f-8eb18d72c162",
    "UltimateDebtorAccountIdentifier":"AccountId",
    "UltimateDebtorAddressLine1":"4th Floor, Prologue Works",
    "UltimateDebtorAddressLine2":"25 Marsh St",
    "UltimateDebtorAddressLine3":"Bristol",
    "UltimateDebtorPostCode":"BS1 4AX",
    "UltimateDebtorCountryCode":"GB",
    "InstructedAmount":100.55,
    "InstructedCurrency":"EUR",
    "Reference":"My payment reference 12345",
    "BatchId":"ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId":"08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId":"4026da87bb0f4a5",
    "UltimateCreditorIBAN":"GB33BUKB20201555555555",
    "UltimateCreditorAccountNumber":null,
    "UltimateCreditorBic":"IIIGGB22",
    "UltimateCreditorName":"John Baker",
    "UltimateCreditorAddressLine1":"Buckingham Palace",
    "UltimateCreditorAddressLine2":"London",
    "UltimateCreditorAddressLine3":null,
    "UltimateCreditorPostCode":"SW1A 1AA",
    "UltimateCreditorCountryCode":"GB",
    "TransactionId":"fd7f3082-72d4-46b3-8e0e-1f66e4a91e13"
},
    "Nonce":711364091
}

Example webhook response

{
    "Nonce": 711364091
}

Cancel batch payments

delete/v1/mccy/payments/{batchId}

This endpoint is used to cancel an entire batch of payments with a matching batch ID. It must be sent at least one hour prior to the opening of the currency payment window in order to successfully cancel the payment.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.
batchId string, path, Required
This must match the batch ID submitted in the payment request.

Response (application/json)

204 Success
400 Bad Request
404 Not Found
406 Not Acceptable
422 Client Error
500 Server Error
503 Server Error

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Acceptable

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Cancel a single payment

delete/v1/mccy/payments/{batchId}/{endToEndId}

This endpoint is used to cancel a single payment within a batch, with a matching batch ID and end-to-end ID. It must be sent at least one hour prior to the opening of the currency payment window in order to successfully cancel the payment.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.
batchId string, path, Required
This must match the batch ID submitted in the payment request.
endToEndId string, path, Required
This must match the end-to-end ID submitted in the payment request.

Response (application/json)

204 Success
400 Bad Request
404 Not Found
406 Not Acceptable
422 Client Error
500 Server Error
503 Server Error

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Found

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Not Acceptable

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Client Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

When you receive an inbound payment, you'll be notified with:

A Multi-currency Transaction Created webhook for all MCCY payments, including EUR via SCT.
A Multi-currency Transaction Settled webhook for all MCCY payments, including EUR via SCT.

This webhook confirms that a multi-currency transaction has been created.

Request body

{
    "Type":"Payments.Mccy.TransactionCreated",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Min. Length: `1` Format: `GUID`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate creditor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`UltimateDebtorName`	Required Name of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateDebtorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate debtor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`SchemePaymentMethod`	Required Payment scheme used for submitting the transaction. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time transaction was created. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Identifiers`	Required List of identifiers. It is an array of objects with a `Scope`, `Name` and `Identifier`. Type: `array` `Scope` Type: `string` Min. Length: `1` Max. Lenght: `50` `Name` Type: `string` Min. Length: `1` Max. Lenght: `50` `Identifier` Type: `string` Min. Length: `1` Max. Lenght: `250`
`AdditionalProperties`	Required List of additional information. It is an array of objects with a `Key` and `Value`. Type: `array` `Key` Type: `string` Min. Length: `1` Max. Lenght: `50` `Value` Type: `string` Min. Length: `1` Max. Lenght: `250`

Example transaction created webhook request body

{
    "TransactionId":"fd7f3082-72d4-46b3-8e0e-1f66e4a91e13",
    "BatchId":"ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId":"08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId":"4026da87bb0f4a5",
    "AccountId":"50daac8a-72c3-4ae5-a6e3-e71b6187dbef",
    "Reference":"My payment reference 12345",
    "UltimateCreditorName":"John Baker",
    "UltimateCreditorAccountIdentifiers":[
        {
            "Kind":"AccountId",
            "Identifier":"fd75710b-4c0a-406d-a962-ef5c98836d3f"
        }
    ],
    "UltimateDebtorName":"Clark Kent",
    "UltimateDebtorAccountIdentifiers":[
        {
            "Kind":"IBAN",
            "Identifier":"GB33BUKB20201555555555"
        }
    ],
    "InstructedAmount":100.55,
    "InstructedCurrency":"EUR",
    "SchemePaymentMethod":"Partner 1",
    "TimestampCreated":"2021-05-22T00:00:00",
    "Identifiers":[
        {
            "Scope":"MCCYOutboundPayments",
            "Name":"SchemeEndToEndId",
            "Identifier":"4026da87bb0f4a5"
        }
    ],
    "AdditionalProperties":[
        {
            "Key":"DebtorName",
            "Value":"Acme Studios"
        },
        {
            "Key":"DebtorCountry",
            "Value":"GB"
        }
    ]
},
    "Nonce":748352091
}

Example webhook response

{
    "Nonce": 748352091
}

This webhook confirms that an inbound or outbound multi-currency transaction has settled.

Request body

{
    "Type":"Payments.Mccy.TransactionSettled",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`TransactionId`	Required Unique internal identifier defined by ClearBank for each payment. Type: `string` Min. Length: `1` Format: `GUID`
`BatchId`	Required Unique identifier for the batch in which the payment was submitted. Type: `string` Min. Length: `1` Format: `GUID`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`SchemeEndToEndId`	Optional Unique identifier created by ClearBank for each payment and passed through the scheme to the creditor. Type: `string` Min. Length: `0` Max. Length: `15`
`AccountId`	Required Unique identifier for the account held with ClearBank. Type: `string` Min. Length: `1` Format: `GUID`
`Reference`	Required Reference provided by the ultimate debtor for the payment. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorName`	Required Name of the ultimate creditor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateCreditorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate creditor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`UltimateDebtorName`	Required Name of the ultimate debtor. Type: `string` Min. Length: `1` Max. Length: `143`
`UltimateDebtorAccountIdentifiers`	Required List of account identifiers used to uniquely identify the ultimate debtor. It is an array of objects with `Kind` and an `Identifier`. Type: `array` `Kind` The kind of account identifier which is provided. This can be either IBAN, BBAN, AccountId or Descriptor (another kind of identifier). Type: `string` Min. Length: `1` Max. Length: `10` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed payment amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed payment. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`SchemePaymentMethod`	Required Payment scheme used for submitting the transaction. Type: `string` Min. Length: `1` Max. Length: `50`
`TimestampCreated`	Required Date and time transaction was created. Time in UTC. Type: `string` Min. Length: `1` Format: `date-time`
`Identifiers`	Required List of identifiers. It is an array of objects with a `Scope`, `Name` and `Identifier`. Type: `array` `Scope` Type: `string` Min. Length: `1` Max. Lenght: `50` `Name` Type: `string` Min. Length: `1` Max. Lenght: `50` `Identifier` Type: `string` Min. Length: `1` Max. Lenght: `250`
`AdditionalProperties`	Required List of additional information. It is an array of objects with a `Key` and `Value`. Type: `array` `Key` Type: `string` Min. Length: `1` Max. Lenght: `50` `Value` Type: `string` Min. Length: `1` Max. Lenght: `250`
`TimestampSettled`	Required Date and time the transaction settled. Type: `string` Min. Length: `1` Format: `date-time`
`TimestampSubmitted`	Required Date and time transaction was submitted. This should be the same as the date and time of TimestampSettled but will reflect a different time if the transaction settlement is delayed. This time will represent the time the transaction should have settled had it not been delayed. Type: `string` Min. Length: `1` Format: `date-time`

Example transaction settled webhook request body

{
    "TransactionId": "fd7f3082-72d4-46b3-8e0e-1f66e4a91e13",
    "BatchId": "ab55f54a-26c3-4333-93cd-f917bb51ecad",
    "EndToEndId": "08c2c49c9e094df59f342a27cb64395c",
    "SchemeEndToEndId": "4026da87bb0f4a5",
    "AccountId": "50daac8a-72c3-4ae5-a6e3-e71b6187dbef",
    "Reference": "My payment reference 12345",
    "UltimateCreditorName": "John Baker",
    "UltimateCreditorAccountIdentifiers": [
        {
            "Kind": "AccountId",
            "Identifier": "fd75710b-4c0a-406d-a962-ef5c98836d3f"
        }
    ],
    "UltimateDebtorName": "Clark Kent",
    "UltimateDebtorAccountIdentifiers": [
        {
            "Kind": "IBAN",
            "Identifier": "GB33BUKB20201555555555"
        }
    ],
    "InstructedAmount": 100.55,
    "InstructedCurrency": "EUR",
    "SchemePaymentMethod": "Partner 1",
    "TimestampCreated": "2021-05-22T00:00:00",
    "Identifiers": [
        {
            "Scope": "MCCYOutboundPayments",
            "Name": "SchemeEndToEndId",
            "Identifier": "4026da87bb0f4a5"
        }
    ],
    "AdditionalProperties": [
        {
            "Key": "DebtorName",
            "Value": "Acme Studios"
        },
        {
            "Key": "DebtorCountry",
            "Value": "GB"
        }
    ],
    "TimestampSettled": "2020-09-13T012:22:17.4",
    "TimestampSubmitted": "2020-09-13T011:26:15.1"
},
    "Nonce":761164091
}

Example webhook response

{
    "Nonce": 761164091
}

You can initiate payments between two ClearBank multi-currency accounts that you operate. This process is known as an internal transfer request. For an internal transfer request to be processed successfully, it is imperative that both accounts are enabled for the instructed currency.

Request an internal transfer

post/v1/mccy/internaltransfers

This endpoint is used to initiate an internal transfer request.

Parameters

Authorization string, header, Required
Your API token, obtained from the ClearBank Portal.
DigitalSignature string, header, Required
Signed hash of the body of the request. The hash is signed by your private key.
X-Request-Id string, header, Required
A unique identifier for the request; valid for 24 hours, max length 83.

Request Payload (application/json)

debitAccountIban string
International Bank Account Number for the debtor account.
debitAccountOther object
The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided.
creditAccountIban string
International Bank Account Number for the creditor account.
creditAccountOther object
The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided.
instructedAmount number, Required
Instructed internal transfer amount.
Minimum
0.01
Maximum
999999999.99
instructedCurrency string, Required
Currency of the instructed internal transfer. This is the 3-letter ISO currency code.
Minimum length
3
Maximum length
3
Enum array
EUR, USD, CAD, CHF, CZK, DKK, HUF, NOK, PLN, RON, SEK
endToEndId string, Required
Unique identifier provided to ClearBank for each payment.
Minimum length
1
Maximum length
35
Pattern
[A-Za-z0-9/\-?:.,"+ ]
reference string
Reference provided by the debtor for the internal transfer.
Minimum length
0
Maximum length
140
Pattern
^[a-zA-Z0-9/\?:\-., ]+

request

{
  "debitAccountIban": "GB29BBUK21081873903941",
  "debitAccountOther": {
    "kind": "AccountId",
    "identifier": "4c4fcf12-6f9f-5fe5-bac5-a75cb1d6382d"
  },
  "creditAccountIban": "GB22CBUK53857446495102",
  "creditAccountOther": {
    "kind": "AccountId",
    "identifier": "4c4fcf12-6f9f-5fe5-bac5-a75cb1d6382d"
  },
  "instructedAmount": 1234.56,
  "instructedCurrency": "EUR",
  "endToEndId": "c2051e84-0c68-51f1-94db-4605ddb62ddd",
  "reference": "Human readable example text"
}

Code copied

Response (application/json)

202 Success
400 Bad Request
409 Conflict
500 Server Error

Bad Request

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Conflict

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Server Error

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Code copied

Associated Webhooks

Multi-currency Internal Transfers Settled webhook
Multi-currency Internal Transfers Cancelled webhook

This webhook confirms that a multi-currency internal transfer request has been settled.

Request body

{
    "Type":"Mccy.InternalTransfers.Settled",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`DebitAccountIban`	Optional International Bank Account Number for the debtor account. Type: `string`
`DebitAccountOther`	Optional The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided. Type: `object` `Kind` The kind of account identifier provided. This can only be AccountId. Type: `string` Min. Length: `1` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`CreditAccountIban`	Optional International Bank Account Number for the creditor account. Type: `string`
`CreditAccountOther`	Optional The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided. Type: `object` `Kind` The kind of account identifier provided. This can only be AccountId. Type: `string` Min. Length: `1` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed internal transfer amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed internal transfer. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`Reference`	Optional Reference provided by the debtor for the internal transfer. Type: `string` Min. Length: `0` Max. Length: `140`

Example internal transfer settled webhook request body

{
    "EndToEndId":"56de3483a56942eb90ccacf59661356f",
    "DebitAccountIban":"GB00CUBK11223312345678",
    "CreditAccountIban":"GB00CUBK88776687654321",
    "InstructedCurrency":"NOK",
    "InstructedAmount":13,
    "Reference":"f92af28f-0635-4d81-893f-6c32af1d2a17"
},
    "Nonce":748394375
}

Example webhook response

{
    "Nonce": 748394375
}

This webhook confirms that a multi-currency internal transfer request has been cancelled.

Request body

{
    "Type":"Mccy.InternalTransfers.Cancelled",
    "Version": 1,
    "Payload": {...},
    "Nonce":
}

Payload

Element	Description
`DebitAccountIban`	Optional International Bank Account Number for the debtor account. Type: `string`
`DebitAccountOther`	Optional The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided. Type: `object` `Kind` The kind of account identifier provided. This can only be AccountId. Type: `string` Min. Length: `1` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`CreditAccountIban`	Optional International Bank Account Number for the creditor account. Type: `string`
`CreditAccountOther`	Optional The unique identifier for the specified account if an IBAN is not provided. It is an object with a Kind and an Identifier. Mandatory only if the IBAN is not provided. Type: `object` `Kind` The kind of account identifier provided. This can only be AccountId. Type: `string` Min. Length: `1` `Identifier` Unique account identifier value that corresponds to the specified account identifier kind. Type: `string` Min. Length: `1` Max. Length: `36`
`InstructedAmount`	Required Instructed internal transfer amount. Type: `number` Format: `decimal`
`InstructedCurrency`	Required Currency of the instructed internal transfer. This is the 3-letter ISO currency code. Type: `string` Min. Length: `3` Max. Length: `3` Pattern: `^[A-z]{3}$`
`EndToEndId`	Required Unique identifier provided to ClearBank for each payment. Type: `string` Min. Length: `1` Max. Length: `35`
`Reference`	Optional Reference provided by the debtor for the internal transfer. Type: `string` Min. Length: `0` Max. Length: `140`
`CancellationCode`	Required The cancellation code for the internal transfer. Valid options include: ValidationFailed, AssessmentFailed. Type: `string`
`FailureReasons`	Required Reasons the internal transfer was cancelled. Type: `array` Min. Items: `1`

Example internal transfer cancelled webhook request body

{
    "CancellationCode":"AssessmentFailed",
    "FailureReasons":[
        "Not enough funds"
    ],
    "EndToEndId":"9020d28f67f042aca26ae4f031765af5",
    "DebitAccountIban":"GB00CUBK11223312345678",
    "CreditAccountIban":"GB00CUBK88776687654321",
    "InstructedCurrency":"EUR",
    "InstructedAmount":53,
    "Reference":"226ef602-43e1-48a3-9fbd-f6a80849d74f"
},
    "Nonce":748394376
}

Example webhook response

{
    "Nonce": 748394376
}

Multi-currency payments

High value international payments

Payment cut-off times and scheduling

Fund your account in the simulation environment

Parameters

Request Payload (application/json)

Response (application/json)

Initiate a payment

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks

Cancel batch payments

Parameters

Response (application/json)

Cancel a single payment

Parameters

Response (application/json)

Inbound payments

Internal transfer (MCCY)

Request an internal transfer

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks