openapi: 3.2.0
info:
  title: Modulr Confirmation of Payee API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Confirmation of Payee
  description: Account Name Checks
paths:
  /account-name-check:
    post:
      tags:
      - Confirmation of Payee
      summary: Create an account name check
      description: 'This endpoint allows you to check the account details of a payee with their bank before you create a beneficiary or payment. If the account details are confirmed, you will have greater assurance that a payment you create will reach the correct bank account.

        This endpoint does not support idempotent requests. Any requests containing an x-mod-nonce header used by a previous request will return the response <code>403: Forbidden ("Unique/allowed nonce header not found")</code>'
      operationId: createOutboundCop
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopResponse'
        '400':
          description: Validation Errors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /account-name-check/payer:
    post:
      tags:
      - Confirmation of Payee
      summary: Create an account name check for Direct Debit Payer
      description: 'Payer Name Verification (PNV) automatically checks that your payer’s name matches the name on the bank account details submitted when setting up BACS Direct Debits. This reduces your exposure to fraud and failed payment setups

        This endpoint does not support idempotent requests. Any requests containing an x-mod-nonce header used by a previous request will return the response <code>403: Forbidden ("Unique/allowed nonce header not found")</code>'
      operationId: createOutboundCheckForPnv
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopResponse'
        '400':
          description: Validation Errors
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopErrorResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /account-name-check/srd-accounts:
    get:
      tags:
      - Confirmation of Payee
      summary: Get SRD Accounts
      description: Returns a list of all sort codes and account numbers for which Secondary Reference Data must be provided with all account name check requests.
      operationId: getSrdAccounts
      parameters:
      - name: page
        in: query
        description: Page to fetch (0 indexed)
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 0
          minimum: 0
      - name: size
        in: query
        description: Size of Page to fetch
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 500
          maximum: 500
          minimum: 1
      responses:
        '200':
          description: Successfully retrieved SRD list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/confirmationofpayee.CopPageResponseJsonSrdAccount'
        '400':
          description: Invalid query params provided
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.MessageResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.MessageResponse'
        '403':
          description: CoP Access denied
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.MessageResponse'
        '500':
          description: Unexpected error occurred
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.MessageResponse'
        '503':
          description: Service outage
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/confirmationofpayee.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    confirmationofpayee.CopPageResponseJsonSrdAccount:
      type: object
      properties:
        content:
          type: array
          description: List of responses on the current page
          items:
            $ref: '#/components/schemas/confirmationofpayee.JsonSrdAccount'
        size:
          type: integer
          format: int32
          description: Page size
        totalSize:
          type: integer
          format: int64
          description: Total count
        page:
          type: integer
          format: int32
          description: Current page number, 0 based; i.e first-page = 0, second-page = 1
        totalPages:
          type: integer
          format: int32
          description: Total pages
      required:
      - content
      - page
      - size
      - totalPages
      - totalSize
    confirmationofpayee.JsonOutboundCopErrorResponse:
      type: object
      description: Account Name Check Error Response
      properties:
        id:
          type: string
        field:
          type: string
        code:
          type: string
        message:
          type: string
        sourceService:
          type: string
        errorCode:
          type: string
      required:
      - code
      - message
    confirmationofpayee.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    confirmationofpayee.JsonOutboundCopResponse:
      type: object
      description: Account Name Check Response
      properties:
        id:
          type: string
          description: Unique id for the account name check.
          example: C12001569Z
        result:
          $ref: '#/components/schemas/confirmationofpayee.JsonOutboundCopResult'
          description: The result of the account name check.
      required:
      - id
      - result
    confirmationofpayee.JsonOutboundCopResult:
      type: object
      description: Account Name Check Result
      properties:
        code:
          type: string
          description: The result of the account name check.
          enum:
          - MATCHED
          - NOT_MATCHED
          - CLOSE_MATCH
          - BUSINESS_ACCOUNT_NAME_MATCHED
          - PERSONAL_ACCOUNT_NAME_MATCHED
          - BUSINESS_ACCOUNT_CLOSE_MATCH
          - PERSONAL_ACCOUNT_CLOSE_MATCH
          - ACCOUNT_DOES_NOT_EXIST
          - SECONDARY_ACCOUNT_ID_NOT_FOUND
          - ACCOUNT_NOT_SUPPORTED
          - ACCOUNT_SWITCHED
          - WRONG_PARTICIPANT
          - NO_RESPONSE
          - NOT_ENROLLED
          example: MATCHED
        name:
          type: string
          description: The actual name on the account (as provided by the participating organisation).
          example: Joseph Bloggs
      required:
      - code
    confirmationofpayee.JsonOutboundCopRequest:
      type: object
      description: Details of Account Name Check Request
      properties:
        paymentAccountId:
          type: string
          description: The identifier of the account that a subsequent payment will be initiated from.
          example: A123AAA4
        sortCode:
          type: string
          description: The sort code of the account.
          example: '000000'
          pattern: ^[0-9]{6}$
        accountNumber:
          type: string
          description: The account number.
          example: '12345678'
          pattern: ^[0-9]{8}$
        secondaryAccountId:
          type: string
          description: Additional information used in conjunction with the Sort Code and Account Number to identify the account (such as a Building Society roll number).
          example: A-1234567890
          maxLength: 140
          minLength: 1
          pattern: ^.{0}$|^$|^([^])+$
        accountType:
          type: string
          description: The type of account, either a personal or business account.
          enum:
          - PERSONAL
          - BUSINESS
          example: PERSONAL
        name:
          type: string
          description: The name to match the account name against.
          example: Joe Bloggs
          maxLength: 140
          minLength: 1
      required:
      - accountNumber
      - accountType
      - name
      - paymentAccountId
      - sortCode
    confirmationofpayee.JsonSrdAccount:
      type: object
      properties:
        sortCode:
          type: string
          description: 'The sort code of one or more accounts that requires Secondary Reference Data to be provided when making account name check requests.

            '
          example: '123456'
        accountNumbers:
          type: array
          description: Account numbers that require Secondary Reference Data. If empty, Secondary Reference Data is required for all name check requests for this sort code.
          items:
            type: string
            description: The account number of a specific account that requires Secondary Reference Data to be provided when making account name check requests.
            example: '11111111'
      required:
      - sortCode
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false