Reserva de cupo

---

• Reserva de cupo
  • Overview
  • Elige tu integración
  • Estados de una reserva
• 1. Crear la reserva
  • Parámetros
  • Respuesta modalidad redirect
  • Respuesta modalidad api
• 2. Autorizar con tarjeta (solo modalidad api)
  • Parámetros de la tarjeta
  • Autenticación 3DS opcional
  • Ejemplo y respuesta
• 3. Cobro final
• 4. Liberar la reserva
• Consultar y sincronizar
• Webhooks
• Códigos de error
• Límites y notas

Overview

Una reserva de cupo retiene fondos en la tarjeta de tu cliente sin cobrarlos todavía. Después decides cuánto cobrar de verdad —hasta el valor reservado— o liberas la retención para que el cliente recupere su cupo.

Sirve cuando no conoces el valor final en el momento de la compra:

Caso	Reservas	Cobras
Hotel	El valor de la estadía más un margen por consumos	Al hacer el check-out, con el consumo real
Rent a car	El alquiler más el depósito de garantía	Al devolver el vehículo, descontando lo que aplique
Delivery por peso o por consumo	Un estimado del pedido	Con el valor pesado o consumido
Suscripción con periodo de prueba	El valor del plan	Cuando termina la prueba y el cliente sigue

El ciclo son tres momentos:

   1. Crear la reserva  ─────►  2. El cliente autoriza  ─────►  3a. Cobro final
                                   (retención activa)           3b. Liberar la reserva

Nota

En la jerga de las redes de pago esto se llama MIT (Merchant Initiated Transaction) o pre-autorización. En esta documentación usamos «reserva de cupo», «cobro final» y «liberar la reserva».

Una reserva es una transacción de tu comercio. Aparece en tu reporte de transacciones desde que el cliente la autoriza, con el estado Autorizada. No se abona a tu cuenta virtual mientras esté solo reservada: el abono ocurre cuando aplicas el cobro final, y por el valor cobrado, no por el reservado.

Elige tu integración

Igual que en el resto de nuestra API, tienes dos modalidades. La eliges con el campo checkout_type al crear la reserva.

	redirect (por defecto)	api
Quién captura la tarjeta	Nosotros, en el checkout de Efipay	Tú, en tu propio checkout
Qué recibes al crear	checkout_url	token
Peticiones para autorizar	1 (creas y rediriges)	2 (creas y autorizas)
Requiere certificación PCI DSS	No	Sí
3DS	Lo gestionamos nosotros	Lo gestionas tú y nos envías el resultado
Llave de API	Prueba o producción	Solo producción

Flujo redirect:

POST /v1/mit/pre-authorizations          →  { checkout_url, id }
rediriges al cliente a checkout_url      →  el cliente ingresa su tarjeta
webhook mit.pre_authorized               →  el cupo quedó reservado
POST /v1/mit/pre-authorizations/{id}/confirm  ó  /void

Flujo api:

POST /v1/mit/pre-authorizations                    →  { id, token }
POST /v1/mit/pre-authorizations/{id}/authorize     →  el cupo quedó reservado
POST /v1/mit/pre-authorizations/{id}/confirm  ó  /void

Precaución

La modalidad api recibe el número de tarjeta y el CVV en tu servidor. Solo úsala si tu plataforma está certificada en PCI DSS. Si no lo está, usa redirect: es igual de completa y el dato sensible nunca pasa por tu sistema.

Estados de una reserva

status	Etiqueta	Qué significa
Iniciada	Esperando al cliente	La reserva existe pero el cliente aún no autorizó
Pre-autorizada	Cupo reservado	Hay fondos retenidos. Puedes cobrar o liberar
Confirmada	Cobrada	El cobro final se aplicó. El dinero entra a tu cuenta virtual
Anulada	Reserva liberada	El cliente recuperó su cupo. No hubo cobro
Vencida	Reserva vencida	Pasó la vigencia sin cobro. El cupo se libera solo
Rechazada	Rechazada	La red no aprobó la reserva
Fallida	Fallida	No se pudo procesar
Indeterminada	Verificando	No recibimos respuesta de la red. No reintentes: estamos verificando si el cupo quedó reservado

Puedes consultar este catálogo en GET /api/v1/resources/mit/status-enum.

