Source Holder Verification (SHV)

Source Holder Verification (SHV) is a feature that allows you to verify the ownership of a payment method (cards or bank accounts) by comparing the holder data provided in the operation with the real data associated with the payment method.

Verification can be performed using the holder's name or a legal identifier of the holder, depending on the selected method.

Verification methods

SHV allows you to verify the ownership of a source using one of the following methods:

NAME (default): verifies whether the provided holder name matches the real owner of the payment method.
IDENTIFICATION_NUMBER: verifies whether the provided legal identifier corresponds to the real owner of the payment method.

The method can be indicated using the verification_method field. If not specified, NAME is used.

Where can it be used?

SHV can be applied in three flows:

Dedicated verification endpoint
- Allows you to verify a source against a holder and obtain the verification result.
- Returns the match result: MATCH, NO_MATCH, PARTIAL_MATCH (when the verification is performed).
Store a payment method (tokenize card / create bank account)
- In the storage endpoint for cards or bank accounts, if the required fields are sent, SHV validates whether the source being stored belongs to the indicated holder.
- According to configured policies, the flow can be blocked and prevent the source from being stored.
Payment flow (payins and payouts)
- When creating a payment order, you can include the source_holder_verification body in extra_data.
- Before attempting the payment, SHV verification of the payment source is executed.
- This allows blocking the payment if:
  - the verification cannot be performed (according to policy), or
  - the result does not match (according to accepted_verification_results).

Dedicated endpoint: verify source holder

Request example with NAME

{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "source_uuid": "EEE99130-218B-4E22-90E2-E55B845DF0D4",
  "service": "E8952860-5441-45A2-9233-33651DABA250",
  "holder": {
    "first_name": "Luis",
    "last_name": "Pérez López"
  }
}

Request example with IDENTIFICATION_NUMBER

When verification_method is IDENTIFICATION_NUMBER, holder.identification_number must be sent. The first_name field is still required to perform the verification.

{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "source_uuid": "EEE99130-218B-4E22-90E2-E55B845DF0D4",
  "service": "E8952860-5441-45A2-9233-33651DABA250",
  "holder": {
    "first_name": "Luis",
    "last_name": "Pérez López",
    "identification_number": "B88353412"
  },
  "verification_method": "IDENTIFICATION_NUMBER"
}

Response example

{
  "message": "OK",
  "code": 200,
  "current_time": "2026-02-24T14:35:01+0100",
  "verification": {
    "uuid": "A8CABF0C-C690-46C7-9F4B-E6AC3F929799",
    "status": "PERFORMED",
    "match_result": "MATCH",
    "error": null,
    "policy_action": null,
    "verification_method": "NAME"
  }
}

Apply SHV in source storage or payment flows

In source storage and payment flows, the same body is used:

{
  "source_holder_verification": {
    "enabled": true,
    "accepted_verification_results": ["MATCH", "PARTIAL_MATCH"],
    "allow_unavailable": true,
    "allow_error": false,
    "first_name": "Pedro",
    "last_name": "Perez"
  }
}

What does this body do?

If enabled = true, SHV is attempted during the flow.
Allows defining policies:
- which results are acceptable (accepted_verification_results),
- what to do if verification is unavailable or is not performed (allow_unavailable),
- what to do in case of errors (allow_error).
Allows sending first_name and last_name. If not provided:
- In payments, they are obtained from extra_data.profile.
- In storage, they are obtained from card_holder / account_holder.
Allows selecting the verification method using verification_method.

For verification to be performed, the required data must be available in the operation:

The holder name (first_name) must be present, either sent in source_holder_verification or obtained from extra_data.profile.first_name.
If the selected method is IDENTIFICATION_NUMBER, the holder legal identifier (identification_number) must also be available, either sent explicitly or obtained from extra_data.profile.document_identification_number.

Usage examples

Tokenize card (storage)

{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "customer_ext_id": "test1",
  "card_holder": "TEST",
  "card_pan": "4242424242424242",
  "card_expiry_year": 34,
  "card_expiry_month": "12",
  "additional": null,
  "url_post": "",
  "validate": false,
  "service": "E8952860-5441-45A2-9233-33651DABA250",
  "card_cvv": 123,
  "source_holder_verification": {
    "enabled": true,
    "allow_unavailable": true,
    "allow_error": false,
    "first_name": "Pedro",
    "last_name": "Perez"
  }
}

Create bank account (storage)

{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "account_holder": "prueba",
  "iban": "ES4469400001180255458867",
  "customer_ext_id": "test",
  "service": "DD90CBFA-DB3E-4961-BB7A-4CC0CC129247",
  "source_holder_verification": {
    "enabled": true,
    "accepted_verification_results": ["MATCH", "PARTIAL_MATCH", "NO_MATCH"],
    "allow_unavailable": true,
    "allow_error": false,
    "first_name": "Pedro",
    "last_name": "Perez"
  }
}

Create order (payment flow)

In payments, source_holder_verification is sent inside extra_data.

