Skip to main content

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.

Where can it be used?​

SHV can be applied in three flows:

  1. 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).
  2. 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.
  3. 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​

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

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

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 (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, from card_holder / account_holder.

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 method holder verification. When set to true, the platform performs SHV before continuing the flow.

accepted_verification_results string[] No --- List of acceptable (enum) verification results 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 verification was not performed because it is not supported by the bank or card brand/type, or because the bank did not execute it.

allow_error boolean No false Determines behavior when verification cannot be completed due to transient failures (timeouts, temporary unavailability). If true, errors do not block the flow. If false, they block the operation.

first_name string No --- Holder name used for matching. If not sent: payments → extra_data.profile; storage → card_holder / account_holder.

last_name string No --- Holder last name used for matching.

SHV response (common format)​

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

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 policies are provided. Indicates the final decision taken.

Status values​

  • PERFORMED
  • NOT_PERFORMED
  • NOT_SUPPORTED
  • FAILED
  • ERROR

Match results​

  • MATCH
  • PARTIAL_MATCH
  • NO_MATCH

Policy actions​

  • ALLOWED
  • BLOCKED_NOT_ACCEPTED_MATCH_RESULT
  • SKIPPED_UNAVAILABLE
  • SKIPPED_ERROR
  • BLOCKED_UNAVAILABLE
  • BLOCKED_ERROR
  • BLOCKED_UNEXPECTED_STATUS

Sandbox IBAN simulation​

IBAN Simulated result Description

ES8569400001160529041877 rejected Always simulates a rejected verification.

ES6769400001110836662135 NO_MATCH Always simulates a NO_MATCH result.

ES3369400001190536473836 PARTIAL_MATCH Always simulates a partial match.

Any other IBAN MATCH Always simulates a full match.