---

1. Crear la reserva

POST /api/v1/mit/pre-authorizations

Parámetros

Nombre del campo	Descripción	Reglas
description	Qué se está reservando. El cliente lo ve en el checkout y tú en tu reporte	['required', 'string', 'max:255']
estimated_amount	Valor a reservar. Es el techo del cobro final: no podrás cobrar más que esto	['required', 'numeric', 'gt:0', 'max:99999999.99']
checkout_type	redirect (por defecto) o api. Ver enumeraciones	['nullable', 'string', 'in:redirect,api']
tax	IVA incluido dentro de estimated_amount. Debe ser menor a estimated_amount	['nullable', 'numeric', 'min:0']
references	Hasta 5 referencias para identificar la reserva en tus sistemas	['nullable', 'array', 'max:5']
references.*.referenceKey	Nombre de la referencia. Solo letras, números y espacios	['required_with:references', 'string', 'regex:/^[\pL\pN ]+$/u', 'max:64']
references.*.referenceDescription	Valor de la referencia. Solo letras, números y espacios	['required_with:references', 'string', 'regex:/^[\pL\pN ]+$/u', 'max:22']
customer	Datos del cliente, para prellenar el checkout	['nullable', 'array']
customer.name	Nombre del cliente	['nullable', 'string', 'max:255']
customer.email	Correo del cliente	['nullable', 'email', 'max:255']
webhook_url	URL a la que notificaremos los cambios de estado de esta reserva. Si no la envías usamos la de tus opciones avanzadas	['nullable', 'url', 'max:255']
redirect_url	A dónde vuelve el cliente después del checkout (modalidad redirect)	['nullable', 'url', 'max:255']
checkout_template_id	ID de tu plantilla de checkout	['nullable', 'integer', 'exists:checkout_templates,id']

Peligro

Este endpoint no recibe datos de tarjeta. Si envías number, cvv, card_token o similares la petición se rechaza con un 422 explicando por qué. En redirect los ingresa el cliente; en api van en el paso 2.

Respuesta modalidad redirect

POSThttps://sag.efipay.co/api/v1/mit/pre-authorizations

Token de accesoCuerpo de la petición{ "description": "Reserva habitación 402 - 3 noches", "estimated_amount": 850000, "checkout_type": "redirect", "references": [ { "referenceKey": "Reserva", "referenceDescription": "HAB402" } ], "customer": { "name": "Ana Gomez", "email": "ana@ejemplo.com" }, "webhook_url": "https://mi-hotel.com/webhooks/efipay" }

ProbarCopiar como cURL

curl -X POST \
'/api/v1/mit/pre-authorizations' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "description": "Reserva habitación 402 - 3 noches",
    "estimated_amount": 850000,
    "checkout_type": "redirect",
    "references": [
        { "referenceKey": "Reserva", "referenceDescription": "HAB402" }
    ],
    "customer": {
        "name": "Ana Gomez",
        "email": "ana@ejemplo.com"
    },
    "webhook_url": "https://mi-hotel.com/webhooks/efipay"
}'

Respuesta 201:

{
    "success": true,
    "pre_authorization": {
        "id": "019fba4a-5a7f-73df-b9a5-ec0ca585fd60",
        "status": "pendiente_autorizacion",
        "checkout_type": "redirect",
        "description": "Reserva habitación 402 - 3 noches",
        "estimated_amount": 850000,
        "currency": "COP",
        "references": [
            { "referenceKey": "Reserva", "referenceDescription": "HAB402" }
        ],
        "expires_at": null,
        "checkout_url": "https://sag.efipay.co/Checkout/019fba4a-5a7f-73df-b9a5-ec0ca585fd60"
    }
}

Redirige al cliente a checkout_url. Cuando autorice te llegará el webhook mit.pre_authorized con la reserva ya vigente.

Respuesta modalidad api

Idéntica, pero cambia checkout_url por token:

{
    "success": true,
    "pre_authorization": {
        "id": "019fba4a-5a7f-73df-b9a5-ec0ca585fd60",
        "status": "pendiente_autorizacion",
        "checkout_type": "api",
        "description": "Reserva habitación 402 - 3 noches",
        "estimated_amount": 850000,
        "currency": "COP",
        "references": [
            { "referenceKey": "Reserva", "referenceDescription": "HAB402" }
        ],
        "expires_at": null,
        "token": "dASpVjbG0AJter1"
    }
}

