Sesiones de Tarjeta

El paso de tarjeta se solicita por sesión, con el objeto paymentCard en POST /v1/sessions. Todo lo demás de la solicitud — userRef, prefill, delivery, language — corresponde a la sesión de identidad, documentada en Sesiones de Verificación.

Crear una Sesión con el Paso de Tarjeta

Endpoint: POST /v1/sessions
Autenticación: token Bearer con el scope sessions — vea Autenticación

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "userRef": "user-123",
  "delivery": { "mode": "webhook" },
  "paymentCard": {
    "capture": true,
    "tokenize": {
      "storeLaterUse": true
    }
  }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ…",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

La respuesta es la misma que la de cualquier sesión. Entregue el widgetUrl de la forma habitual; el paso de tarjeta sigue a la selfie.

Para solo verificación, envíe capture por sí solo:

{ "userRef": "user-123", "paymentCard": { "capture": true } }

El Objeto `paymentCard`

Campo	Tipo	Requerido	Descripción
`capture`	boolean	No	`true` agrega el paso de tarjeta a esta sesión. Por defecto `false`
`tokenize`	object	No	Además tokeniza la tarjeta a través del tokenizador del gateway. Requiere `capture: true`. Envíe `{}` para los valores predeterminados

`tokenize`

Campo	Tipo	Requerido	Descripción
`storeLaterUse`	boolean	No	`false` (predeterminado) pide al gateway un token de uso único, `true` uno recurrente. El resultado lo informa como `kind`: `one_time` o `recurring`

La tarjeta se tokeniza sin 3D Secure, así que el titular nunca recibe un desafío en el widget. Autentique cuando cobre el token: vea Manejo de 3D Secure.

Cada objeto aquí rechaza un campo que no nombra, así que un storeLaterUse mal escrito es un 422 y no un token de uso único que usted no pidió.

Respuestas de Error

Todas devuelven 422 con errorCode: "validation_error", en el formato de problema con el que responde todo endpoint KYC de Inyo360. errors[].field nombra el campo:

{
  "type": "docs#/components/schemas/ProblemDetails",
  "title": "Unprocessable Entity",
  "status": 422,
  "errorCode": "validation_error",
  "errors": [
    {
      "field": "paymentCard.tokenize",
      "message": "paymentCard.tokenize is not enabled for this tenant",
      "type": "value_error"
    }
  ],
  "correlationId": "…",
  "instance": "/v1/sessions"
}

Causa	`field`	Qué hacer
El paso de tarjeta no está habilitado para su tenant	`paymentCard.capture`	Pida a su contacto en Inyo que lo habilite
Se envió `tokenize` y su tenant no tiene clave de tarjeta de pago	`paymentCard.tokenize`	El tokenizador necesita su clave pública del gateway en su tenant. Consulte a su contacto en Inyo
Se envió `tokenize` y la tokenización está desactivada para su tenant	`paymentCard.tokenize`	Consulte a su contacto en Inyo, o envíe `capture` por sí solo
Se envió `tokenize` sin `capture: true`	`paymentCard`	Establezca `capture: true`. Una tarjeta se tokeniza solo después de capturarse
Un campo que el objeto no nombra	El campo tal como se envió	Compare la ortografía con las tablas de arriba

Los rechazos que aplican a toda la sesión — modo webhook sin webhookUrl, problemas de prefill — están en Sesiones de Verificación.

Ajustes que Cambian Después de Enviar un Enlace

El paso de tarjeta y la tokenización se vuelven a leer cada vez que el widget lo pide, no solo cuando se crea la sesión.

Qué cambia para su tenant	Un enlace ya enviado
La tokenización se desactiva, o se elimina la clave de tarjeta de pago	El paso de tarjeta se sigue ejecutando, como solo verificación. No se solicita ningún token y no se entrega ningún bloque `paymentCard`
El paso de tarjeta se desactiva	La sesión termina solo con los pasos de identidad, sin filas de la tarjeta

Próximos Pasos

Flujo del Widget — qué ve el titular después de la selfie
Resultados de la Tarjeta — el bloque paymentCard en el resultado
Verificaciones de la Tarjeta — las filas de la tarjeta en checks