Проверка имён пользователей с помощью сервиса Verification of Payee

Алгоритмы

В рамках варианта с обработкой результатов проверки Verification of Payee на стороне платёжной платформы ecommpay допустимо выбрать и использовать один из следующих алгоритмов одобрения операций (с их последующим выполнением, когда статус проверки соответствует одному из одобренных).

• Алгоритм 1 основан на следующих правилах:
  • статус MATCH указывает на возможность выполнения соответствующей операции;
  • статусы CLOSE_MATCH, NO_MATCH, VERIFICATION_NOT_POSSIBLE и VOP_ERROR указывают на невозможность выполнения соответствующей операции.
• Алгоритм 2 основан на следующих правилах:
  • статусы MATCH и CLOSE_MATCH указывают на возможность выполнения соответствующей операции;
  • статусы NO_MATCH, VERIFICATION_NOT_POSSIBLE и VOP_ERROR указывают на невозможность выполнения соответствующей операции.
• Алгоритм 3 основан на следующих правилах:
  • статусы MATCH, CLOSE_MATCH и VERIFICATION_NOT_POSSIBLE указывают на возможность выполнения соответствующей операции;
  • статусы NO_MATCH и VOP_ERROR указывают на невозможность выполнения соответствующей операции.
• Алгоритм 4 основан на следующем правиле: все статусы, включая статус NO_MATCH и статусы с фиксацией невозможности проверки, указывают на возможность выполнения соответствующей операции.

Кратко эти правила можно представить в виде таблицы.

Контроль результатов

Информацию о результате проверки Verification of Payee для любой из операций, выполняемой в рамках варианта с обработкой результатов на стороне платёжной платформы ecommpay, можно получать через итоговое оповещение о выполнении этой операции. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье Работа с оповещениями. При этом информация об итоговом статусе проверки указывается в параметрах объекта provider_extra_fields, а в случаях с отклонением операций дополнительно можно ориентироваться на итоговые коды их состояния, среди которых могут быть коды, связанные с результатами проверки:

• 20450 — при отклонении операции из-за того, что проверку не удалось выполнить (для статуса VERIFICATION_NOT_POSSIBLE в алгоритмах 1–2 и статуса VOP_ERROR в алгоритмах 1–3);
• 20451 — при отклонении операции из-за того, что статус выполненной проверки не соответствует одобряемому (для статуса CLOSE_MATCH в алгоритме 1 и статуса NO_MATCH в алгоритмах 1–3).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 239 была проведена выплата в размере 10,00 EUR. В параметре vop_status объекта provider_extra_fields данных из этого оповещения указывается статус проверки CLOSE_MATCH.

{
        "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": "7eee810762d6493a807f30094414"
        },
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    }

В следующем примере оповещение свидетельствует о том, что выплата была отклонена в связи с полным несоответствием имён, о чём свидетельствует статус NO_MATCH.

{
        "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": "231221"
        },
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    }

Схема работы

В рамках варианта с обработкой результатов проверки Verification of Payee на стороне веб-сервиса необходимо организовать дополнительные взаимодействия между веб-сервисом и платформой для каждой операции с процедурой проверки. Это включает в себя ряд шагов между приёмом заявки от пользователя на получение средств и инициированием соответствующей операции в платформе:

1. Отправить запрос на проверку имени пользователя (с требуемыми параметрами и подписью) на рабочий URL ecommpay.
2. Принять от платёжной платформы синхронный ответ с информацией об инициировании проверки.
3. Спустя не менее чем 10 секунд отправить запрос на получение информации о результате проверки (с требуемыми параметрами и подписью) на рабочий URL ecommpay.
4. Принять от платёжной платформы синхронный ответ с информацией о статусе проверки.

После такого взаимодействия в каждом случае на стороне веб-сервиса необходимо принять решение о допустимости операции (в соответствии с реализованным внутренним алгоритмом) и инициировать эту операцию в платформе либо уведомить пользователя об ошибке.

Общая схема взаимодействий при проверке имени получателя средств в рамках выплаты или возврата выглядит следующим образом.

Информация о форматах данных, используемых для запросов и ответов в рамках такого взаимодействия, представлена далее в этом разделе.

Формат запроса на проверку имени пользователя

При формировании запросов на проверку имён пользователей необходимо учитывать следующее:

1. Для инициирования каждой проверки должен использоваться отдельный POST-запрос к конечной точке /v2/verification-of-payee/create.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;;
     • signature — подпись к запросу, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным); (подробнее);
   • payment — объект, содержащий сведения о платеже:
     • currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • account — объект, содержащий сведения о банковском счёте получателя средств:
     • customer_name — полное имя или наименование владельца счёта;
     • number — номер счёта.

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

Формат ответа об инициировании проверки

Для ответов о результатах инициирования проверки имён пользователей используется типовой формат, описание которого представлено в статье Организация взаимодействия. При этом:

• если проверка была инициирована, в объекте vop передаются следующие параметры:
  • id — идентификатор проверки, присвоенный на стороне провайдера;
  • status — промежуточный статус проверки со значением processing;
• если проверка не была инициирована из-за ошибок на стороне провайдера или платформы, объект vop не используется.

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

Формат запроса на получение информации о результате проверки

При формировании запросов на получение информации о результатах проверки имён пользователей необходимо учитывать следующее:

1. Для получения информации каждый раз должен использоваться отдельный POST-запрос к конечной точке /v2/verification-of-payee/result.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;;
     • signature — подпись к запросу, составленная после указания всех целевых параметров (подробнее — в статье Работа с подписью к данным); (подробнее);
   • vop — объект, содержащий сведения об искомой проверке:
     • id — идентификатор проверки, полученный от ecommpay в ответе о её инициировании.

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

Формат ответа о результате проверки

Для ответов о результатах проверки имён пользователей используется типовой формат, описание которого представлено в статье Организация взаимодействия. При этом, в зависимости от ситуации, в объекте vop в таких ответах могут передаваться следующие параметры:

• id — идентификатор искомой проверки;
• status — индикатор состояния проверки, который может принимать одно из следующих значений:
  • processing — при отсутствии итогового статуса проверки со стороны сервисного провайдера;
  • completed — при получении итогового статуса проверки со стороны сервисного провайдера;
  • decline — при невозможности выполнения проверки из-за ошибок при взаимодействии платформы и сервиса провайдера;
• result — итоговый статус проверки (подробнее; не включается в ответ, если в параметре status указано значение processing);
• details — пояснения к итоговому статусу проверки со стороны сервисного провайдера (не включаются в ответ, если в параметре status указано значение processing или если в параметре result указано значение VOP_ERROR).

В случаях с итоговым статусом VOP_ERROR рекомендуется обращаться к специалистам технической поддержки ecommpay для уточнения информации о проверке и возможности её выполнения.

{
  "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"
  }
}