Precaución

El token se devuelve una sola vez: en nuestra base solo queda su hash. Guárdalo junto al id, porque los dos juntos autentican el paso 2. Si lo pierdes, crea una reserva nueva.

---

2. Autorizar con tarjeta (solo modalidad api)

POST /api/v1/mit/pre-authorizations/{id}/authorize

Este es el paso que retiene los fondos. El par id + token del paso 1 autentica la operación: el id va en la URL y el token en el cuerpo.

Parámetros de la tarjeta

Nombre del campo	Descripción	Reglas
payment	Objeto con el token de la reserva	['required', 'array']
payment.token	El token que te devolvió el paso 1	['required', 'string']
customer_payer	Datos de quien paga	['required', 'array']
customer_payer.name	Nombre de quien paga	['required', 'string', 'min:5', 'max:255']
customer_payer.email	Correo de quien paga. Solo caracteres alfanuméricos	['required', 'email']
customer_payer.address_1	Dirección principal	['required', 'string', 'min:5', 'max:100']
customer_payer.address_2	Dirección secundaria	['nullable', 'string', 'min:1', 'max:100']
customer_payer.city	Ciudad	['required', 'string', 'min:1', 'max:100']
customer_payer.state	Departamento o estado	['required', 'string', 'min:1', 'max:100']
customer_payer.country	País en ISO3. Ver lista de países	['required', 'string', 'in:COL,USA,MEX,...']
customer_payer.zip_code	Código postal	['required', 'numeric', 'digits_between:1,10']
customer_payer.dialling_code	Indicativo telefónico, con + (por ejemplo +57)	['required', 'regex:/^\+\d{1,3}$/i']
customer_payer.cellphone	Celular, solo dígitos	['required', 'numeric', 'digits_between:5,15']
customer_payer.identification_type	Tipo de documento. Ver enumeraciones	['nullable', 'in:CC,CE,TI,PPT,DNI,NIT,Pasaporte,Otro']
customer_payer.id_number	Número de documento. No puede ser un número de tarjeta	['nullable', 'digits_between:5,15']
payment_card	Datos de la tarjeta	['required', 'array']
payment_card.number	Número de la tarjeta, sin espacios	['required', 'numeric', 'digits_between:14,16']
payment_card.name	Nombre impreso en la tarjeta. Solo letras y espacios	['required', 'string']
payment_card.expiration_date	Vencimiento en formato YYYY-MM, con mes entre 01 y 12. No puede estar vencida	['required', 'date_format:Y-m', 'after_or_equal:<mes actual>']
payment_card.cvv	Obligatorio. Código de seguridad de 3 o 4 dígitos	['required', 'regex:/^\d{3,4}$/i']
payment_card.installments	Número de cuotas	['required', 'integer', 'between:1,60']
payment_card.redirect_url	A dónde volver si hay una autenticación intermedia	['nullable', 'url', 'max:500']
browser_information	Datos del navegador del comprador	['nullable', 'array']
browser_information.ipAddress	IP del comprador, para el antifraude	['nullable', 'ipv4']

Peligro

El CVV es obligatorio en una reserva de cupo: la red la rechaza sin él. Por eso no se aceptan tarjetas tokenizadas en este endpoint —un token no incluye CVV—. Si envías payment_card.token recibirás un 422 explicándolo. El soporte de tarjetas tokenizadas para reservas está en evaluación con la red.

Autenticación 3DS opcional

Si autenticaste al tarjetahabiente con 3D Secure por tu cuenta, envíanos el resultado en three_ds y lo reenviamos a la red. Cada franquicia usa campos distintos; enviar los de la otra hace que la reserva sea rechazada.

Nota

En las reglas verás nullable en todos: Laravel los acepta ausentes, pero después validamos la combinación según la franquicia de la tarjeta. La columna «Descripción» dice cuándo cada uno pasa a ser obligatorio.

Visa — la franquicia se detecta por el BIN. Los tres campos son obligatorios si envías three_ds:

