Using the Verification of Payee service

Algorithms

When processing the Verification of Payee verification results on the ecommpay payment platform side, it is permissible to select and use one of the following operation approval algorithms (with subsequent processing after the final verification status is set and matches one of the approved ones).

• Algorithm 1 is based on the following rules:
  • MATCH status indicates that the corresponding operation can be processed.
  • CLOSE_MATCH, NO_MATCH, VERIFICATION_NOT_POSSIBLE and VOP_ERROR statuses indicate that the corresponding operation cannot be processed.
• Algorithm 2 is based on the following rules:
  • MATCH and CLOSE_MATCH statuses indicate that the corresponding operation can be processed.
  • NO_MATCH, VERIFICATION_NOT_POSSIBLE and VOP_ERROR statuses indicate that the corresponding operation cannot be processed.
• Algorithm 3 is based on the following rules:
  • MATCH, CLOSE_MATCH and VERIFICATION_NOT_POSSIBLE statuses indicate that the corresponding operation can be processed.
  • NO_MATCH and VOP_ERROR statuses indicate that the corresponding operation cannot be processed.
• Algorithm 4 is based on the following rule: all statuses (including the NO_MATCH status) as well as statuses indicating the impossibility of verification indicate that the corresponding operation can be processed.

These rules can be briefly presented in the form of a table.

Result monitoring

Information about the Verification of Payee result for any operation within this workflow can be obtained via a final callback containing information about the operation completion. Callbacks in such cases use a standard format, described in the article Handling callbacks. Information about the final status of this verification is specified in the parameters of the provider_extra_fields object. In cases where operations are declined, you can additionally rely on the final response codes for verification information, such as these:

• 20450—when an operation is declined due to a failed verification (for the VERIFICATION_NOT_POSSIBLE status in algorithms 1–2 and the VOP_ERROR status in algorithms 1–3).
• 20451—when an operation is declined due to the final verification status not matching the approved status (for the CLOSE_MATCH status in algorithm 1 and the NO_MATCH status in algorithms 1–3).

The following is an example of a callback with information about a 10.00 EUR payout made in the 239 project. The vop_status parameter of the provider_extra_fields object included in this callback indicates the CLOSE_MATCH status of the verification.

{
        "provider_extra_fields": {
            "customer_name": "John Smit",
            "operation_id_in_ps": "TX55DE3DEFC161XT",
            "vop_status": "CLOSE_MATCH",
            "vop_message": "Reasons: NAME_MISMATCH; Details: The account details are a close match.; Matched: name: JOHN SMITH"
        },
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "LV35HA******6833"
        },
        "project_id": 239,
        "payment": {
            "id": "Test payment 02042026-111",
            "type": "payout",
            "status": "success",
            "date": "2026-04-02T11:12:47+0000",
            "method": "world",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "test payout"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16711,
                "payment_id": "P21132ZU06",
                "auth_code": "",
                "date": "2026-04-02T11:11:51+0000"
            },
            "id": 94413010223457,
            "type": "payout",
            "status": "success",
            "date": "2026-04-02T11:12:47+0000",
            "created_date": "2026-04-02T11:11:43+0000",
            "request_id": "7eee81073a807f30094414"
        },
        "signature": "<signature>"
    }

The following is an example of a callback with information about a payout declined due to complete mismatch of the names, which is indicated by the NO_MATCH status.

