You can send single or bulk high value payments overseas in currencies other than GBP. To be able to initiate high value international payments, we will need you to first fund your SIM account while integrating with our API in the simulation environment. As part of our fund assessment control framework, you will not be able to initiate high value international payments without doing so.

ClearBank accepts inbound and outbound Euro payments via the T2 scheme only. Inbound payments which are processed via any other scheme apart from T2 will not be accepted by ClearBank. Non-EUR high value international payments are settled according to cut-off times specific to the currency in which the payment is made.

For more information about the countries that you can send high value payments to, currencies supported by ClearBank and currency cut-off times, please speak to your Relationship Manager.

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.

If 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	Scheduled processing time
Czech Koruna	CZK	8:20 AM
Romanian Leu	RON	8:20 AM
All other supported currencies		8: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

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.
instructedAmount number, Required
Instructed payment amount.
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": 1000,
  "reference": "12345678",
  "endToEndId": "87654321",
  "ultimateCreditor": {
    "iban": "GB14BARC20031838591122",
    "name": "Rob Robinson",
    "address": "1 High St Northleach Gloucestershire"
  },
  "ultimateDebtor": {
    "identifier": "IR14BARC20031838591122",
    "name": "Joe Bloggs",
    "address": "2 Main St London"
  }
}

Code copied

Response (application/json)

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

Successful operation.

{
  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc",
  "instructedCurrency": "string",
  "instructedAmount": 0,
  "reference": "string",
  "endToEndId": "string",
  "ultimateCreditorIBAN": "string",
  "ultimateCreditorName": "string",
  "ultimateDebtorIdentifier": "string",
  "ultimateDebtorName": "string",
  "timestampCreated": "2019-08-24T14:15:22Z",
  "bankRefSearchable": "string"
}

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

Request Payload (application/json)

batchId string
Unique identifier for the batch in which the payment is being submitted. (GUID format 128-bit label)
currencyCode string, Required
Three-letter ISO currency code for the outbound payment.
Minimum length
3
Maximum length
3
transactions array, Required
Array of transactions. The maximum batch size is 100.

request

{
  "batchId": "5579c111-9c50-47e2-af92-f16d52e63189",
  "currencyCode": "EUR",
  "transactions": [
    {
      "endToEndId": "string",
      "reference": "string",
      "amount": 0,
      "creditor": {
        "name": "string",
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "addressLine3": "string",
          "postCode": "string",
          "country": "st"
        },
        "bic": "string",
        "identification": {
          "organisationIdentification": {
            "Other": {
              "identification": "string",
              "schemeName": {
                "code": "stri",
                "proprietary": "string"
              },
              "issuer": "string"
            }
          },
          "privateIdentification": {
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "2019-08-24",
              "cityOfBirth": "string",
              "countryOfBirth": "st"
            },
            "other": {
              "identification": "string",
              "schemeName": {
                "code": "stri",
                "proprietary": "string"
              }
            }
          }
        },
        "countryOfResidence": "st",
        "contactDetails": {
          "name": "string",
          "emailAddress": "string"
        },
        "iban": "string",
        "accountNumber": "string",
        "schemeName": {
          "code": "stri",
          "proprietary": "string"
        }
      },
      "debtorName": "string",
      "debtorAddress": {
        "addressLine1": "string",
        "addressLine2": "string",
        "addressLine3": "string",
        "postCode": "string",
        "country": "st"
      },
      "debtorBic": "string",
      "debtorPrivateIdentification": {
        "dateAndPlaceOfBirth": {
          "dateOfBirth": "2019-08-24",
          "cityOfBirth": "string",
          "countryOfBirth": "st"
        },
        "other": {
          "identification": "string",
          "schemeName": {
            "code": "stri",
            "proprietary": "string"
          }
        }
      },
      "accountIdentifier": {
        "kind": "AccountId",
        "identifier": "string"
      },
      "debtorAccountCurrency": "str",
      "intermediaryAgent": {
        "FinancialInstitutionIdentification": {
          "bic": "string",
          "aba": "string",
          "name": "string",
          "addressDetails": {
            "addressLine1": "string",
            "addressLine2": "string",
            "addressLine3": "string",
            "postCode": "string",
            "country": "st"
          }
        }
      },
      "creditorAgent": {
        "FinancialInstitutionIdentification": {
          "bic": "string",
          "aba": "string",
          "clearingSystemIdCode": "string",
          "memberId": "string",
          "name": "string",
          "addressDetails": {
            "addressLine1": "string",
            "addressLine2": "string",
            "addressLine3": "string",
            "postCode": "string",
            "country": "st"
          }
        },
        "branchId": "string"
      },
      "instructionForDebtorAgent": "string",
      "purpose": {
        "code": "stri",
        "proprietary": "string"
      },
      "remittanceInformation": {
        "additionalRemittanceInformation": "string"
      },
      "ultimateCreditor": {
        "name": "string",
        "address": {
          "addressLine1": "string",
          "addressLine2": "string",
          "addressLine3": "string",
          "postCode": "string",
          "country": "st"
        },
        "bic": "string",
        "identification": {
          "organisationIdentification": {
            "Other": {
              "identification": "string",
              "schemeName": {
                "code": "stri",
                "proprietary": "string"
              },
              "issuer": "string"
            }
          },
          "privateIdentification": {
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "2019-08-24",
              "cityOfBirth": "string",
              "countryOfBirth": "st"
            },
            "other": {
              "identification": "string",
              "schemeName": {
                "code": "stri",
                "proprietary": "string"
              }
            }
          }
        }
      }
    }
  ]
}

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 a multi-currency transaction has been 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 a 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 a 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 a 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

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

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

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

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.
instructedCurrency string, Required
Currency of the instructed internal transfer. This is the 3-letter ISO currency code.
Minimum length
3
Maximum length
3
Pattern
^[A-z]{3}$
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": "string",
  "debitAccountOther": {
    "kind": "string",
    "identifier": "string"
  },
  "creditAccountIban": "string",
  "creditAccountOther": {
    "kind": "string",
    "identifier": "string"
  },
  "instructedAmount": 0,
  "instructedCurrency": "str",
  "endToEndId": "string",
  "reference": "string"
}

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

Post cut-off payments are rescheduled

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)

Internal transfer (MCCY)

Request an internal transfer

Parameters

Request Payload (application/json)

Response (application/json)

Associated Webhooks