ClearBank Co P API

openapi: 3.2.0
info:
  title: ClearBank..Outbound.Api 1.0 Co P API
  description: ClearBank API for CoP outbound requests
  version: 1.0.COP-Outbound
tags:
- name: CoP
paths:
  /open-banking/outbound/v1/name-verification:
    post:
      tags:
      - CoP
      summary: This endpoint is used to confirm the exact name registered with the payee’s account.
      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: CoP Outbound Request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CoPOutboundRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CoPOutboundRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CoPOutboundRequest'
      responses:
        '200':
          description: Success
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CoPOutboundResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CoPOutboundResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/CoPOutboundResponse'
        '403':
          description: Forbidden
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: CoP participant not found
        '424':
          description: Call to CoP participant resulted in an error
components:
  schemas:
    Data:
      type: object
      properties:
        VerificationReport:
          $ref: '#/components/schemas/VerificationReport'
      additionalProperties: false
      description: Information about the exact name registered with the payee’s account.
    CoPOutboundRequest:
      required:
      - Identification
      - LegalOwnerType
      - OwnerName
      - SchemeName
      type: object
      properties:
        SchemeName:
          minLength: 1
          type: string
          description: Indicates the sort code and account number associated with the payee’s account. The value should always be SortCodeAccountNumber.
        LegalOwnerType:
          minLength: 1
          type: string
          description: Nature of funds held in the account. Valid options are Personal or Business.
        Identification:
          minLength: 1
          type: string
          description: Payee's sort code and account number, used by an Account Servicing Payment Service Provider (ASPSP) to identify the account. In case the account number contains less than 8 digits, it can be padded with preceding zeros to make the length up to 8. The format should always be SortCodeAccountNumber   (e.g., “04040412345678”).
        OwnerName:
          maxLength: 140
          minLength: 1
          type: string
          description: OwnerName identifies the owner of the account. This must be in a structured or unstructured comma-delimited format. Both formats consist of three parts separated by commas. We recommend using the unstructured format for all CoP name verification requests. The unstructured format is valid for personal, business, and joint accounts. The full owner name string is populated in the third part (“ClearBank Ltd” would be “,,ClearBank Ltd”). The structured format is only valid for personal accounts. The three parts of the owner's name are comma-delimited (“Mr John Smith” would be “Mr, John, Smith”).
        SecondaryIdentification:
          maxLength: 140
          minLength: 0
          type:
          - string
          - 'null'
          description: Payment reference information as provided by the payer. If provided, this information may be used by the payee’s ASPSP to identify the account.
        EndToEndIdentification:
          maxLength: 140
          minLength: 0
          type:
          - string
          - 'null'
          description: A unique value which can be used to identify the CoP request and then used in any subsequent payment initiations to link them to this CoP request.
      additionalProperties: false
      description: Required information to perform a CoP check
    ErrorResponse:
      type: object
      properties:
        Error:
          $ref: '#/components/schemas/ErrorBody'
      additionalProperties: false
      description: Error response class.
    VerificationReport:
      required:
      - Matched
      - MatchedBank
      type: object
      properties:
        Matched:
          type: boolean
          description: True if there is a match. False when there is no match or a partial match.
        Name:
          type:
          - string
          - 'null'
          description: The account holder name in case of a partial match. This will not be present if there is a true match.
        ReasonCode:
          type:
          - string
          - 'null'
          description: Reason code for a more detailed description of the kind of match. Defined by Pay.UK. Provided if there is no match or a partial match. This will not be present if there is a true match.
        ReasonCodeDescription:
          type:
          - string
          - 'null'
          description: Detailed description of the reason code, as described by Pay.UK. Provided if there is no match or a partial match. This will not be present if there is a true match.
          readOnly: true
        MatchedBank:
          minLength: 1
          type: string
          description: The name of the bank that the CoP check was performed with.
        ResponseWithinSla:
          type: boolean
          description: Time taken by the responder for the CoP request
        LegalOwnerType:
          type:
          - string
          - 'null'
          description: Legal Owner Type used in the CoP check
        ResponderRegistrationId:
          type:
          - string
          - 'null'
          description: Open Banking Directory registration ID of the participant responding to the CoP request.
      additionalProperties: false
      description: Additional information, including the result of the name match.
    CoPOutboundResponse:
      type: object
      properties:
        Data:
          $ref: '#/components/schemas/Data'
      additionalProperties: false
      description: Response contract
    ErrorBody:
      type: object
      properties:
        Reason:
          type:
          - string
          - 'null'
          description: The error reason.
        ParticipantName:
          type:
          - string
          - 'null'
          description: Name of the participant.
      additionalProperties: false
      description: Error body with description.