---
title: "Simulate incoming payee verification request"
method: POST
path: "/payee_verification_requests/simulate"
tags: ["payee-verification-requests"]
---

# Simulate incoming payee verification request

`POST /payee_verification_requests/simulate`

Simulate an incoming payee verification request for testing and development purposes.

## Request body

- VopRequestSimulateIncomingCreationDetails — Details required to simulate an incoming payee verification request.
  - `scheme` 'vop', required — The scheme of the request you want to simulate. Only `vop` is supported.
  - `payee_identification_type` 'name' | 'inac' | 'legal_entity_identifier' | 'business_identification_code' | 'bank_identification' | 'central_bank_identification' | 'clearing_house_identification' | 'company_incorporation_number' | 'company_identification' | 'customer_number' | 'duns_number' | 'employee_number' | 'global_location_number' | 'siren' | 'siret' | 'tax_number' | 'business_domain_identification' | 'other_identification' | 'proprietary_code', required — The type of identification used in the request. See Supported identification type for more information.
  - `payee_identification` string, required — The identification of the payee. For example, if `payee_identification_type = name`, then you should fill the name of the payee here.
  - `payee_account_number` string, required — The account number of the payee. When `scheme = vop`, must be an IBAN.
  - `payee_additional_information` string — Additional information about the payee.
  - `requesting_agent_bank_code` string — The BIC of the requesting agent sending the request in your simulation.
  - `matching_algorithm` 'levenshtein' | 'jaro-winkler' — The matching algorithm you want to use to respond to this request. Supported values are `levenshtein` and `jaro-winkler`.
  - `min_score_match` integer — The matching score above which you want the matching result to be `match`.
  - `min_score_close_match` integer — The matching score below which you want the matching result to be `close_match`. When matching score is between `min_score_match` and `min_score_close_match`, matching result will be `close_match`.
  - `responding_agent_bank_code` string, required — The BIC of the responding agent receiving the request in your simulation.
  - `metadata` CommonMetadata — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).

## Response `200`

Successfully simulated incoming payee verification request

- VopRequestDetails — Details of a payee verification request.
  - `id` string, required — The ID of the payee verification request.
  - `idempotency_key` string — An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.
  - `object` 'payee_verification_request', required — Label used to identify this kind of object.
  - `status` 'created' | 'received' | 'completed' | 'failed', required — The status of the payee verification request. See Payee verification request lifecycle for more details.
  - `status_details` string, required — More information about the payee verification request status.
  - `failure_code` 'business_error' | 'technical_error' | 'psp_technical_error', nullable — A code explaining why the request failed.
  - `direction` 'outgoing' | 'incoming', required — The direction of the request. Can be outgoing or incoming.
  - `scheme` 'vop', required — The scheme the request was sent on. Only `vop` is supported today.
  - `request` object, required — An object containing key information about the request.
    - `payee_identification_type` string — The type of identification used in the request.
    - `payee_identification` string — The identification of the payee.
    - `sent_identification` string, nullable — The identification actually sent on the scheme, after any cleaning or transformation applied to `payee_identification`. Only available for outgoing requests.
    - `payee_account_number` string — The account number of the payee.
    - `additional_information` string — Additional information about the payee.
    - `requesting_agent_bank_code` string — The agent which sent the request.
    - `responding_agent_bank_code` string — The agent at which the request is aimed, i.e. the agent of the payee.
  - `matching_result` 'match' | 'close_match' | 'no_match' | 'impossible_match', required — The result of the verification. Can be `match`, `close_match`, `no_match` or `impossible_match`. Note that `close_match` is only possible when `payee_identification_type = name`.
  - `payee_suggested_name` string, nullable, required — In case of `matching_result = close_match`, name suggested as correct by the responding agent.
  - `matching_details` object, nullable, required — Details of the request processing in case `direction = incoming`.
    - `cleaned_identification` string — Payee identification after data cleaning (removing double spaces, honorific titles, etc.)
    - `retrieved_identification` string, nullable — Payee identification retrieved in your account database (in Numeral or in your systems), using `payee_account_number` as a search key. For name matching: set to the best matching name when `matching_result` is `match` or `close_match`, null when `matching_result` is `no_match`. For other identification types (LEI, BIC, etc.): set to the retrieved value.
    - `retrieved_identifications` string[], nullable — All holder names retrieved from your account database that were evaluated during the matching process. Only populated for `payee_identification_type = name`. Null for other identification types.
    - `internal_account_id` string — If your account database is held in Numeral using internal accounts, the ID of the internal account matching `payee_account_number`.
    - `matching_score` integer — The score, from 0 to 100, of the matching algorithm configured for your entity when run with `cleaned_identification` and `retrieved_identification`.
    - `distance` 'levenshtein' | 'jarowinkler', nullable — The name of the matching algorithm used to compute the matching score.
    - `match_threshold` integer, nullable — The minimum score threshold configured for a result to be considered a `match`.
    - `close_match_threshold` integer, nullable — The minimum score threshold configured for a result to be considered a `close_match`.
  - `scheme_data` object, nullable, required — An object containing technical information about the request.
    - `scheme_request_id` string — The unique ID of the request on the scheme. Different from `id`.
    - `request_timestamp` string, date-time — The timestamp of the creation of the request.
    - `response_timestamp` string, date-time — The timestamp of the answer to the request.
  - `response_received_at` string, date-time, nullable — The UTC timestamp of the reception of the response to the request. Only available for outgoing requests.
  - `initiated_at` string, date-time, nullable — The UTC timestamp at which you started the verification request cycle, as provided on creation. Only available for outgoing requests where it was provided.
  - `metadata` CommonMetadata — Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata).
  - `created_at` string, date-time, required — The UTC timestamp of the creation of the outgoing payee verification request.

## Other responses

- `400` — Validation error.
- `500` — Internal server error.

---

[API](https://skmtc.net/numeral/apis/payments.md) · [All operations](https://skmtc.net/numeral/apis/payments/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/numeral/payments/versions/220f101cc2ef/schema)