Introducción a Checkins

Las APIs de Checkins de Virtualpos permiten a los comercios gestionar garantías, prepagos y cobros posteriores asociados a una tarjeta registrada por el cliente, de forma flexible y segura. Son ideales para arriendo de vehículos, hotelería y cualquier servicio que requiera reservar un monto en garantía y cobrar el total al finalizar.

El modelo soporta distintos escenarios operativos:

• Registro de un check-in (garantía).
• Captura y tokenización de la tarjeta del cliente.
• Prepago, según la configuración del check-in.
• Garantía inmediata o diferida, según la configuración del check-in.
• Incremental: aumentar el monto de la garantía tomada.
• Checkout: cargo final sobre la garantía.
• Cancelación de la garantía, si aplica.
• Cargos adicionales posteriores al checkout (multas, daños, etc.).
• Nuevo check-in para un cliente y tarjeta ya registrados, sin volver a ingresar sus datos.

Autenticación y firma

Las llaves y headers son los mismos del resto de la API (ver Autenticación y firma): la API KEY va en el header Authorization y la firma en el header Signature.

En Checkins, la firma es un JWT HS256 firmado con tu SECRET KEY cuyo payload contiene la fecha de creación de la solicitud:

{ "ciat": 1767225600 }

ciat es el timestamp Unix (en segundos) del momento en que se genera la solicitud.

Ambientes

Ambiente	URL base API	Portal de comercio
Sandbox	https://api.virtualpos-sandbox.com	comercios.virtualpos-sandbox.com
Producción	https://api.virtualpos.cl	comercios.virtualpos.cl

Flujo de integración

1. Crear el check-in con POST /v3/checkins. La respuesta incluye el uuid del check-in y la hosted_url del formulario de captura de tarjeta.
2. Redirigir al cliente a la hosted_url. Ahí ingresa su tarjeta, que se tokeniza, y según la configuración se ejecuta la garantía (preautorización) y/o el prepago.
3. Notificación al comercio: Virtualpos envía un webhook a tu callback_url.
4. Retorno: el cliente es redirigido a tu return_url.
5. Consultar el estado con GET /v3/checkins/{uuid}.

Según la configuración del check-in, después puedes:

6. Ejecutar la garantía diferida con POST /v3/checkins/authorize.
7. Aumentar la garantía con POST /v3/checkins/incremental (opcional).
8. Cobrar un prepago con POST /v3/checkins/prepayment, si no se ejecutó antes (opcional).

Según la decisión del comercio, al finalizar el servicio:

9. Ejecutar el checkout con POST /v3/checkins/checkout, que captura el monto final total o parcialmente, o bien
10. Cancelar la garantía con DELETE /v3/checkins/{uuid}, que libera la preautorización.
11. Cargos adicionales posteriores al checkout con POST /v3/checkins/additional-charges.

Para un cliente que vuelve, puedes crear un check-in con su cliente y tarjeta existentes, con garantía inmediata y sin formulario.

Campos en Base64

callback_url y return_url deben enviarse codificadas en Base64. Por ejemplo, https://www.miempresa.cl/callback se envía como aHR0cHM6Ly93d3cubWllbXByZXNhLmNsL2NhbGxiYWNr.

Estados del Check-in

Estado	Descripción
pending	Check-in creado
abandoned	Check-in abandonado por el cliente
incomplete	Check-in sin movimientos durante un tiempo definido desde estado pending
card_captured	Tokenización exitosa
card_captured_failed	Tokenización fallida
authorized	Garantía autorizada
auth_rejected	Autorización de garantía rechazada
prepaid	Prepago ejecutado correctamente desde el formulario
prepayment_rejected	Prepago rechazado
captured	Checkout ejecutado
cancelled	Garantía liberada
expired	El check-in expiró porque no se ejecutó el checkout en el tiempo definido

Tipos de transacción

Al consultar un check-in, el arreglo transactions puede contener distintos tipos de transacción (transaction_type) según las operaciones realizadas durante su ciclo de vida:

transaction_type	Descripción
checkin	Garantía
sale	Prepago
incremental	Aumento del monto de la garantía
checkout	Cobro de la garantía
additional_charge	Cargo adicional posterior al checkout
release	Liberación de la garantía

Metadata

El campo metadata permite enviar información adicional relevante para tu negocio como pares clave-valor. Se devuelve en las consultas del check-in.

"metadata": {
  "marca": "Toyota",
  "modelo": "RAV4"
}

Colección Postman

Todas las operaciones de Checkins están disponibles, listas para ejecutar, en la colección VirtualPOS - Checkins del workspace público de Virtualpos en Postman.