Open Payments Verification of Payee (VoP) API

openapi: 3.2.0
info:
  title: Open Payments Verification of Payee (VoP) API
  version: 1.3.3
  description: '# Summary

    The Open Banking part of our API is based on The BerlinGroup NextGenPSD2 Framework with some additional services.'
  license:
    name: Creative Commons Attribution 4.0 International Public License
    url: https://creativecommons.org/licenses/by/4.0/
  contact:
    name: Open Payments Europe AB
    url: https://www.openpayments.io/
    email: info@openpayments.io
servers:
- url: https://api.openbankingplatform.com
- url: https://api.sandbox.openbankingplatform.com
security:
- {}
tags:
- name: Verification of Payee (VoP)
  description: The Verification of Payee (VoP) API allows you to instantly verify that a creditor's name matches the provided account details (IBAN) and display the result to your PSU, e.g. when they create a new supplier card in your system. With this API, you can provide enhanced security for your PSU's financial operations by reducing the risk of fraud and misdirected payments.
paths:
  /premium/v1/payee-verifications:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: Premium products sandbox server
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    post:
      summary: Submit Verification Request
      description: Returns a VoP result based on a creditor's name and IBAN.
      tags:
      - Verification of Payee (VoP)
      operationId: SubmitVerificationOfPayee
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      requestBody:
        $ref: '#/components/requestBodies/verificationOfPayee'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_VerificationOfPayee'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
      x-operation-id-source: normalized
      x-operation-id-original: Submit Verification of Payee
  /premium/v1/bulk-payee-verifications:
    servers:
    - url: https://api.sandbox.openbankingplatform.com
      description: Premium products sandbox server
    - url: https://api.openbankingplatform.com
      description: Premium products production server
    post:
      summary: Submit Bulk Verification Request
      description: Returns VoP results for multiple creditors.
      tags:
      - Verification of Payee (VoP)
      operationId: SubmitBulkVerificationOfPayee
      security:
      - oAuth2Sandbox:
        - paymentinitiation corporate
      - oAuth2Production:
        - paymentinitiation corporate
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/PSU-ID'
      - $ref: '#/components/parameters/PSU-Corporate-ID'
      requestBody:
        $ref: '#/components/requestBodies/bulkVerificationOfPayee'
      responses:
        '200':
          $ref: '#/components/responses/OK_200_BulkVerificationOfPayee'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseDetails'
        description: Returns VoP results
      x-operation-id-source: normalized
      x-operation-id-original: Submit Bulk Verification of Payee