Nombre del campo	Descripción	Reglas
three_ds.eci	Electronic Commerce Indicator. Obligatorio si envías three_ds con una tarjeta Visa	['nullable', 'string', 'size:2', 'in:05,06,07']
three_ds.cavv	Cardholder Authentication Verification Value. Obligatorio si envías three_ds con una tarjeta Visa	['nullable', 'string', 'max:28']
three_ds.xid	Identificador de la transacción 3DS. Obligatorio si envías three_ds con una tarjeta Visa	['nullable', 'string', 'max:28']

Mastercard — los cuatro campos son obligatorios si envías three_ds:

Nombre del campo	Descripción	Reglas
three_ds.directory_server_transaction_id	Id de la transacción en el directorio, de exactamente 36 caracteres. Obligatorio si envías three_ds con una tarjeta que no sea Visa	['nullable', 'string', 'size:36']
three_ds.ucaf_collection_indicator	Indicador UCAF. Obligatorio si envías three_ds con una tarjeta que no sea Visa	['nullable', 'string', 'in:0,1,2,4,6,7']
three_ds.ucaf_authentication_data	Dato de autenticación UCAF. Obligatorio si envías three_ds con una tarjeta que no sea Visa	['nullable', 'string', 'max:200']
three_ds.specification_version	Versión de la especificación, un solo carácter. Obligatorio si envías three_ds con una tarjeta que no sea Visa	['nullable', 'string', 'max:1']

Si no envías three_ds, la reserva se procesa sin autenticación 3DS.

Ejemplo y respuesta

POSThttps://sag.efipay.co/api/v1/mit/pre-authorizations/019fba4a-5a7f-73df-b9a5-ec0ca585fd60/authorize

Token de accesoCuerpo de la petición{ "payment": { "token": "dASpVjbG0AJter1" }, "customer_payer": { "name": "Ana Gomez Perez", "email": "ana@ejemplo.com", "address_1": "Calle 100 # 20-30", "city": "Bogota", "state": "Cundinamarca", "country": "COL", "zip_code": "110111", "dialling_code": "+57", "cellphone": "3001234567" }, "payment_card": { "number": "4916170011291313", "name": "Ana Gomez", "expiration_date": "2028-08", "cvv": "200", "installments": 1 } }

ProbarCopiar como cURL

curl -X POST \
'/api/v1/mit/pre-authorizations/019fba4a-5a7f-73df-b9a5-ec0ca585fd60/authorize' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "payment": { "token": "dASpVjbG0AJter1" },
    "customer_payer": {
        "name": "Ana Gomez Perez",
        "email": "ana@ejemplo.com",
        "address_1": "Calle 100 # 20-30",
        "city": "Bogota",
        "state": "Cundinamarca",
        "country": "COL",
        "zip_code": "110111",
        "dialling_code": "+57",
        "cellphone": "3001234567"
    },
    "payment_card": {
        "number": "4916170011291313",
        "name": "Ana Gomez",
        "expiration_date": "2028-08",
        "cvv": "200",
        "installments": 1
    },
    "three_ds": {
        "eci": "05",
        "cavv": "AAABCZIhcQAAAABZlyFxAAAAAAA=",
        "xid": "ODUzNTYzOTcwODU5NzQzMjE0NTY="
    }
}'

Respuesta 201 — cupo reservado:

{
    "success": true,
    "pre_authorization": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "operation": "pre_authorization",
        "status": "Pre-autorizada",
        "status_label": "Cupo reservado",
        "estimated_amount": 850000,
        "authorized_amount": 850000,
        "max_confirmable_amount": 850000,
        "currency": "COP",
        "installments": 1,
        "card": {
            "franchise": "visa",
            "bin": "491617",
            "last_four": "1313"
        },
        "references": [
            { "referenceKey": "Reserva", "referenceDescription": "HAB402" }
        ],
        "network_transaction_id": 320000303129,
        "authorization_code": "005077",
        "response_code": "00",
        "expires_at": "2026-08-07T10:15:00-05:00",
        "confirmable_until": "2026-08-07T10:15:00-05:00",
        "voidable_until": "2026-08-06T10:15:00-05:00",
        "can_confirm": true,
        "can_void": true,
        "blocked_reason": null,
        "checkout_url": null,
        "authorized_at": "2026-07-31T10:15:00-05:00",
        "confirmed_at": null,
        "voided_at": null,
        "created_at": "2026-07-31T10:15:00-05:00",
        "error": null
    }
}

