> ## Documentation Index > Fetch the complete documentation index at: https://docs.finventi.com/llms.txt > Use this file to discover all available pages before exploring further. # Verify if IBAN holder name or legal entity ID matches > Submit an IBAN together with either **account_holder_name** or **organisation_identification** (**additional_attribute** is optional) ## OpenAPI ````yaml post /v1/accounts/payee-verification openapi: 3.0.1 info: description: "# General information\nThis API guide provides a comprehensive overview of integrating with the Inventi Verification of Payee (VoP) service, designed to validate account ownership before a payment is initiated. It is intended for use by financial institutions or payment service providers (PSPs), intended for organizations acting in either two roles inititating verification of payee requests or responding with ownership data for validation.\n\nThis guide covers the following topics\n- Authentication and secure access\n- Environment configuration\n- Using the Verification of Payee (VoP) API\n- Understanding verification outcomes\n- Using the Account Data Import API\n- Request and Response Formats and Error handling\n\n\n## Base API URL for environments:\n- TEST: https://api.vop-sandbox.finventi.com\n\n\n## Authentication\nNOTE: IP whitelisting is mandatory to gain access to our APIs in both TEST and PROD environments. To register your IPs, please contact `connectors-support@inventi.lt`.\n\nOur API uses OAuth 2.0 for authentication. To access the API, you need to obtain a bearer token from the authorization server.\n\n\n### Obtain a Bearer Token\nTo get a bearer token, use the following cURL command:\n\n```\ncurl -X POST \\\n--location '/realms//protocol/openid-connect/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=api-vop-client' \\\n--data-urlencode 'client_secret='\n```\n\nwhere:\n\n`` is either `https://auth.sandbox.finventi.com/` (TEST) or `https://auth.finventi.com/` (PROD).\n\n`` is a value of TenantID that was assigned by INVENTI team during initial configuration and could be found in Configuration Matrix that was shared to your representative.\n\n`` is a value that can be obtained by logging into SEPA Dashboard UI and going to User Management -> Clients -> `api-vop-client` -> Credentials -> Client Secret.\n\nNOTE: The token is valid for 45 minutes.\n\n### Include the Bearer Token in Requests\nInclude the obtained token in the `Authorization` header of your API requests with the `Bearer` prefix:\n\n```\nAuthorization: Bearer \n```\n\n### Example Request:\n```\ncurl --location --request POST 'https://api.vop-sandbox.finventi.com/api/v1/accounts' \\\n--header 'Authorization: Bearer ' \\\n```\n\n\n## Overview of the APIs\nThe Verification of Payee (VoP) service is accessible through two core APIs, each serving a distinct function:\n1. VoP API - Sending VoP requests\nReal-Time Verification\n\nThis API allows clients to verify whether a specified IBAN corresponds to a particular payee prior to executing a transaction.\n\nTwo verification checks are supported:\n- IBAN + Account Holder Name â\x80\x93 used to verify natural persons or legal entities based on the name provided\n- IBAN + Legal Entity Identifier (e.g., VAT, LEI) â\x80\x93 used to verify legal entities based on official registration identifiers\n\nThis API is designed for real-time use, typically invoked during payment initiation. Upon processing a request, the service returns one of the following outcomes: MATCH, CLOSE_MATCH, NO_MATCH, or CANNOT_VERIFY.\n\n2. Account Data Import API\nAccount Data Provisioning\n\nThis API enabled Responding PSPs to manage the dataset against which VoP checks are validated.\n\nIt allows for the following operations.\n- Importing new IBAN-to-holder records.\n- Updating existing records (e.g., changes in name or legal entity ID).\n- Deleting outdated or obsolete records.\n\nThis API supports both single-record and batch operations for import and delete actions. However, update operations are restricted to single-record requests only.\n\n\n## Sending VoP Requests\nVerification is initiated by sending a real-time request to Inventi's routing engine. The system returns a match status based on comparison results. Verification can be conducted via:\n- Name-based checksâ\x80\x93 for verifying individuals or legal entities entities based on the account-holder names\n- Legal identifier checks â\x80\x93 for verifying legal entities using national or international registration numbers (e.g., VAT, LEI)\nBoth verification methods have defined parameters, examples of requests and response formats, and validation rules specific to the test and production environments.\nError Handling: This guide currently covers general error types. Specific use case errors will be documented in future updates.\nBatch Requests: Batch request functionality in under development and will be release in the future.\n\n## Account Data Import\nTo participate as a Responding PSP, account holders and IBANs must be provided. This information is used by the VoP service to perform matching during incoming verification requests.\n\nThe Account Data Import API supports to:\n- Importing new IBAN + account holder mappings.\n- Updating existing records.\n- Deleting outdated records.\n\nAll data management endpoints include defined parameters, sample requests and response formats, and validation rules specific to the test and production environments.\nError Handling: This guide currently covers general error types. Specific use case errors will be documented in future updates.\nAdditional notes:\n- No validation is performed on input data (e.g., the system does not verify IBANs are genuine or names formatted correctly).\n- All imported data is stored in an internal Accounts database and becomes immediately available for matching.\n" title: Inventi Verification of Payee (VoP) API Guide version: 0.1.2 servers: - description: VoP test environment url: https://api.vop-sandbox.finventi.com - description: VoP prod environment url: https://api.vop.finventi.com security: [] tags: - description: >- Real-time check to confirm if a provided IBAN matches a given name or legal identifier. Returns a status such as MATCH, CLOSE_MATCH, NO_MATCH, or CANNOT_VERIFY. name: Verification of Account holder paths: /v1/accounts/payee-verification: post: tags: - Verification of Account holder summary: Verify if IBAN holder name or legal entity ID matches description: >- Submit an IBAN together with either: `account_holder_name` or `organisation_identification` (`additional_attribute` is optional) operationId: checkIban parameters: - description: Idempotency key to prevent duplicate requests example: b7f3f8a2-9e0c-4d1e-8a2f-1234567890ab in: header name: Idempotency-Key required: true schema: type: string requestBody: content: application/json: examples: '`account_holder_name` based example': description: '`account_holder_name` based example' value: account_holder_name: Name Example iban: LT123456789012345678 '`bic` based example': description: '`bic` based example' value: iban: LT123456789012345678 organisation_identification: bic: '123456789012345678' '`lei` based example': description: '`lei` based example' value: iban: LT123456789012345678 organisation_identification: lei: '123456789012345678' '`other.scheme_name_code` based example': description: '`other.scheme_name_code` based example' value: iban: LT123456789012345678 organisation_identification: other: identification: '123456789' scheme_name_code: BANK '`other.scheme_name_proprietary` based example': description: '`other.scheme_name_proprietary` based example' value: iban: LT123456789012345678 organisation_identification: other: identification: '123456789' scheme_name_proprietary: LocalRegistry schema: $ref: '#/components/schemas/VerificationOfPayeeRequest' description: >- Payload containing:`iban` (string, mandatory); one of `account_holder_name` (string) OR `organisation_identification` (object); `additional_attribute` (string, optional) required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/VerificationOfPayeeResponse' description: Verification result '400': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: Invalid request payload '403': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: "Forbidden â\x80\x93 tenant not allowed" components: schemas: VerificationOfPayeeRequest: properties: account_holder_name: description: >- Account holder name (natural person or legal entity) of the associated IBAN. type: string additional_attribute: description: Additional free-text metadata (e.g. payment context, internal ref) type: string iban: description: IBAN to verify minLength: 1 type: string organisation_identification: $ref: '#/components/schemas/OrganisationId' responding_psp_bic: description: >- 11 character ISO code assigned by SWIFT and used to identify a financial institution in financial transactions. type: string required: - iban type: object VerificationOfPayeeResponse: properties: match_result: description: >- Result of the VoP check: one of MATCH, CLOSE_MATCH, NO_MATCH, CANNOT_VERIFY enum: - MATCH - CLOSE_MATCH - NO_MATCH - CANNOT_VERIFY example: CLOSE_MATCH type: string real_name: description: >- Present if matchResult == CLOSE_MATCH; the best-matched account holder name example: Alice Johnson type: string reference_id: description: Unique ID associated with the VoP request (traceable for audit) example: 123e4567-e89b-12d3-a456-426614174000 type: string timestamp: description: ISO 8601 datetime of when the check was processed example: '2025-04-29T15:30:00Z' format: date-time type: string required: - match_result - reference_id - timestamp type: object Problem: properties: detail: type: string instance: format: uri type: string parameters: additionalProperties: type: object type: object status: $ref: '#/components/schemas/StatusType' title: type: string type: format: uri type: string type: object OrganisationId: description: >- Legal-entity identifiers for the IBAN owner. Either `lei`, `bic` or `other` must be provided. properties: bic: description: >- Business Identifier Code (BIC). 8 or 11 characters, conforming to ISO 9362 format. type: string lei: description: Legal Entity Identifier (LEI) conforming to ISO 17442 format. type: string other: $ref: '#/components/schemas/OtherOrganisationIdRequest' type: object StatusType: properties: reasonPhrase: type: string statusCode: format: int32 type: integer type: object OtherOrganisationIdRequest: description: Custom identification scheme for organisations. properties: identification: description: Identifier value in this custom scheme. maxLength: 256 minLength: 1 type: string issuer: description: Authority or body that issued this identifier. type: string scheme_name_code: description: Coded name of the identifier scheme enum: - BANK - CBID - CHID - CINC - COID - CUST - DUNS - EMPL - GS1G - SREN - SRET - TXID - BDID - BOID type: string scheme_name_proprietary: description: Proprietary name of the identifier scheme. type: string required: - identification type: object ````