Saltar al contenido principal

Actualizar CVV

Envía un nuevo valor de verificación de tarjeta para una tarjeta guardada que pertenece al usuario autenticado.

Dominio
Cards and vault
Servicio responsable
Payments
Dirigido a
Aplicación del cliente · usuario a servidor
Autorización compatible
Token Bearer del usuario autenticado

Encabezados#

2
AuthorizationstringObligatorio
Aceptado o reenviado por el API Gateway para esta operación.
X-Merchant-IDstringOpcional
Aceptado o reenviado por el API Gateway para esta operación.

Parámetros de ruta#

2
user_idstring<uuid>Obligatorio
Valor que sustituye a `user_id` en la ruta del endpoint.
card_idstring<uuid>Obligatorio
Valor que sustituye a `card_id` en la ruta del endpoint.

Cuerpo de la solicitud#

1
card_cvvstringObligatorio
Payload JSON aceptado por el servicio responsable. Usa el panel de solicitud para editarlo y previsualizarlo.
Ejemplo 123

Respuesta#

7
204La solicitud se aceptó o completó. Revisa el payload para conocer el resultado de negocio.
400La solicitud no es válida o no supera la validación.
401Las credenciales o el contexto del llamador no son válidos.
403Las credenciales o el contexto del llamador no son válidos.
404No se encontró el recurso o la ruta solicitada.
422La solicitud no es válida o no supera la validación.
500El servicio no pudo completar la solicitud. Reintenta solo cuando la operación sea segura o idempotente.

Antes de actualizar el CVV#

  • Autentica al cliente y envía su token de acceso de usuario en el encabezado Authorization.
  • Establece el ID de usuario de la ruta con el UUID del cliente autenticado y usa un ID de tarjeta devuelto por Enumerar tarjetas almacenadas.
  • Solicita al cliente el valor de verificación de tarjeta (CVV) de la tarjeta guardada. La tarjeta debe pertenecer a ese cliente y tener una fecha de vencimiento válida.

Envía la solicitud de actualización#

Usa la URL base de sandbox que se muestra a continuación para las pruebas y https://api.deuna.io para producción. Envía un objeto JSON con la cadena obligatoria card_cvv que contiene el CVV de tres o cuatro dígitos. No hay parámetros de consulta. Esta operación actualiza una tarjeta existente; no crea una tarjeta ni realiza un cargo al cliente.

curl --request POST \
  --url 'https://api.sandbox.deuna.io/users/USER_ID/cards/CARD_ID/refresh-cvv' \
  --header 'Authorization: Bearer USER_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"card_cvv":"123"}'

Verifica el resultado#

Una solicitud exitosa devuelve HTTP 204 No Content con un cuerpo vacío. No lo analices como JSON. La respuesta confirma que se completó la actualización del CVV; no confirma un pago ni expone el CVV en una respuesta de tarjeta. No se necesita un webhook de pago para confirmar esta operación.

Continúa con tu solicitud de pago cuando el cliente esté listo para pagar.

Gestiona errores y reintentos#

HTTP 400 indica identificadores inválidos, JSON mal formado o un CVV ausente o inválido. HTTP 401 indica una autorización de usuario inválida. HTTP 404 significa que no se encontró la tarjeta guardada para el usuario autenticado. HTTP 422 indica una tarjeta vencida, datos de vencimiento inválidos o una tarjeta cuyo CVV no puede actualizarse. Corrige los datos o selecciona otra tarjeta antes de reintentar.

Si un tiempo de espera agotado o un error del servidor deja el resultado incierto, no reenvíes el CVV automáticamente. No se define un contrato de clave de idempotencia para esta operación. Permite que el cliente reintente dentro del flujo activo y solicita el CVV de nuevo cuando sea necesario. Consulta códigos de respuesta y resolución de problemas.