Sign in

v1

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

Send verification payee request

Send a request to verify your payee's information.

post/payee_verification_requests

Headers

Idempotency-Keystring
Example:8A2gcC

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.

Request body

scheme'vop' required

The scheme on which the request will be sent. Only vop is supported today.

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 BIC11 you want to use to send your request. Must be one of the BIC11 configured in Numeral for your company.

initiated_atstring date-time

The UTC timestamp at which you started the verification request cycle. It is forwarded unchanged to the counterparty as the request timestamp. Must not be in the future and must be less than 5 seconds old.

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",
  "initiated_at": "2025-01-26T13:51:10Z",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  }
}

Response

Successfully created 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"
}