Respuesta 422 — la red rechazó la reserva:

{
    "success": false,
    "pre_authorization": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "status": "Rechazada",
        "status_label": "Rechazada",
        "response_code": "51",
        "can_confirm": false,
        "can_void": false,
        "error": {
            "code": "51",
            "message": "Fondos insuficientes. Pídele al cliente otra tarjeta.",
            "action": "Reintentar con otro medio de pago"
        }
    }
}

Nota

Usa success para decidir, no el código HTTP: siempre te devolvemos el estado completo de la reserva para que sepas exactamente en qué quedó.

---

3. Cobro final

POST /api/v1/mit/pre-authorizations/{id}/confirm

Cobra el valor real. Este es el momento en que el dinero se mueve y en que la transacción pasa a Aprobada y se abona a tu cuenta virtual, por el valor cobrado.

Nombre del campo	Descripción	Reglas
amount	Valor real a cobrar. No puede superar max_confirmable_amount	['required', 'numeric', 'gt:0', 'max:99999999.99']

Reglas de vigencia:

• Puedes cobrar hasta la fecha de confirmable_until, que es la vigencia de la reserva: 7 días para Visa y 30 días para Mastercard desde la autorización.
• Puedes cobrar menos que lo reservado; la diferencia se libera. No puedes cobrar más.
• Una reserva solo admite un cobro final.

POSThttps://sag.efipay.co/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/confirm

Token de accesoCuerpo de la petición{ "amount": 620000 }

ProbarCopiar como cURL

curl -X POST \
'/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/confirm' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{ "amount": 620000 }'

Respuesta 200:

{
    "success": true,
    "operation": {
        "id": "019fba55-1c22-70aa-9f10-3d0b21ee7742",
        "operation": "confirmation",
        "status": "Confirmada",
        "status_label": "Cobrada",
        "estimated_amount": 620000,
        "response_code": "00",
        "authorization_code": "005081",
        "network_transaction_id": 320000303188
    },
    "pre_authorization": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "status": "Confirmada",
        "status_label": "Cobrada",
        "estimated_amount": 850000,
        "authorized_amount": 850000,
        "max_confirmable_amount": 620000,
        "can_confirm": false,
        "can_void": false,
        "confirmed_at": "2026-08-02T18:40:11-05:00"
    }
}

Si la reserva ya no admite cobro, la respuesta llega con success: false y el motivo en pre_authorization.blocked_reason.

---

4. Liberar la reserva

POST /api/v1/mit/pre-authorizations/{id}/void

Suelta la retención para que el cliente recupere su cupo. No requiere cuerpo.

Reglas de vigencia:

• Puedes liberar hasta voidable_until, que es 24 horas antes del vencimiento de la reserva. Esa ventana existe porque una liberación pedida sobre el filo del vencimiento puede cruzarse con la liberación automática de la red y quedar en un estado ambiguo.
• Pasada esa ventana, deja que la reserva venza: el cupo se libera solo, sin cobro. Lo verás con estado Vencida.
• Como nunca se abonó nada a tu cuenta virtual, liberar no genera ningún movimiento.

Este endpoint no recibe cuerpo.

POSThttps://sag.efipay.co/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/void

Token de accesoCuerpo de la petición

ProbarCopiar como cURL

curl -X POST \
'/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/void' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Respuesta 200:

{
    "success": true,
    "operation": {
        "operation": "void",
        "status": "Anulada",
        "status_label": "Reserva liberada",
        "response_code": "00"
    },
    "pre_authorization": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "status": "Anulada",
        "status_label": "Reserva liberada",
        "can_confirm": false,
        "can_void": false,
        "voided_at": "2026-08-01T09:12:44-05:00"
    }
}

---

Consultar y sincronizar

Una reserva

GET /api/v1/mit/pre-authorizations/{id}

Devuelve la reserva completa, con los mismos campos que ves en la respuesta de crear y autorizar. No recibe parámetros.

GEThttps://sag.efipay.co/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb

Token de acceso

ProbarCopiar como cURL

curl -X GET \
'/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

Consejo

