openapi: 3.2.0 info: title: FI Initiation API 3.0 Fps Payments API description: FI Initiation API version: 3.0.FPS-payment tags: - name: FpsPayments paths: /v3/payments/fps: post: tags: - FpsPayments summary: Initiate a payment using the faster payments scheme. This endpoint is FTR compliant. description: "This endpoint works on a partial acceptance basis - meaning that you can submit 10 payments and only 6 of them may be accepted for processing.\n \nEach payment instruction is validated against the scheme specific rules as well as the ISO20022 specification.\n \nCurrently, only payments through GBP are supported. We have listed possible currencies for future proofing of the API.\n \nThe remittance information must be scheme compatible. Values exceeding the length limits of the scheme will be truncated. Missing remittance information will be replaced by a blank string." operationId: Post 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: description: Information that should be used to create a batch credit transfer. content: application/json: schema: $ref: '#/components/schemas/BatchCreateCreditTransferRequest' x-bodyName: request responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/BatchCreditTransferResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/OtherProblemDetails' '404': description: Not Found '422': description: Client Error content: application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' /v3/payments/fps/return: post: tags: - FpsPayments summary: Return an inbound Faster Payment. This endpoint can be used to return Faster Payments - including Faster Payments Originating Overseas - that cleared less than 90 days ago. description: This endpoint is the recommended method for returning Faster Payments that cannot be completed for any reason. operationId: PostReturn 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: description: Information that should be used to create an FPS return. content: application/json: schema: $ref: '#/components/schemas/CreateReturnCreditTransferRequest' x-bodyName: request responses: '202': description: Accepted '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '403': description: Forbidden '404': description: Not Found '422': description: Client Error content: application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' components: schemas: CounterpartAccountGenericIdentificationScheme: type: object properties: code: enum: - BBAN - CUID - UPIC type: - string - 'null' description: Name of the identification scheme in coded form. No need to specify if you are providing this information in free-form text in the "proprietary" field. proprietary: maxLength: 35 minLength: 0 type: - string - 'null' 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., in the "code" field). example: Example scheme additionalProperties: false description: Information about the identification scheme in coded form or free-form text. PaymentInstructionResponse: required: - endToEndIdentification - response type: object properties: endToEndIdentification: type: string description: Unique identification, as assigned by the initiating party to unambiguously identify the transaction. example: E2E12345 response: enum: - Accepted - InsufficientFunds - InvalidAccount - InvalidCurrency - Rejected - DebitPaymentDisabled - InvalidInstructionIdentification type: string description: The result of how the payment instruction has been processed. example: Accepted additionalProperties: false description: The acceptance or rejection status of a payment instruction. BatchCreateCreditTransferRequest: required: - paymentInstructions type: object properties: paymentInstructions: type: array maxLength: 10 minLength: 1 items: $ref: '#/components/schemas/BatchPaymentInstruction' description: Details of the payments to be made. additionalProperties: false description: Information that should be used to create a batch credit transfer. BatchStructured: type: object properties: creditorReferenceInformation: $ref: '#/components/schemas/BatchCreditorReferenceInformation' description: Reference information provided by the debtor to allow the identification of underlying documents by the creditor. additionalProperties: false description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (for example, a purchase reference number). HalLink: required: - href - name type: object properties: name: type: string description: The named link type. href: type: string description: URI to be used. templated: type: boolean description: Specifies "true" if href is a URI template, i.e., with parameters. Otherwise, this property is absent or set to false. additionalProperties: false description: Hypermedia link. BatchRemittanceInformation: type: object properties: structured: $ref: '#/components/schemas/BatchStructured' description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (e.g., a purchase reference number). unstructured: $ref: '#/components/schemas/BatchUnstructured' description: Information supplied by the remitter (in an unstructured form) to reconcile an entry with item(s) that the payment intends to settle. additionalProperties: false description: Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system. ValidationProblemDetails: type: object properties: errors: type: - object - 'null' additionalProperties: type: array items: type: string description: The validation errors. example: field1: - Error message 1 field2: - Error message 2 type: type: - string - 'null' description: A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be "about:blank". example: https://example.com/probs/error-code title: type: - string - 'null' description: A short, human-readable summary of the problem type. It should not change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see[RFC7231], Section 3.4). example: Error title status: type: - integer - 'null' description: The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem. format: int32 example: 400 detail: type: - string - 'null' description: A human-readable explanation specific to this occurrence of the problem. example: The request is invalid. See errors for details. instance: type: - string - 'null' description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: /errors/12345 additionalProperties: {} description: A machine-readable format for specifying errors in HTTP API responses based on https://tools.ietf.org/html/rfc7807 BatchCreditorPartyIdentifier: required: - name type: object properties: name: maxLength: 140 minLength: 1 type: string description: The name of the account holder. example: Aisha Khan legalEntityIndentifier: maxLength: 35 minLength: 0 type: - string - 'null' description: 'The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.' example: 9485839XYZ additionalProperties: false description: The name and, optionally, the legal entity identifier of the account. BatchPaymentInstructionCounterpartAccount: required: - identification type: object properties: identification: $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccountIdentification' description: The identifiable information of an account. additionalProperties: false description: Information about the counterpart in a given transaction. BatchCreditTransferResponse: type: object properties: transactions: type: - array - 'null' items: $ref: '#/components/schemas/PaymentInstructionResponse' description: An array containing the the acceptance or rejection status of each individual payment instruction. You'll receive a 400 - Bad Request response if all payments in the batch fail. You'll receive a 202 - Accepted response if any payments in the batch succeed. halLinks: type: - array - 'null' items: $ref: '#/components/schemas/HalLink' description: Hypermedia links. additionalProperties: false description: The result of each payment instruction and applicable links BatchCreditorReferenceInformation: type: object properties: reference: maxLength: 35 minLength: 0 type: - string - 'null' description: A reference, as assigned by the debtor to unambiguously refer to the payment transaction. Conditionally required if supplied by the debtor. example: Payment for invoice 12345 additionalProperties: false description: Reference information provided by the ultimate debtor to allow the identification of underlying documents by the creditor. CreateReturnCreditTransferRequest: required: - paymentReturnInstruction type: object properties: paymentReturnInstruction: $ref: '#/components/schemas/PaymentReturnInstruction' description: Information about the payment return. additionalProperties: false description: Information that should be used to create a single credit return. PaymentReturnInstruction: required: - TransactionId - ReasonForReturn type: object properties: TransactionId: maxLength: 36 minLength: 1 type: string description: The ID of the transaction to be returned. format: uuid ReasonForReturn: type: string description: 'A scheme compliant return code. Accepted values: [ BeneficiarySortCodeOrAccountUnknown, BeneficiaryAccountClosed, BeneficiaryAccountStopped, BeneficiaryDeceased, AccountCannotBeIdentified, BeneficiaryAccountNameDoesNotMatchBeneficiaryAccountNumber, ReturnRequestedBySenderOfOriginalPayment, AccountIsNotInCurrencyQuoted, BeneficiaryNotExpectingFundsOrInstructedReturn, TermsAndConditionsOfAccountDoNotPermitCreditingOfFunds, SendingFpsInstitutionActionRequired, AccountTransferred, PaymentCannotBeAppliedBecauseOfBeneficiarySensitivities, Other ]' additionalProperties: false description: Information about the single payment return instruction. BatchCreditTransfer: required: - amount - creditor - creditorAccount - paymentIdentification - remittanceInformation type: object properties: paymentIdentification: $ref: '#/components/schemas/BatchPaymentIdentification' description: Identification of the payment instruction. amount: $ref: '#/components/schemas/BatchAmount' description: Indicates the amount and the currency used in a given transaction or account balance. creditor: $ref: '#/components/schemas/BatchCreditorPartyIdentifier' description: The name and, optionally, the legal entity identifier of the account. creditorAccount: $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccount' description: Information about the counterpart in a given transaction. remittanceInformation: $ref: '#/components/schemas/BatchRemittanceInformation' description: Information supplied to enable the matching/reconciliation of an entry with the items that the payment is intended to settle, such as commercial invoices in an accounts receivable system. enforceSendToScheme: type: boolean description: If set to true, then the payment will be sent to scheme for processing. If set to false or not supplied, then it will be processed as an internal transfer if eligible. additionalProperties: false description: Represents a creditor in a payment instruction. OtherProblemDetails: type: object properties: transactions: type: - array - 'null' items: type: object properties: endToEndIdentification: type: string example: E2E12345 description: Unique identification, as assigned by the initiating party to unambiguously identify the transaction. response: description: Indicates the reason for the rejection of the payment instruction. enum: - Accepted - InsufficientFunds - InvalidAccount - InvalidCurrency - Rejected - DebitPaymentDisabled - InvalidInstructionIdentification type: string example: InsufficientFunds description: If all payments in the batch fail, you'll receive a 400 response containing this array in the body, with an entry for each failed payment. You'll receive a 202 - Accepted response if any payments in the batch succeed. The model for 400 responses will match the model of 422 - Client Error in all other cases. additionalProperties: false BatchAmount: required: - instructedAmount type: object properties: currency: enum: - ALL - DZD - ARS - AUD - BSD - BHD - BDT - AMD - BBD - BMD - BTN - BOB - BWP - BZD - SBD - BND - MMK - BIF - KHR - CAD - CVE - KYD - LKR - CLP - CNY - COP - KMF - CRC - HRK - CUP - CZK - DKK - DOP - SVC - ETB - ERN - FKP - FJD - DJF - GMD - GIP - GTQ - GNF - GYD - HTG - HNL - HKD - HUF - ISK - INR - IDR - IRR - IQD - ILS - JMD - JPY - KZT - JOD - KES - KPW - KRW - KWD - KGS - LAK - LBP - LSL - LRD - LYD - MOP - MWK - MYR - MVR - MUR - MXN - MNT - MDL - MAD - OMR - NAD - NPR - ANG - AWG - VUV - NZD - NIO - NGN - NOK - PKR - PAB - PGK - PYG - PEN - PHP - QAR - RUB - RWF - SHP - SAR - SCR - SLL - SGD - VND - SOS - ZAR - SSP - SZL - SEK - CHF - SYP - THB - TOP - TTD - AED - TND - UGX - MKD - EGP - GBP - TZS - USD - UYU - UZS - WST - YER - TWD - MRU - STN - CUC - ZWL - BYN - TMT - GHS - VEF - SDG - UYI - RSD - MZN - AZN - RON - CHE - CHW - TRY - XAF - XCD - XOF - XPF - XBA - XBB - XBC - XBD - XAU - XDR - XAG - XPT - XTS - XPD - XUA - ZMW - SRD - MGA - COU - AFN - TJS - AOA - BGN - CDF - BAM - EUR - MXV - UAH - GEL - BOV - PLN - BRL - CLF - XSU - USN - XXX type: - string - 'null' example: GBP description: Set to 'GBP' as other currencies are not supported. instructedAmount: type: number description: Amount of funds to be moved between the debtor and creditor (prior to deduction of charges) in GBP. format: double example: 100.0 additionalProperties: false description: Indicates the amount and the currency used in a given transaction or account balance. BatchDebtorPartyIdentifier: required: - address type: object properties: legalEntityIdentifier: maxLength: 35 minLength: 0 type: - string - 'null' description: 'The legal entity identifier of the account holder (eg: charity number). This should be supplied if known.' example: 9485839XYZ address: maxLength: 140 minLength: 1 pattern: ^[a-zA-Z0-9\/\-?:().,'+ ]*$ type: string description: 'The full postal address of the account holder. For UK addresses, the order of this information MUST be: country, town, city, state/province/municipality, street name, building number and/or name, postal code.' example: UK, Manchester, Greater Manchester, Oxford Road, 123, M13 9PL additionalProperties: false description: 'Optionally, the Legal Entity Identifier of the account. Mandatory the Address of the account.' BatchCounterpartAccountGenericIdentification: required: - identification - schemeName type: object properties: issuer: maxLength: 35 minLength: 0 type: - string - 'null' description: The name of the entity that assigns the identification. example: Example Passport identification: maxLength: 34 minLength: 1 type: string description: Identification assigned by an institution. example: '123456789012345678' schemeName: $ref: '#/components/schemas/CounterpartAccountGenericIdentificationScheme' description: Name of the identification scheme. additionalProperties: false description: Unique identification of an account, as assigned by the account servicer, using an identification scheme. BatchUnstructured: type: object properties: additionalReferenceInformation: $ref: '#/components/schemas/BatchAdditionalReferenceInformation' description: Additional unstructured remittance information. additionalProperties: false description: Information supplied by the remitter (in a structured form), to reconcile an entry with item(s) that the payment intends to settle (for example, a purchase reference number). BatchAdditionalReferenceInformation: type: object properties: reference: maxLength: 140 minLength: 0 type: - string - 'null' description: Additional remittance information. example: Plumbing payment additionalProperties: false description: Reference information provided by the ultimate debtor to allow the identification of underlying documents by the creditor. BatchPaymentIdentification: required: - endToEndIdentification - instructionIdentification type: object properties: instructionIdentification: maxLength: 35 minLength: 1 type: string description: Unique identification, as assigned by an instructing party for an instructed party, to unambiguously identify the instruction. example: PAYMENT12345 endToEndIdentification: maxLength: 35 minLength: 1 type: string description: Unique identification, as assigned by the initiating party to unambiguously identify the transaction. This identification is passed on unchanged throughout the entire end-to-end chain. example: E2E12345 additionalProperties: false description: Identification of the payment instruction. BatchPaymentInstructionCounterpartAccountIdentification: type: object properties: iban: type: - string - 'null' description: The International Bank Account Number of the account. example: GB29NWBK60161331926819 other: $ref: '#/components/schemas/BatchCounterpartAccountGenericIdentification' description: Unique identification of an account, as assigned by the account servicer, using an identification scheme. additionalProperties: false description: The identifiable information of an account. BatchPaymentInstruction: required: - creditTransfers - debtor - debtorAccount - paymentInstructionIdentification type: object properties: debtor: $ref: '#/components/schemas/BatchDebtorPartyIdentifier' description: Details about the account holder. paymentInstructionIdentification: maxLength: 35 minLength: 1 type: string description: The unique identifier for the payment instruction. example: INSTRUCTION12345 paymentTypeCode: type: string maxLength: 3 minLength: 3 description: A three-letter code signifying the type of payment. SIP - Single immediate payment, SOP - Standing order payment, FDP - Forward-dated payment. enum: - SIP - SOP - FDP debtorAccount: $ref: '#/components/schemas/BatchPaymentInstructionCounterpartAccount' description: Information about the counterpart in a given transaction. creditTransfers: type: array maxLength: 10 minLength: 1 items: $ref: '#/components/schemas/BatchCreditTransfer' description: A series of payments that should be made from the debtor account. additionalProperties: false description: A payment from a single account to multiple creditors.