Crear un Check-in

Permite crear un nuevo check-in asociado a un cliente y definir las condiciones de pago, garantía y fechas del servicio.

Al crear el check-in, VirtualPOS genera un identificador único y una URL de formulario para que el cliente pueda registrar su tarjeta de forma segura. Según la configuración enviada, el flujo podrá considerar sólo garantía, prepago más garantía, garantía inmediata o garantía diferida.

Este endpoint no ejecuta necesariamente un cobro al momento de la creación. La captura de tarjeta, el prepago y/o la preautorización de garantía se ejecutan posteriormente según el escenario configurado y la interacción del cliente con el formulario.

POST /v3/checkins

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

Headers

Nombre	Requerido	Descripción
Content-Type	Sí	application/json
Authorization	Sí	API KEY del comercio
Signature	Sí	JWT HS256 firmado con la SECRET KEY, payload {"ciat": <timestamp>}. Ver firma de Checkins.

Body

Campo	Obligatorio	Regla	Observación
currency	Sí	Moneda de la transacción	Por defecto CLP. USD no soportado
description	Sí	Descripción del check-in	Ej: arriendo, habitación
merchant_internal_code	Sí	Identificador único del comercio	Reutilizable si no hubo check-in exitoso previo
date_checkin_commerce	Sí	Fecha inicio informada por el comercio	Formato YYYY-MM-DD
date_checkout_commerce	Sí	Fecha término informada por el comercio	Formato YYYY-MM-DD
client	Sí	Datos del cliente	Objeto obligatorio
client.first_name	Sí	Nombre del cliente
client.last_name	Sí	Apellido del cliente
client.phone	No	Teléfono del cliente
client.email	Sí	Email del cliente
client.social_id_type	Sí	Tipo de documento	RUT, DNI, PASSPORT
client.social_id	Sí	Identificación del cliente
client.type	Sí	Tipo de cliente	PERSONA, EMPRESA
payment_plan	Sí	Plan de pago del check-in	Debe contener garantía
payment_plan.guarantee	Sí	Definición de garantía	Objeto obligatorio
payment_plan.guarantee.timing	Sí	Momento de ejecución	immediate o deferred
payment_plan.guarantee.amount	Sí	Monto de garantía	Mayor a 0, entero, sin decimales
payment_plan.prepayment	Sí	Definición de prepago	Objeto obligatorio
payment_plan.prepayment.amount	Sí	Monto de prepago	Si no aplica, debe enviarse en 0, entero, sin decimales
callback_url	Sí	URL de callback	Debe enviarse en Base64
return_url	Sí	URL de retorno	Debe enviarse en Base64
metadata	No	Información adicional	JSON clave-valor

Ejemplo de request

curl -X POST 'https://api.virtualpos-sandbox.com/v3/checkins' \
  -H 'Content-Type: application/json' \
  -H "Authorization: $API_KEY" \
  -H "Signature: $SIGNATURE" \
  -d '{
  "currency": "CLP",
  "description": "Rent a car",
  "merchant_internal_code": "Reserva PruebaAgosto",
  "date_checkin_commerce": "2026-09-30",
  "date_checkout_commerce": "2026-10-15",
  "client": {
    "first_name": "Cliente",
    "last_name": "Ejemplo",
    "phone": "5698987659",
    "email": "cliente@ejemplo.cl",
    "social_id_type": "RUT",
    "social_id": "11111111-1",
    "type": "PERSONA"
  },
  "payment_plan": {
    "guarantee": {
      "timing": "immediate",
      "amount": 112000
    },
    "prepayment": {
      "amount": 0
    }
  },
  "callback_url": "aHR0cHM6Ly9zZXJ2aWNlcy52aXJ0dWFscG9zLWRldi5jb20vbGlzdGVuZXItYXN5bmMtY29uZmlybWF0aW9u",
  "return_url": "aHR0cHM6Ly9odHRwYmluLm9yZy9wb3N0",
  "metadata": {
    "Marca": "Toyota",
    "Modelo": "RAW4 Red"
  }
}'

Respuestas

200 OK

{
  "status": "OK",
  "code": 200,
  "checkin": {
    "commerce": {
      "commerce_id": "76478111-2",
      "name": "Virtualpos"
    },
    "client": {
      "uuid_cli": "cli_0316aaaaaaaaaaaa",
      "email": "cliente@ejemplo.cl",
      "first_name": "Cliente",
      "last_name": "Ejemplo",
      "social_id_type": "RUT",
      "social_id": "11111111-1",
      "phone": "564444444",
      "type": "PERSONA"
    },
    "uuid": "chk_beb71934-4b53-46e4-834d-0548b3936414",
    "status": "pending",
    "currency": "CLP",
    "description": "rent car",
    "merchant_internal_code": "RentCard-Agosto",
    "guarantee_amount": 235001,
    "timing_guarantee": "immediate",
    "prepayment_amount": 0,
    "date_checkin_commerce": "2026-09-21",
    "date_checkout_commerce": "2026-09-30",
    "created_at": "2026-08-10 15:11:08",
    "metadata": {
      "Marca": "Toyota",
      "Modelo": "RAW4 Black"
    },
    "callback_url": "aHR0cHM6Ly9zZXJ2aWNlcy52aXJ0dWFscG9zLWRldi5jb20vbGlzdGVuZXItYXN5bmMtY29uZmlybWF0aW9u",
    "return_url": "aHR0cHM6Ly9odHRwYmluLm9yZy9wb3N0",
    "hosted_url": "https://checkin-checkout.virtualpos-dev.com/form/chk_beb71934-4b53-46e4-834d-0548b3936414"
  }
}

400 Bad Request

{
  "status": "NOK",
  "code": 400,
  "error": {
    "error_code": "E-086",
    "message": "Solicitud rechazada merchant_internal_code ya utilizado.",
    "doc_url": "https://virtualpos.readme.io/reference/objeto-error"
  }
}