Respuesta satisfactoria

200OK

{
    "data": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "operation": "pre_authorization",
        "status": "Pre-autorizada",
        "status_label": "Cupo reservado",
        "estimated_amount": 850000,
        "authorized_amount": 850000,
        "max_confirmable_amount": 850000,
        "currency": "COP",
        "installments": 1,
        "card": {
            "franchise": "visa",
            "bin": "491617",
            "last_four": "1313"
        },
        "references": [],
        "network_transaction_id": 320000303188,
        "authorization_code": "005081",
        "response_code": "00",
        "expires_at": "2026-08-08T18:40:11-05:00",
        "confirmable_until": "2026-08-08T18:40:11-05:00",
        "voidable_until": "2026-08-07T18:40:11-05:00",
        "can_confirm": true,
        "can_void": true,
        "blocked_reason": null,
        "checkout_url": null,
        "authorized_at": "2026-08-01T18:40:11-05:00",
        "confirmed_at": null,
        "voided_at": null,
        "created_at": "2026-08-01T18:39:02-05:00",
        "error": null
    }
}

Peligro

No encontramos la reserva

404Not Found

{
    "message": "No encontramos la reserva de cupo."
}

Todas tus reservas

GET /api/v1/mit/pre-authorizations

Paginado, de la más reciente a la más antigua.

Estos parámetros de consulta no se validan en el servidor: un valor inesperado no produce un 422, simplemente no filtra.

Nombre del campo	Descripción
status	Filtra por estado exacto, por ejemplo Pre-autorizada. Ver estados
pending_confirmation	true devuelve solo las que todavía admiten cobro final
per_page	Cuántas por página. Por defecto 25

GEThttps://sag.efipay.co/api/v1/mit/pre-authorizations

Token de acceso

ProbarCopiar como cURL

curl -X GET \
'/api/v1/mit/pre-authorizations?status=Pre-autorizada&pending_confirmation=true&per_page=50' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

Consejo

Respuesta satisfactoria

200OK

{
    "data": [
        {
            "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
            "operation": "pre_authorization",
            "status": "Pre-autorizada",
            "status_label": "Cupo reservado",
            "estimated_amount": 850000,
            "authorized_amount": 850000,
            "max_confirmable_amount": 850000,
            "currency": "COP",
            "can_confirm": true,
            "can_void": true,
            "confirmable_until": "2026-08-08T18:40:11-05:00",
            "created_at": "2026-08-01T18:39:02-05:00"
        }
    ],
    "links": {
        "first": "https://sag.efipay.co/api/v1/mit/pre-authorizations?page=1",
        "last": "https://sag.efipay.co/api/v1/mit/pre-authorizations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "per_page": 50,
        "to": 1,
        "total": 1
    }
}

Sincronizar contra la red

POST /api/v1/mit/pre-authorizations/{id}/sync

Consulta el estado real en la red y actualiza la reserva. No recibe cuerpo. Úsalo cuando el estado sea Indeterminada —no recibimos respuesta y no sabemos si el cupo quedó reservado— y para obtener la fecha de vencimiento real, que la red solo entrega al consultar.

POSThttps://sag.efipay.co/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/sync

Token de accesoCuerpo de la petición

ProbarCopiar como cURL

curl -X POST \
'/api/v1/mit/pre-authorizations/019fba50-8d0f-7362-a0b3-029215d91ebb/sync' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Accept: application/json'

Precaución

Ante un estado Indeterminada, no reintentes la autorización: podrías reservar el cupo dos veces. Llama a /sync o espera nuestro webhook; nosotros reconciliamos automáticamente.

---

Webhooks

Te notificamos cada cambio de estado en la URL de webhook_url de la reserva o, si no la enviaste, en el result_urls.webhook de tus opciones avanzadas.

Evento	Cuándo llega
mit.pre_authorized	El cliente autorizó: hay fondos retenidos
mit.declined	La red rechazó la reserva
mit.confirmed	Se aplicó el cobro final
mit.voided	Se liberó la reserva
mit.expiring_soon	La reserva vence pronto y todavía no la cobraste
mit.expired	La reserva venció y el cupo se liberó solo

Cuerpo:

