Verificación del titular del medio de pago (SHV)

La Source Holder Verification (SHV) es una funcionalidad que permite verificar la titularidad de un medio de pago (tarjetas o cuentas bancarias), comparando los datos del titular aportados en la operación con la información real asociada al medio de pago.

¿En qué flujos se puede usar?

SHV puede aplicarse en tres flujos:

Endpoint específico de verificación
- Permite verificar un source frente a un titular y obtener el resultado de la verificación.
- Devuelve el resultado de coincidencia: MATCH, NO_MATCH, PARTIAL_MATCH (cuando la verificación se realiza).
Almacenar un medio de pago (tokenizar tarjeta / crear cuenta bancaria)
- En el endpoint de almacenamiento de tarjeta o cuenta bancaria, si se envían los campos requeridos, SHV valida si el source que se pretende almacenar pertenece al titular indicado.
- Según las políticas configuradas, el flujo puede bloquearse y evitar que el source se almacene.
Flujo de pago (payins y payouts)
- Al generar la orden de pago, se puede indicar en extra_data el cuerpo de source_holder_verification.
- Antes de intentar el pago, se ejecuta una verificación SHV del source con el que se pretende pagar.
- Permite bloquear el pago si:
  - la verificación no puede llevarse a cabo (según política), o
  - el resultado no coincide (según accepted_verification_results).

Endpoint específico: verificar titular de un source

Ejemplo de petición

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

Ejemplo de respuesta

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

Aplicar SHV en almacenamiento de source o en pagos

En los flujos de almacenamiento de source y pago, el cuerpo que se envía es el mismo:

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

¿Qué hace este cuerpo?

Si enabled = true, se intenta ejecutar SHV durante el flujo.
Permite definir políticas:
- qué resultados son aceptables (accepted_verification_results),
- qué hacer si la verificación no está disponible o no se realiza (allow_unavailable),
- qué hacer ante errores (allow_error).
Permite informar first_name y last_name. Si no se envían:
- En pagos, se intenta obtener de extra_data.profile.
- En almacenamiento, se intenta obtener de card_holder / account_holder.

Ejemplos de uso

Tokenizar tarjeta (almacenamiento)

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

Crear cuenta bancaria (almacenamiento)

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

Crear orden (flujo de pago)

En pagos, source_holder_verification se envía dentro de 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"
    }
  }
}

Campos de `source_holder_verification`

Campo	Tipo	Requerido	Default	Descripción
`enabled`	`boolean`	Sí	—	Activa la verificación del titular del medio de pago. Cuando se establece en `true`, la plataforma realiza una comprobación SHV antes de continuar con el flujo (por ejemplo, antes de ejecutar el pago).
`accepted_verification_results`	`string[]` (enum)	No	—	Lista de resultados de verificación que se consideran aceptables para continuar con la operación. Si se omite o está vacía, el flujo continúa independientemente del resultado SHV. Valores permitidos: `MATCH`, `NO_MATCH`, `PARTIAL_MATCH`.
`allow_unavailable`	`boolean`	No	`true`	Permite continuar con el flujo si la verificación no ha sido realizada porque no es soportada por el banco o por el tipo/marca de tarjeta, o porque aun pudiendo ser soportada el banco no la ejecuta.
`allow_error`	`boolean`	No	`false`	Determina el comportamiento cuando la comprobación no puede completarse debido a fallos/errores transitorios (p. ej. timeout o indisponibilidad temporal). Cuando es `true`, estos errores no bloquean el flujo. Cuando es `false`, estos errores bloquean la operación.
`first_name`	`string`	No	—	Nombre del titular usado para comparar. Si no se envía: en pagos se intenta obtener de `extra_data.profile`; en almacenamiento, de `card_holder` / `account_holder`.
`last_name`	`string`	No	—	Apellidos del titular usado para comparar (misma lógica que `first_name`).

Respuesta SHV (formato común)

Independientemente del endpoint/flujo, el bloque de respuesta de SHV se devuelve con esta forma:

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

Significado de los campos

uuid: identificador único de la verificación realizada.
status: estado final del intento de verificación.
match_result: resultado de coincidencia (si aplica).
error: el error que se haya podido producir durante la verificación.
policy_action: aplica solo a los flujos de creación de source y pago (cuando se envía source_holder_verification con políticas). Indica la decisión final tomada sobre la continuación del flujo.

Estados de `status`

Valores posibles:

PERFORMED La verificación se pudo realizar. Se espera que match_result venga informado (MATCH, PARTIAL_MATCH o NO_MATCH).
NOT_PERFORMED No se realizó la verificación (por motivos no necesariamente de soporte).
NOT_SUPPORTED La verificación no está soportada para el banco / tipo de cuenta / marca o tipo de tarjeta.
FAILED Fallo durante la ejecución de la verificación.
ERROR Error transitorio o técnico (por ejemplo, timeout o indisponibilidad temporal).

Resultados de coincidencia `match_result`

Una comprobación SHV puede devolver:

MATCH — El nombre del titular coincide completamente con el titular real del medio de pago.
PARTIAL_MATCH — Coincidencia aproximada con pequeñas discrepancias.
NO_MATCH — El nombre del titular no coincide con el titular real.

Acciones de política `policy_action`

Aplica en flujos de creación de source y pago cuando se han enviado políticas en source_holder_verification.

Valores posibles:

ALLOWED
BLOCKED_NOT_ACCEPTED_MATCH_RESULT
SKIPPED_UNAVAILABLE
SKIPPED_ERROR
BLOCKED_UNAVAILABLE
BLOCKED_ERROR
BLOCKED_UNEXPECTED_STATUS

Simulación en Sandbox (IBAN)

En entornos de sandbox, para cuentas bancarias, se pueden simular resultados de match_result usando estos IBAN:

IBAN	Resultado simulado	Descripción
`ES8569400001160529041877`	rechazado	Simula siempre una verificación rechazada.
`ES6769400001110836662135`	fallido (`NO_MATCH`)	Simula siempre un resultado `NO_MATCH`.
`ES3369400001190536473836`	confirmado (`PARTIAL_MATCH`)	Simula siempre una coincidencia aproximada.
Cualquier otro IBAN	confirmado (`MATCH`)	Simula siempre una coincidencia completa.

Verificación del titular del medio de pago (SHV)

¿En qué flujos se puede usar?​

Endpoint específico: verificar titular de un source​

Ejemplo de petición​

Ejemplo de respuesta​

Aplicar SHV en almacenamiento de source o en pagos​

¿Qué hace este cuerpo?​

Ejemplos de uso​

Tokenizar tarjeta (almacenamiento)​

Crear cuenta bancaria (almacenamiento)​

Crear orden (flujo de pago)​

Campos de source_holder_verification​

Respuesta SHV (formato común)​

Significado de los campos​

Estados de status​

Resultados de coincidencia match_result​

Acciones de política policy_action​

Simulación en Sandbox (IBAN)​