{
        "provider_extra_fields": {
            "vop_status": "NO_MATCH",
            "vop_message": "Reasons: NAME_MISMATCH, ACCOUNT_MISMATCH; Details: The account and name do not match."
        },
        "customer": {
            "id": "1"
        },
        "account": {
            "number": "LV35HA******6833"
        },
        "project_id": 155543,
        "payment": {
            "id": "Test payment 02042026-115",
            "type": "payout",
            "status": "decline",
            "date": "2026-04-02T11:22:20+0000",
            "method": "world",
            "sum": {
                "amount": 1,
                "currency": "EUR"
            },
            "description": "test payout"
        },
        "operation": {
            "sum_initial": {
                "amount": 1,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1,
                "currency": "EUR"
            },
            "code": "20451",
            "message": "Payout or refund cannot be processed based on the Verification of Payee result",
            "provider": {
                "id": 16711,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 43116010187149,
            "type": "payout",
            "status": "decline",
            "date": "2026-04-02T11:22:21+0000",
            "created_date": "2026-04-02T11:22:18+0000",
            "request_id": "21356"
        },
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    }

Overview

When processing Verification of Payee results on the web service side, additional interactions between the web service and the platform must be organized for each transaction involving the verification procedure. This involves a series of steps between accepting a customer request to receive funds and initiating the corresponding operation in the platform:

• Send a Verification of Payee request (with the required parameters and signature) to the ecommpay URL.
• Receive a synchronous response from the payment platform containing the information about initiating the verification.
• After at least 10 seconds, send a request to receive verification result information (with the required parameters and signature) to the ecommpay URL.
• Receive a synchronous response from the payment platform containing the information about the verification status.

After this process, in each case, a decision must be made on the web service side regarding the permissibility of the operation (in accordance with the implemented internal algorithm), and this operation must be initiated in the platform or the customer must be notified of the error.

The full sequence and special aspects of the Verification of Payee process are provided below.

Information about the formats of requests and responses used during this process is presented further in this section.

Verification of Payee request format

There are several things you need to consider when sending Verification of Payee requests:

1. To initiate each verification, send a separate POST request to the /v2/verification-of-payee/create endpoint.
2. Each request must include the following objects and parameters:
   • Object general—general purchase information:
     • project_id—project identifier obtained from ecommpay during integration
     • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
   • Object payment—payment information:
     • currency—payment currency code in the ISO-4217 alpha-3 format
   • Object account—customer account information:
     • customer_name—full name or title of the account holder
     • number—account number

{
  "general": {
    "project_id": 12345,
    "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "currency": "EUR"
  },
  "account": {
    "customer_name": "John Doe",
    "number": "DOMESTIC_ACC_NUMBER_12345678"
  }
}

Verification of Payee initiation response format

A response to the Verification of Payee request is formatted according to the guidelines listed in Interaction concepts. Note that:

• If the verification was initiated, the following parameters are included in the vop object:
  • id—the verification identifier assigned on the provider side.
  • status—the intermediate verification status, the value is processing.
• If the verification was not initiated due to errors on the provider or platform side, the vop object is not included in the response.

{
  "status": "success",
  "request_id": "3213123",
  "project_id": 12345,
  "vop": {
    "id": 777888,
    "status": "processing"
  }
}

Request format for receiving verification information

There are several things you need to consider when sending verification information requests:

1. To request information on each verification, send a separate POST request to the /v2/verification-of-payee/result endpoint.
2. Each request must include the following objects and parameters:
   • Object general—general purchase information:
     • project_id—project identifier obtained from ecommpay during integration
     • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
   • Object vop—Verification of Payee information:
     • id—verification identifier obtained from ecommpay in the verification initiation response

{
  "general": {
    "project_id": 12345,
    "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJb=="
  },
  "vop": {
    "id": 777888
  }
}

Verification of Payee information response format

A response to the Verification of Payee information request is formatted according to the guidelines listed in Interaction concepts. Wherein, depending on the situation, the following parameters can be included in the vop object in such responses:

• id—identifier of the required verification
• status—a verification status indicator that can take one of the following values:
  • processing—if the final verification status is not received from the service provider
  • completed—if the final verification status is received from the service provider
  • decline—if verification is impossible due to errors in the interaction between the platform and the service provider
• result—the final verification status (details; not included in the response if the status parameter is processing)
• details—additional details to the final verification status from the service provider (not included in the response if the status parameter is processing or if the result parameter is VOP_ERROR)

In cases where the final status is VOP_ERROR, you are recommended to contact technical support specialists to clarify information about the verification and whether it can be performed.

{
  "general": {
    "project_id": 12345,
    "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
  },
  "vop": {
    "id": 777888,
    "status": "completed",
    "result": "CLOSE_MATCH",
    "details": "Reasons: CLOSE_MATCH; Details: The account details match.; Matched: name: John Doe, accountType: personal account"
  }
}