components:
  schemas:
    vopParty:
      description: The registered name for the account.
      type: object
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/creditorName'
    verificationOfPayeeResponse:
      description: 'Body of the JSON response for a successful VoP request.

        '
      type: object
      required:
      - partyNameMatch
      properties:
        partyNameMatch:
          description: 'The match result of the VoP request in a 4-letter code. See Statuses & Types documentation for full descriptions of values.

            '
          type: string
          enum:
          - MTCH
          - CMTC
          - NMTC
          - NOAP
        matchedName:
          description: "The actual name found for the account. This is returned in case of a slight mismatch with the name provided in the request. \n"
          type: string
        tppMessages:
          type: array
          items:
            $ref: '#/components/schemas/tppMessage200_VoP'
    iban:
      type: string
      description: International Bank Account Number (IBAN) of an account.
      pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}'
      example: FR7612345987650123456789014
    ErrorResponseDetails:
      type: object
      properties:
        tppMessages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/tppMessage2XX'
      additionalProperties: false
    bulkVerificationOfPayeeResponseItem:
      allOf:
      - type: object
        required:
        - uetr
        properties:
          uetr:
            description: Unique reference identifying the party verification request.
            type: string
            format: uuid
      - $ref: '#/components/schemas/verificationOfPayeeResponse'
    creditorName:
      description: Creditor Name
      type: string
      maxLength: 70
      pattern: ^[A-Za-z0-9 ]{1,70}$
      example: Creditor Name
    tppMessage2XX:
      type: object
      required:
      - category
      - code
      properties:
        category:
          $ref: '#/components/schemas/tppMessageCategory'
        code:
          $ref: '#/components/schemas/MessageCode2XX'
        path:
          type: string
        text:
          $ref: '#/components/schemas/tppMessageText'
    verificationOfPayee_json:
      title: Verification of Payee
      description: 'Request Body for a Verification of Payee via JSON.

        '
      type: object
      required:
      - party
      - partyAccount
      properties:
        party:
          $ref: '#/components/schemas/vopParty'
        partyAccount:
          $ref: '#/components/schemas/vopPartyAccount'
        partyAgent:
          $ref: '#/components/schemas/vopPartyAgent'
    tppMessage200_VoP:
      type: object
      required:
      - category
      - code
      properties:
        category:
          $ref: '#/components/schemas/tppMessageCategory'
        code:
          $ref: '#/components/schemas/MessageCode200_VoP'
        text:
          $ref: '#/components/schemas/tppMessageText'
    tppMessageText:
      description: Additional explaining text to the TPP.
      type: string
      maxLength: 512
    MessageCode200_VoP:
      description: Message codes defined for Verification of Payee when the result is not a perfect match.
      type: string
      enum:
      - CREDITOR_NAME_MISMATCH
      - CREDITOR_NAME_CLOSE_MATCH
      - CREDITOR_NAME_UNVERIFIED
    vopPartyAgent:
      $ref: '#/components/schemas/bicfi'
    bicfi:
      description: 'BICFI

        '
      type: string
      pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}'
      example: AAAADEBBXXX
    MessageCode2XX:
      description: Message codes for HTTP Error codes 2XX.
      type: string
    tppMessageCategory:
      description: Category of the TPP message category
      type: string
      enum:
      - INFORMATION
      - UNMAPPED
      - ERROR
      - WARNING
    vopPartyAccount:
      description: The IBAN of the account.
      type: object
      required:
      - iban
      properties:
        iban:
          $ref: '#/components/schemas/iban'
    bulkVerificationOfPayee_json:
      title: Bulk Verification of Payee
      description: 'Request Body for a Bulk Verification of Payee via JSON.

        '
      type: object
      required:
      - partyVerificationRequests
      properties:
        partyVerificationRequests:
          type: array
          items:
            allOf:
            - type: object
              required:
              - uetr
              - party
              - partyAccount
              properties:
                uetr:
                  description: Unique reference identifying the party verification request.
                  type: string
                  format: uuid
                party:
                  $ref: '#/components/schemas/vopParty'
                partyAccount:
                  $ref: '#/components/schemas/vopPartyAccount'
                partyAgent:
                  $ref: '#/components/schemas/vopPartyAgent'
    bulkVerificationOfPayeeResponse:
      description: 'Body of the JSON response for a successful bulk VoP request.

        '
      type: object
      required:
      - partyVerificationResponses
      properties:
        partyVerificationResponses:
          type: array
          items:
            $ref: '#/components/schemas/bulkVerificationOfPayeeResponseItem'
  responses:
    OK_200_VerificationOfPayee:
      description: OK
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verificationOfPayeeResponse'
          examples:
            Example:
              $ref: '#/components/examples/verificationOfPayeeResponseExample'
    OK_200_BulkVerificationOfPayee:
      description: OK
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/bulkVerificationOfPayeeResponse'
          examples:
            Example:
              $ref: '#/components/examples/bulkVerificationOfPayeeResponseExample'
  examples:
    verificationOfPayeeResponseExample:
      value:
        partyNameMatch: CMTC
        matchedName: Acme AB
        tppMessages:
        - category: WARNING
          code: CREDITOR_NAME_CLOSE_MATCH
          text: Creditor name closely matches the registered name of the account.
    bulkVerificationOfPayeeResponseExample:
      value:
        partyVerificationResponses:
        - uetr: ab450982-a52d-49b6-90a7-a949535a5ca1
          partyNameMatch: MTCH
        - uetr: a1874514-a2ae-408c-93fc-588228876394
          partyNameMatch: CMTC
          matchedName: Company AB
          tppMessages:
          - category: WARNING
            code: CREDITOR_NAME_CLOSE_MATCH
            text: Creditor name closely matches the registered name of the account.
        - uetr: 4932e93d-e04b-4813-b126-49df7d321f3f
          partyNameMatch: NMTC
          tppMessages:
          - category: WARNING
            code: CREDITOR_NAME_MISMATCH
            text: Creditor name does not match the registered name of the account.
    bulkVerificationOfPayeeExample:
      value:
        partyVerificationRequests:
        - uetr: ab450982-a52d-49b6-90a7-a949535a5ca1
          party:
            name: Acme
          partyAccount:
            iban: SE4550000000058398257466
          partyAgent: ESSESESS
        - uetr: a1874514-a2ae-408c-93fc-588228876394
          party:
            name: Company
          partyAccount:
            iban: FI2112345600000785
          partyAgent: NDEAFIHH
        - uetr: 4932e93d-e04b-4813-b126-49df7d321f3f
          party:
            name: Other Company
          partyAccount:
            iban: FI4950009420002319
          partyAgent: OKOYFIHH
    verificationOfPayeeExample:
      value:
        party:
          name: Acme
        partyAccount:
          iban: SE4550000000058398257466
        partyAgent: ESSESESS
  parameters:
    PSU-ID:
      name: PSU-ID
      in: header
      description: 'Client ID of the PSU in the ASPSP client interface. This is typically a local social security number or another unique login ID.

        '
      schema:
        type: string
      required: true
      example: 199002092386
    PSU-Corporate-ID:
      name: PSU-Corporate-ID
      in: header
      description: 'Corporate Client ID for the ASPSP. This is typically the unique Corporate ID in the local format. E.g. Org. nummer for SE, KVK for NL. **Mandatory in the corporate scope**.

        '
      schema:
        type: string
      required: false
      example: 5560160680
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: ID of the request, unique to the call, as determined by the initiating party.
      required: true
      example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
      schema:
        type: string
        format: uuid
  headers:
    X-Request-ID:
      description: ID of the request, unique to the call, as determined by the initiating party.
      required: true
      example: 99391c7e-ad88-49ec-a2ad-99ddcb1f7721
      schema:
        type: string
        format: uuid
  requestBodies:
    verificationOfPayee:
      description: 'JSON request body for a VoP request.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/verificationOfPayee_json'
          examples:
            Example:
              $ref: '#/components/examples/verificationOfPayeeExample'
    bulkVerificationOfPayee:
      description: 'JSON request for a bulk VoP request.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/bulkVerificationOfPayee_json'
          examples:
            Example:
              $ref: '#/components/examples/bulkVerificationOfPayeeExample'
  securitySchemes:
    oAuth2Sandbox:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
    oAuth2Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.openbankingplatform.com/connect/token
          scopes:
            aspspinformation: ASPSP Information
            accountinformation: Account Information
            bankgiroinformation: Account Information Enrichment
            paymentinitiation: Payment Initiation
            private: Private accounts context
            corporate: Corporate accounts context
externalDocs:
  description: 'Full Documentation of NextGenPSD2 Access to Account Interoperability Framework

    (General Introduction Paper, Operational Rules, Implementation Guidelines)

    '
  url: https://www.berlin-group.org/nextgenpsd2-downloads
x-tagGroups:
- name: Core APIs
  tags:
  - ASPSP Information Service
  - Consent Service
  - Account Information Service (AIS)
  - Payment Initiation Service (PIS)
  - KYC Service
- name: Alternative APIs
  tags:
  - ISO Payments
  - FX Connect
- name: Premium APIs
  tags:
  - Bankgiro Lookup
  - Payout Service
  - Verification of Payee (VoP)
  - SEPA Direct Debit