{
    "event": "mit.pre_authorized",
    "pre_authorization": {
        "id": "019fba50-8d0f-7362-a0b3-029215d91ebb",
        "operation": "pre_authorization",
        "status": "Pre-autorizada",
        "status_label": "Cupo reservado",
        "estimated_amount": 850000,
        "authorized_amount": 850000,
        "max_confirmable_amount": 850000,
        "currency": "COP",
        "card": { "franchise": "visa", "bin": "491617", "last_four": "1313" },
        "references": [
            { "referenceKey": "Reserva", "referenceDescription": "HAB402" }
        ],
        "network_transaction_id": 320000303129,
        "authorization_code": "005077",
        "expires_at": "2026-08-07T10:15:00-05:00",
        "confirmable_until": "2026-08-07T10:15:00-05:00",
        "voidable_until": "2026-08-06T10:15:00-05:00",
        "can_confirm": true,
        "can_void": true,
        "error": null
    }
}

Nota

La ruta debe ser de tipo post.

Enviamos un header Signature con la firma del cuerpo, para que verifiques que no fue manipulado. Se firma con el token de webhooks de tu comercio, que encuentras aquí, usando HMAC-SHA256.

Si tu aplicación no responde 2xx reintentamos a los 10s y luego a los 100s. Después de eso no hay más intentos.

mit.expiring_soon es el que evita que se te pase un cobro: llega mientras la reserva todavía es cobrable, así que puedes cobrarla o dejarla vencer a conciencia.

---

Códigos de error

Puedes traer el catálogo completo, actualizado, desde GET /api/v1/resources/mit/response-codes. Cada entrada trae code, message, action y retryable, para que manejes los errores sin escribirlos a mano.

Errores propios de la reserva de cupo:

Código	HTTP	Qué pasó y qué hacer
MIT_PRODUCTION_KEY_REQUIRED	422	Intentaste autorizar con una llave de prueba. Una reserva retiene fondos reales, así que la modalidad api solo funciona con llave de producción
MIT_AMOUNT_EXCEEDS_AUTHORIZED	422	El cobro final supera lo reservado. Ajusta el monto a max_confirmable_amount
MIT_EXPIRED	422	La reserva venció. Debes crear una reserva nueva
MIT_ALREADY_CONFIRMED	409	Esta reserva ya tiene su cobro final aplicado
MIT_VOID_WINDOW_CLOSED	422	Ya cerró la ventana para liberar (24 h antes del vencimiento). Deja que venza
MIT_FRANCHISE_NOT_ENABLED	422	Esa franquicia no está habilitada para reservas en tu comercio. Escríbenos
MIT_INDETERMINATE	202	No recibimos respuesta de la red. No reintentes; estamos verificando
MIT_IN_PROGRESS	429	Ya hay una autorización en curso para esta reserva. Espera el resultado

Códigos de la red más frecuentes (llegan en pre_authorization.error.code):

Código	Qué pasó
51	Fondos insuficientes en el cupo del cliente
05	Negada: la tarjeta puede estar bloqueada o el emisor no respondió
54	Tarjeta vencida
M02	La reserva no está en un estado que admita esta operación
M12	El valor del cobro final no corresponde al reservado
309	El tipo de transacción MIT no admite 3DS
310	El ECI enviado no es válido: debe ser 05, 06 o 07
319 / 320	Enviaste el objeto 3DS de la otra franquicia

---

Límites y notas

• Moneda: solo COP.
• Franquicias: Visa y Mastercard. Amex, Diners y Codensa no admiten reserva de cupo.
• Vigencia: 7 días para Visa, 30 días para Mastercard, contados desde la autorización. La fecha exacta viene en expires_at.
• Cuotas: de 1 a 60.
• CVV obligatorio, y por eso todavía no hay soporte de tarjetas tokenizadas para reservas. Está en evaluación con la red.
• Referencias: solo letras, números y espacios; hasta 22 caracteres cada una. Procura que sean únicas por día: son la forma de identificar la reserva ante la red si hay que investigar una operación.
• Cuenta virtual: una reserva no abona nada mientras esté solo reservada. El abono ocurre con el cobro final, por el valor cobrado.
• Reporte de transacciones: la reserva aparece desde que el cliente la autoriza, con estado Autorizada, y pasa a Aprobada al cobrarla.