{ "openapi": "3.0.1", "info": { "title": "Mccy Payment Orchestrator External Api V1", "description": "Mccy Payment Orchestrator External Api V1", "version": "1.0.Dec21" }, "paths": { "/v1/mccy/payments": { "post": { "tags": [ "Payments" ], "summary": "This endpoint is used to initiate payments.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Your API token, obtained from the ClearBank Portal.", "required": true, "schema": { "type": "string" } }, { "name": "DigitalSignature", "in": "header", "description": "Signed hash of the body of the request. The hash is signed by your private key.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "A unique identifier for the request; valid for 24 hours, max length 83.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/PaymentResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "Conflict", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Unprocessable Entity", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server Error" }, "503": { "description": "Server Error" } } } }, "/v1/mccy/payments/{batchId}": { "delete": { "tags": [ "Payments" ], "summary": "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": [ { "name": "Authorization", "in": "header", "description": "Your API token, obtained from the ClearBank Portal.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "A unique identifier for the request; valid for 24 hours, max length 83.", "required": true, "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "required": true, "description": "This must match the batch ID submitted in the payment request.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Client Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server Error" }, "503": { "description": "Server Error" } } } }, "/v1/mccy/payments/{batchId}/{endToEndId}": { "delete": { "tags": [ "Payments" ], "summary": "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": [ { "name": "Authorization", "in": "header", "description": "Your API token, obtained from the ClearBank Portal.", "required": true, "schema": { "type": "string" } }, { "name": "X-Request-Id", "in": "header", "description": "A unique identifier for the request; valid for 24 hours, max length 83.", "required": true, "schema": { "type": "string" } }, { "name": "batchId", "in": "path", "required": true, "description": "This must match the batch ID submitted in the payment request.", "schema": { "type": "string" } }, { "name": "endToEndId", "in": "path", "required": true, "description": "This must match the end-to-end ID submitted in the payment request.", "schema": { "type": "string", "pattern": "[A-Za-z0-9/\\-?:.,\"+ ]" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Not Acceptable", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Client Error", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "Server Error" }, "503": { "description": "Server Error" } } } } }, "components": { "schemas": { "Creditor": { "required": [ "name", "address" ], "type": "object", "description": "Information about the creditor of the transaction.", "properties": { "name": { "type": "string", "description": "Creditor's name.", "minLength": 1, "maxLength": 140, "example": "Newell Saunders" }, "address": { "type": "object", "description": "Information about the creditor's address.", "required": [ "addressLine1", "addressLine2", "postCode", "country" ], "properties": { "addressLine1": { "type": "string", "minLength": 1, "maxLength": 70, "description": "First line of the creditor's address.", "example": "123A" }, "addressLine2": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Second line of the creditor's address.", "example": "Wren Way" }, "addressLine3": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Third line of the creditor's address.", "nullable": true, "example": "Hamlinton" }, "postCode": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Creditor's postcode.", "example": "NN87 2335" }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter ISO country code for the creditor's address.", "pattern": "^[A-Z]{2}$", "example": "PT" } } }, "bic": { "type": "string", "description": "Creditor's Business Identifier Code (BIC).", "minLength": 8, "maxLength": 11, "pattern": "[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}", "nullable": true, "example": "1A2BPT12AB3" }, "identification": { "type": "object", "description": "Creditor's business and personal information.", "properties": { "organisationIdentification": { "type": "object", "description": "Information about the creditor's organisation.", "properties": { "Other": { "type": "object", "description": "Information about the creditor's non-SWIFT BIC organisation identification.", "properties": { "identification": { "type": "string", "description": "Creditor's non-SWIFT BIC organisation identification, as assigned by an identification scheme.", "minLength": 0, "maxLength": 35, "nullable": true }, "schemeName": { "type": "object", "description": "Information about the organisation identification scheme in coded form or free-form text.", "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form, as specified in the ExternalOrganisationIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "BDID" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Other identification scheme name" } } }, "issuer": { "type": "string", "description": "Entity/authority/body responsible for issuing the identification.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Identification authority name" } } } } }, "privateIdentification": { "type": "object", "description": "The creditor's private or personal information.", "properties": { "dateAndPlaceOfBirth": { "type": "object", "description": "Creditor's birth information.", "properties": { "dateOfBirth": { "type": "string", "description": "Creditor's date of birth.", "format": "date", "nullable": true, "example": "1995-12-27" }, "cityOfBirth": { "type": "string", "description": "Creditor's city of birth.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Lisbon" }, "countryOfBirth": { "type": "string", "description": "Two-letter ISO country code for the creditor's country of birth.", "minLength": 0, "maxLength": 2, "pattern": "^[A-Z]{2}$", "nullable": true, "example": "PT" } } }, "other": { "type": "object", "description": "Information about the creditor's private identification.", "properties": { "identification": { "type": "string", "description": "Creditor's personal identification, as assigned by an identification scheme. For example, their passport number.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "020696623" }, "schemeName": { "type": "object", "description": "Information about the identification scheme in coded form, or free-form text.", "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form, as specified in the ExternalPersonIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "CCPT" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Other identification scheme name" } } } } } } } } }, "countryOfResidence": { "type": "string", "description": "Two-letter ISO country code for the creditor's country of residence.", "minLength": 0, "maxLength": 2, "pattern": "^[A-Z]{2}$", "nullable": true, "example": "PT" }, "contactDetails": { "type": "object", "description": "Creditor's contact details.", "properties": { "name": { "type": "string", "description": "Creditor's contact name.", "minLength": 0, "maxLength": 140, "nullable": true, "example": "Ryan Christensen" }, "emailAddress": { "type": "string", "description": "Creditor's email address.", "minLength": 0, "maxLength": 2048, "nullable": true, "example": "tokchri@business.eu" } } }, "iban": { "type": "string", "description": "Creditor's International Bank Account Number. Mandatory only if account number is not specified.", "nullable": true, "example": "ES9242020418450222051122" }, "accountNumber": { "type": "string", "description": "Creditor's Account Number. Mandatory only if iban is not specified.", "nullable": true, "minLength": 0, "maxLength": 34, "example": "0222051122" }, "schemeName": { "type": "object", "description": "Information about the identification scheme in coded form or free-form text. This should only be provided if the creditor's account number has been specified", "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form. No need to specify if you are providing this name in free-form text (i.e., proprietary). Valid options include: CASH, CHAR, COMM, TAXE, CISH, TRAS, SACC, CACC, SVGS, ONDP, MGLD, NREX, MOMA, LOAN, SLRY, ODFT.", "minLength": 0, "maxLength": 4, "nullable": true, "example": "TRAS" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Example other identification scheme" } } } }, "additionalProperties": false }, "AccountIdentifierKind": { "enum": [ "AccountId", "IBAN" ], "type": "string", "description": "The kind of account identifier provided. This can either be IBAN or AccountId. This field is case insensitive." }, "AccountIdentifier": { "required": [ "kind", "identifier" ], "type": "object", "description": "The unique identifier for the account.", "properties": { "kind": { "$ref": "#/components/schemas/AccountIdentifierKind" }, "identifier": { "type": "string", "description": "Unique account identifier value that corresponds to the specified account identifier kind.", "minLength": 1, "maxLength": 36, "example": "GB22CBUK60109839856819" } }, "additionalProperties": false }, "IntermediaryAgent": { "type": "object", "description": "Information about the intermediary/correspondent bank.", "properties": { "FinancialInstitutionIdentification": { "type": "object", "description": "Information that identifies the intermediary agent as a financial institution. Mandatory only when intermediary agent details are being provided.", "required": [ "addressDetails" ], "properties": { "bic": { "type": "string", "description": "Intermediary agent's Business Identifier Code (BIC). No need to specify if you are providing the intermediary agent's American Bankers Association (ABA) routing number.", "minLength": 8, "maxLength": 11, "pattern": "[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}", "nullable": true, "example": "NWBKGB2LXXX" }, "aba": { "type": "string", "description": "Intermediary agent's American Bankers Association (ABA) routing number. No need to specify if you are providing the intermediary agent's Business Identifier Code (BIC).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "376582168" }, "name": { "type": "string", "description": "Intermediary agent's name.", "minLength": 0, "maxLength": 140, "nullable": true, "example": "Intermediary Agent Financial Institution" }, "addressDetails": { "type": "object", "description": "Information about the intermediary agent's address. Mandatory only when financial institution identification details are being provided.", "nullable": true, "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "minLength": 0, "maxLength": 70, "description": "First line of the intermediary agent's address.", "nullable": true, "example": "12 Banking Building" }, "addressLine2": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Second line of the intermediary agent's address.", "nullable": true, "example": "Bank Street" }, "addressLine3": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Third line of the intermediary agent's address.", "nullable": true, "example": "Belfast" }, "postCode": { "type": "string", "minLength": 0, "maxLength": 16, "description": "Intermediary agent's postcode.", "nullable": true, "example": "BT1 5GS" }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter ISO country code for the intermediary agent's address. Mandatory only when the intermediary agent's details are being provided.", "pattern": "^[A-Z]{2}$", "example": "GB" } } } }, "additionalProperties": false } }, "additionalProperties": false }, "CreditorAgent": { "type": "object", "required": [ "FinancialInstitutionIdentification" ], "properties": { "FinancialInstitutionIdentification": { "type": "object", "description": "Information that identifies the creditor agent as a financial institution.", "required": [ "name", "addressDetails" ], "properties": { "bic": { "type": "string", "description": "Creditor agent's Business Identifier Code (BIC). No need to specify if you are providing the creditor agent's American Bankers Association (ABA) routing number or Clearing System Id Code.", "minLength": 8, "maxLength": 11, "pattern": "[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}", "nullable": true, "example": "CBUKGBA132S" }, "aba": { "type": "string", "description": "Creditor agent's American Bankers Association (ABA) routing number. No need to specify if you are providing the creditor agent's Business Identifier Code (BIC) or Clearing System Id Code.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "853688941" }, "clearingSystemIdCode": { "description": "Creditor agent's Clearing System Id Code. No need to specify if you are providing the creditor agent's Business Identifier Code (BIC) or American Bankers Association (ABA) routing number.", "type": "string", "minLength": 0, "maxLength": 35, "nullable": true, "example": "GBDSC" }, "memberId": { "description": "Creditor agent's Member Id for the specified clearing system. Mandatory only when Clearing System Id Code has been provided.", "type": "string", "nullable": true, "minLength": 0, "maxLength": 35, "example": "30-12-77" }, "name": { "type": "string", "description": "Creditor agent's name.", "minLength": 1, "maxLength": 140, "example": "Big FI Corp" }, "addressDetails": { "type": "object", "description": "Information about the creditor agent's address.", "nullable": true, "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "minLength": 0, "maxLength": 70, "description": "First line of the creditor agent's address.", "nullable": true, "example": "11 The Square" }, "addressLine2": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Second line of the creditor agent's address.", "nullable": true, "example": "Circle District" }, "addressLine3": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Third line of the creditor agent's address.", "nullable": true, "example": "Sphere City" }, "postCode": { "type": "string", "minLength": 0, "maxLength": 16, "description": "Creditor agent's postcode.", "nullable": true, "example": "SP1 8NY" }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter ISO country code for the creditor agent's address. Mandatory only when the creditor agent's details are being provided.", "pattern": "^[A-Z]{2}$", "example": "GB" } } } }, "additionalProperties": false }, "branchId": { "type": "string", "description": "Creditor agent's unique branch Id.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Big FI Outbound Salisbury" } }, "additionalProperties": false }, "Purpose": { "type": "object", "nullable": true, "description": "Information about the purpose of the transaction.", "properties": { "code": { "type": "string", "description": "Purpose of the transaction in coded form, as specified in the Purpose1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "SUPP" }, "proprietary": { "type": "string", "description": "Purpose of the transaction in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Other non-codified purpose" } }, "additionalProperties": false }, "RemittanceInformation": { "type": "object", "description": "Remittance information to accompany the payment.", "nullable": true, "properties": { "additionalRemittanceInformation": { "type": "string", "description": "Additional remittance information in free-form text, to compliment the structured remittance information.", "minLength": 0, "maxLength": 140, "nullable": true, "example": "Example unstructured information" } }, "additionalProperties": false }, "UltimateCreditor": { "type": "object", "description": "Information about the ultimate creditor of the transaction. To be used where there is a “for further credit to” scenario.", "nullable": true, "required": [ "name", "address" ], "properties": { "name": { "type": "string", "description": "Ultimate creditor's name.", "minLength": 1, "maxLength": 140, "example": "Amanda Myers" }, "address": { "type": "object", "description": "Information about the ultimate creditor's address. Mandatory only when information about the ultimate creditor is being provided.", "nullable": true, "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "minLength": 0, "maxLength": 70, "description": "First line of the ultimate creditor's address.", "nullable": true, "example": "21 Cyan" }, "addressLine2": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Second line of the ultimate creditor's address.", "nullable": true, "example": "Fontainebleau" }, "addressLine3": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Third line of the ultimate creditor's address.", "nullable": true, "example": "Île-de-France" }, "postCode": { "type": "string", "minLength": 0, "maxLength": 16, "description": "Ultimate creditor's postcode.", "nullable": true, "example": "77300" }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter ISO country code for the ultimate creditor's address. Mandatory only when the ultimate creditor's details are being provided.", "pattern": "^[A-Z]{2}$", "example": "FR" } } }, "bic": { "type": "string", "description": "Ultimate creditor's Business Identifier Code (BIC).", "minLength": 8, "maxLength": 11, "pattern": "[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}", "nullable": true, "example": "ABBAFRA112A" }, "identification": { "type": "object", "description": "The ultimate creditor's business and personal information.", "nullable": true, "properties": { "organisationIdentification": { "type": "object", "description": "Information about the ultimate creditor's organisation.", "properties": { "Other": { "type": "object", "description": "Information about the ultimate creditor's non-SWIFT BIC organisation. identification.", "properties": { "identification": { "type": "string", "description": "The ultimate creditor's non-SWIFT BIC organisation identification, as assigned by an identification scheme. Customarily the account number/IBAN of the Ultimate Creditor held with the Creditor.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "BE29539003417022" }, "schemeName": { "type": "object", "description": "Name of the identification scheme in coded form or free-form text.", "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form, as specified in the ExternalOrganisationIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "CUST" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Example other identification scheme" } } }, "issuer": { "type": "string", "description": "Entity/authority/body responsible for issuing the identification.", "minLength": 0, "maxLength": 35, "nullable": true } } } } }, "privateIdentification": { "type": "object", "description": "The ultimate creditor's private or personal information.", "nullable": true, "properties": { "dateAndPlaceOfBirth": { "type": "object", "description": "The ultimate creditor's birth information.", "nullable": true, "properties": { "dateOfBirth": { "type": "string", "description": "The ultimate creditor's date of birth.", "format": "date", "nullable": true, "example": "1975-11-22" }, "cityOfBirth": { "type": "string", "description": "The ultimate creditor's city of birth.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Copenhagen" }, "countryOfBirth": { "type": "string", "description": "Two-letter ISO country code for the ultimate creditor's country of birth.", "minLength": 0, "maxLength": 2, "pattern": "^[A-Z]{2}$", "nullable": true, "example": "DK" } } }, "other": { "type": "object", "description": "Information about the ultimate creditor's private identification.", "nullable": true, "properties": { "identification": { "type": "string", "description": "The ultimate creditor's personal identification, as assigned by an identification scheme.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "139748154" }, "schemeName": { "type": "object", "description": "Information about the identification scheme in coded form or free-form text.", "nullable": true, "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form, as specified in the ExternalPersonIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "CCPT" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Example other identification scheme" } } } } } } } } } }, "additionalProperties": false }, "PaymentRequestItem": { "required": [ "endToEndId", "reference", "accountIdentifier", "amount", "debtorAddress", "creditor", "debtorAccountCurrency", "debtorName" ], "type": "object", "properties": { "endToEndId": { "type": "string", "description": "Unique identifier provided to ClearBank for each payment.", "minLength": 1, "maxLength": 35, "pattern": "[A-Za-z0-9/\\-?:.,\"+ ]", "example": "pd0G4d9XCLOzpM5lBA86YNXU8KU3I0etZ5T" }, "reference": { "type": "string", "description": "Reference provided by the debtor for the payment.", "minLength": 1, "maxLength": 140, "example": "Human readable example text" }, "amount": { "type": "number", "description": "Instructed payment amount in the batch's specified currency.", "minimum": 0.01, "maximum": 999999999.99, "multipleOf": 0.01, "example": 1234.56 }, "creditor": { "$ref": "#/components/schemas/Creditor" }, "debtorName": { "type": "string", "description": "The name used to identify the legal owner of the account from which the funds will be debited.", "minLength": 1, "maxLength": 140, "example": "Bradley Kennedy" }, "debtorAddress": { "type": "object", "description": "Information about the debtor's address.", "required": [ "addressLine1", "addressLine2", "postCode", "country" ], "properties": { "addressLine1": { "type": "string", "minLength": 1, "maxLength": 70, "description": "First line of the debtor's address.", "example": "Green House" }, "addressLine2": { "type": "string", "minLength": 1, "maxLength": 35, "description": "Second line of the debtor's address.", "example": "Purple Lane" }, "addressLine3": { "type": "string", "minLength": 0, "maxLength": 35, "description": "Third line of the debtor's address.", "nullable": true, "example": "Orange District" }, "postCode": { "type": "string", "minLength": 1, "maxLength": 16, "description": "Debtor's postcode.", "example": "CB2 5AB" }, "country": { "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter ISO country code for the debtor's address.", "pattern": "^[A-Z]{2}$", "example": "GB" } } }, "debtorBic": { "type": "string", "description": "Debtor's Business Identifier Code (BIC).", "minLength": 8, "maxLength": 11, "pattern": "[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}", "nullable": true, "example": "ABCDNLAA123" }, "debtorPrivateIdentification": { "type": "object", "description": "The debtor's private or personal information.", "properties": { "dateAndPlaceOfBirth": { "type": "object", "description": "Debtor's birth information.", "properties": { "dateOfBirth": { "type": "string", "description": "Debtor's date of birth.", "format": "date", "nullable": true, "example": "1962-02-21" }, "cityOfBirth": { "type": "string", "description": "Debtor's city of birth.", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Paris" }, "countryOfBirth": { "type": "string", "description": "Two-letter ISO country code for the debtor's country of birth.", "minLength": 0, "maxLength": 2, "pattern": "^[A-Z]{2}$", "nullable": true, "example": "France" } } }, "other": { "type": "object", "description": "Information about the debtor's private identification.", "properties": { "identification": { "type": "string", "description": "Debtor's personal identification, as assigned by an identification scheme.", "minLength": 0, "maxLength": 35, "nullable": true }, "schemeName": { "type": "object", "description": "Information about the identification scheme in coded form or free-form text.", "properties": { "code": { "type": "string", "description": "Name of the identification scheme in coded form, as specified in the ExternalPersonIdentification1Code code set required by ISO 20022 Message Schemas. No need to specify if you are providing this name in free-form text (i.e., proprietary).", "minLength": 0, "maxLength": 4, "nullable": true, "example": "CCPT" }, "proprietary": { "type": "string", "description": "Name of the identification scheme in free-form text. No need to specify if you are providing this name in coded form (i.e., code).", "minLength": 0, "maxLength": 35, "nullable": true, "example": "Other identification scheme name" } } } } } } }, "accountIdentifier": { "$ref": "#/components/schemas/AccountIdentifier" }, "debtorAccountCurrency": { "type": "string", "description": "Three-letter ISO currency code for the currency supported by the debtor account. This field is case insensitive.", "minLength": 3, "maxLength": 3, "enum": ["EUR", "USD", "CAD", "CHF", "CZK", "DKK", "HUF", "NOK", "PLN", "RON", "SEK"], "example": "EUR" }, "intermediaryAgent": { "$ref": "#/components/schemas/IntermediaryAgent" }, "creditorAgent": { "$ref": "#/components/schemas/CreditorAgent" }, "instructionForDebtorAgent": { "type": "string", "nullable": true, "description": "Further information related to the processing of the payment instruction that may need to be acted upon by the debtor agent (depending on an agreement between the debtor and debtor agent). Financial institutions sending payments on behalf of their customers should populate their BIC in this field preceded by '/INST/' signifying that they are the instructing institution.", "minLength": 0, "maxLength": 140, "example": "Example further instruction text" }, "purpose": { "$ref": "#/components/schemas/Purpose" }, "remittanceInformation": { "$ref": "#/components/schemas/RemittanceInformation" }, "ultimateCreditor": { "$ref": "#/components/schemas/UltimateCreditor" } }, "additionalProperties": false }, "PaymentRequest": { "required": [ "currencyCode", "transactions" ], "type": "object", "properties": { "batchId": { "type": "string", "description": "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.", "format": "uuid", "nullable": true, "example": "d7cc6fda-52a5-5ba8-a03e-303746dc2501" }, "currencyCode": { "type": "string", "description": "Three-letter ISO currency code for the outbound payment. This field is case insensitive.", "example": "EUR", "minLength": 3, "maxLength": 3, "enum": ["EUR", "USD", "CAD", "CHF", "CZK", "DKK", "HUF", "NOK", "PLN", "RON", "SEK"] }, "transactions": { "type": "array", "description": "Array of transactions. The maximum batch size is 100.", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/PaymentRequestItem" } } }, "additionalProperties": false }, "PaymentResponse": { "type": "object", "properties": { "isScheduled": { "type": "boolean", "description": "Whether the payment(s) are scheduled for the next payment window.", "example": true } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true, "description": "A URI reference [RFC3986] that identifies a problem type. When dereferenced, it provides a human-readable documentation for the problem type. When not present, default value is assumed to be \"about:blank\"." }, "title": { "type": "string", "nullable": true, "description": "A short, human-readable summary of the problem type. " }, "status": { "type": "integer", "format": "int32", "nullable": true, "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem." }, "detail": { "type": "string", "nullable": true, "description": "A human-readable explanation of what went wrong. It can include specifics about the issue, missing parameters, or invalid data." }, "instance": { "type": "string", "nullable": true, "description": "A URL reference to a retrieve more information about the error, if available" } }, "additionalProperties": {} } } } }