Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
payee-verification-requests

Simulate incoming payee verification request

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

post/payee_verification_requests/simulate

Request body

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_identificationstring 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_numberstring required

The account number of the payee. When scheme = vop, must be an IBAN.

payee_additional_informationstring

Additional information about the payee.

requesting_agent_bank_codestring

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_matchinteger

The matching score above which you want the matching result to be match.

min_score_close_matchinteger

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_codestring required

The BIC of the responding agent receiving the request in your simulation.

metadataCommonMetadata

Additional client data in JSON format. See Metadata.

Example request

{
  "scheme": "vop",
  "payee_identification_type": "name",
  "payee_identification": "John Doe",
  "payee_account_number": "FR5012739000308682265435N36",
  "payee_additional_information": "Account 123-ABC",
  "requesting_agent_bank_code": "BANKITPPXXX",
  "matching_algorithm": "levenshtein",
  "min_score_match": 90,
  "min_score_close_match": 75,
  "responding_agent_bank_code": "BANKITPPXXX",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  }
}

Response

Successfully simulated incoming payee verification request

idstring required

The ID of the payee verification request.

idempotency_keystring

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_detailsstring 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.

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_namestring nullable required

In case of matching_result = close_match, name suggested as correct by the responding agent.

response_received_atstring date-time nullable

The UTC timestamp of the reception of the response to the request. Only available for outgoing requests.

initiated_atstring 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.

metadataCommonMetadata

Additional client data in JSON format. See Metadata.

created_atstring date-time required

The UTC timestamp of the creation of the outgoing payee verification request.

Example response

{
  "id": "c39d1eff-c5ed-4197-8f24-28a68bd0eee6",
  "idempotency_key": "8A2gcC",
  "object": "payee_verification_request",
  "status": "completed",
  "status_details": "Some details about the status.",
  "failure_code": "business_error",
  "direction": "incoming",
  "scheme": "vop",
  "request": {
    "payee_identification_type": "name",
    "payee_identification": "John Doe",
    "sent_identification": "John Doe",
    "payee_account_number": "FR5012739000308682265435N36",
    "additional_information": "Account 123-ABC",
    "requesting_agent_bank_code": "SOMEBICXXX",
    "responding_agent_bank_code": "BANKITPPXXX"
  },
  "matching_result": "match",
  "matching_details": {
    "cleaned_identification": "John Doe",
    "retrieved_identification": "John Doe",
    "retrieved_identifications": [
      "John Doe",
      "J. Doe",
      "John M. Doe"
    ],
    "internal_account_id": "c39d1eff-c5ed-4197-8f24-28a68bd0eee6",
    "matching_score": 100,
    "distance": "levenshtein",
    "match_threshold": 90,
    "close_match_threshold": 75
  },
  "scheme_data": {
    "scheme_request_id": "c3d79e5a-2058-4301-8b36-353cb9eb0ca5",
    "request_timestamp": "2025-01-26T13:51:10Z",
    "response_timestamp": "2025-01-26T13:51:15Z"
  },
  "response_received_at": "2025-01-26T13:51:15Z",
  "initiated_at": "2025-01-26T13:51:10Z",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  },
  "created_at": "2025-01-01T12:00:00Z"
}