{
  "signature": "341f7de8e6fc49da8d8736473af6b03a",
  "amount": 10,
  "operative": "PAYOUT",
  "secure": false,
  "customer_ext_id": "test",
  "service": "DD90CBFA-DB3E-4961-BB7A-4CC0CC129247",
  "description": "test",
  "additional": "Paylands test",
  "url_post": "https://enpxp0f8f1owh.x.pipedream.net/",
  "url_ok": "",
  "url_ko": "",
  "template_uuid": null,
  "dcc_template_uuid": null,
  "extra_data": {
    "profile": {
      "first_name": "Luis",
      "last_name": "test",
      "email": "victor.colejo@paynopain.com",
      "birthdate": "1996-04-04"
    },
    "source_holder_verification": {
      "enabled": true,
      "accepted_verification_results": ["MATCH", "PARTIAL_MATCH"],
      "allow_unavailable": true,
      "allow_error": false,
      "first_name": "Pedro",
      "last_name": "Perez"
    }
  }
}

`source_holder_verification` fields

Field	Type	Required	Default	Description
`enabled`	`boolean`	Yes	—	Enables payment source holder verification. When set to `true`, the platform performs an SHV check before continuing the flow (for example, before executing the payment).
`verification_method`	`string` (enum)	No	`NAME`	Method used to verify the ownership of the payment source. Allowed values: `NAME` or `IDENTIFICATION_NUMBER`. If set to `NAME`, verification is based on checking whether the provided holder name matches the real owner of the payment source. If set to `IDENTIFICATION_NUMBER`, verification is based on checking whether the provided legal identifier corresponds to the real owner of the payment source.
`accepted_verification_results`	`string[]` (enum)	No	—	List of verification results that are considered acceptable to continue the operation. If omitted or empty, the flow continues regardless of the SHV result. Allowed values: `MATCH`, `NO_MATCH`, `PARTIAL_MATCH`.
`allow_unavailable`	`boolean`	No	`true`	Allows the flow to continue if the verification has not been performed because it is not supported by the bank or by the card type/brand, or because the bank does not execute it even if supported.
`allow_error`	`boolean`	No	`false`	Determines the behavior when the verification cannot be completed due to transient failures/errors (e.g. timeout or temporary unavailability). When `true`, these errors do not block the flow. When `false`, these errors block the operation.
`first_name`	`string`	No	—	Holder's first name. If not provided: in payments it is retrieved from `extra_data.profile`; in storage operations, from `card_holder` / `account_holder`. This data must be available for the verification to be performed.
`last_name`	`string`	No	—	Holder's last name (same logic as `first_name`).
`identification_number`	`string`	Conditional	—	Legal identifier of the payment source holder (e.g. tax ID, national ID, passport or company registration number). Required when `verification_method` is `IDENTIFICATION_NUMBER`. If not provided, in payments it is retrieved from `extra_data.profile.document_identification_number`.

SHV response (common format)

{
  "source_holder_verification": {
    "uuid": "ED17EDE3-51A7-47A9-BD13-50448587278C",
    "status": "PERFORMED",
    "match_result": "NO_MATCH",
    "error": null,
    "policy_action": "ALLOWED",
    "verification_method": "NAME"
  }
}

Field meaning

uuid: unique identifier of the verification performed.
status: final verification attempt status.
match_result: match result (if applicable).
error: verification error if any.
policy_action: only applies to source creation and payment flows when source_holder_verification with policies is sent. Indicates the final decision taken on whether the flow continues.

`status` values

Possible values:

PERFORMED Verification could be performed. match_result is expected to be returned (MATCH, PARTIAL_MATCH or NO_MATCH).
NOT_PERFORMED Verification was not performed (for reasons not necessarily related to support).
NOT_SUPPORTED Verification is not supported for the bank / account type / brand or card type.
FAILED Failure during verification execution.
ERROR Transient or technical error (for example, timeout or temporary unavailability).

`match_result` values

An SHV check can return:

MATCH — The holder data matches completely with the real owner of the payment source.
PARTIAL_MATCH — Approximate match with minor discrepancies.
NO_MATCH — The holder data does not match the real owner.

`policy_action` values

Applies to source creation and payment flows when policies have been sent in source_holder_verification.

Possible values:

ALLOWED
BLOCKED_NOT_ACCEPTED_MATCH_RESULT
SKIPPED_UNAVAILABLE
SKIPPED_ERROR
BLOCKED_UNAVAILABLE
BLOCKED_ERROR
BLOCKED_UNEXPECTED_STATUS

Sandbox simulation (IBAN)

In sandbox environments, for bank accounts, match_result values can be simulated using these IBANs:

IBAN	Simulated result	Description
`ES8569400001160529041877`	rejected	Always simulates a rejected verification.
`ES6769400001110836662135`	failed (`NO_MATCH`)	Always simulates a `NO_MATCH` result.
`ES3369400001190536473836`	confirmed (`PARTIAL_MATCH`)	Always simulates an approximate match.
Any other IBAN	confirmed (`MATCH`)	Always simulates a full match.

Source Holder Verification (SHV)

Verification methods​

Where can it be used?​

Dedicated endpoint: verify source holder​

Request example with NAME​

Request example with IDENTIFICATION_NUMBER​

Response example​

Apply SHV in source storage or payment flows​

What does this body do?​

Usage examples​

Tokenize card (storage)​

Create bank account (storage)​

Create order (payment flow)​

source_holder_verification fields​

SHV response (common format)​

Field meaning​

status values​

match_result values​

policy_action values​

Sandbox simulation (IBAN)​