Checkout alojado
Crea una sesión de checkout, redirige al pagador a la página alojada y conoce el resultado por webhook o consultando la sesión.
El checkout alojado de Vecnet te permite crear una sesión desde tu servidor con
una llave de API, redirigir al pagador a la url alojada que te devolvemos y
dejar que la página de pagos se encargue de mostrar la sesión y cobrar. Todo el
ciclo (sesión creada, pagador redirigido, pago aprobado o rechazado) queda
cosido por un solo correlation_id.
Todos los montos van en unidades mínimas (centavos). amount_total: 49900
significa MXN 499.00. La moneda por defecto es MXN.
Resumen
Crea una sesión (servidor a servidor)
Tu backend llama a POST /checkout/v1/sessions con tu llave de API. La
respuesta trae el id de la sesión (un cs_…) y la url del checkout alojado.
Redirige al pagador a la url
Envía el navegador del pagador a la url de la respuesta. Esa página la sirve
la plataforma de pagos de Vecnet.
El pagador paga en la página alojada
La página muestra la sesión (tu marca, los conceptos, el monto a pagar), cobra y
regresa al pagador a tu return_url o success_url.
Conoce el resultado
Suscríbete a webhooks (recomendado) o consulta la sesión y lee
su status.
Paso 1: crea una sesión de checkout
Autentica con tu llave de API usando el esquema Token (X-API-Key también
funciona). Crea una llave desde el panel o con POST /api/api-keys; el valor en
claro se muestra una sola vez.
| Quién llama | Encabezado | Dónde se usa |
|---|---|---|
| Tu integración (llave de API) | Authorization: Token <llave> o X-API-Key: <llave> | Checkout alojado, ligas de pago y llamadas servidor a servidor. |
| Un operador del panel (JWT) | Authorization: Bearer <jwt> + X-Merchant-Id: mrc_… | Recursos administrativos desde el panel. |
expires_at acepta una marca Unix (segundos o milisegundos) o una cadena
ISO 8601, entre 30 minutos y 24 horas en el futuro; por defecto son 24 horas.
payment_method_types debe ser un subconjunto no vacío de los métodos
habilitados para el comercio. return_url es obligatorio salvo que envíes
success_url.
curl -X POST https://api.vecnet.io/checkout/v1/sessions \
-H "Authorization: Token vk_live_1a2b3c4d5e6f7a8b9c0d" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"first_name": "Ana",
"last_name": "Ramírez",
"email": "ana.ramirez@example.com"
},
"amount_total": 49900,
"currency": "MXN",
"line_items": [
{ "name": "Plan Pro (mensual)", "quantity": 1, "unit_price": 49900, "product_id": "prod_plan_pro" }
],
"return_url": "https://tienda.example.com/checkout/retorno",
"success_url": "https://tienda.example.com/checkout/exito",
"external_id": "orden_2026_06_22_0001",
"payment_method_types": ["card", "spei", "oxxopay"],
"metadata": { "cart_id": "cart_77c2" }
}'La misma llamada en JavaScript:
const res = await fetch("https://api.vecnet.io/checkout/v1/sessions", {
method: "POST",
headers: {
Authorization: "Token vk_live_1a2b3c4d5e6f7a8b9c0d",
"Content-Type": "application/json",
},
body: JSON.stringify({
customer: { first_name: "Ana", last_name: "Ramírez", email: "ana.ramirez@example.com" },
amount_total: 49900,
currency: "MXN",
line_items: [
{ name: "Plan Pro (mensual)", quantity: 1, unit_price: 49900, product_id: "prod_plan_pro" },
],
return_url: "https://tienda.example.com/checkout/retorno",
success_url: "https://tienda.example.com/checkout/exito",
external_id: "orden_2026_06_22_0001",
payment_method_types: ["card", "spei", "oxxopay"],
metadata: { cart_id: "cart_77c2" },
}),
});
const session = await res.json();
window.location.href = session.url;Respuesta
La respuesta es la sesión de checkout. Redirige al pagador a url.
{
"id": "cs_3f9a1c7d2e6b4a8f",
"url": "https://pagos.vecnet.io/checkout/cs_3f9a1c7d2e6b4a8f",
"status": "pending",
"amount_total": 49900,
"currency": "MXN",
"customer": {
"first_name": "Ana",
"last_name": "Ramírez",
"email": "ana.ramirez@example.com"
},
"external_id": "orden_2026_06_22_0001",
"payment_method_types": ["card", "spei", "oxxopay"],
"created_at": 1782138600000,
"modified_at": 1782138600000
}En el objeto de sesión, created_at y modified_at son milisegundos desde
época, no ISO 8601. Todas las demás marcas de tiempo de la API son ISO 8601.
Redirige a la url exacta que recibes; no escribas el host a mano.
Paso 2: redirige al pagador
Envía el navegador del pagador a la url de la respuesta (una redirección HTTP
o window.location.href = session.url). La plataforma sirve la página de
checkout alojado en esa URL y se encarga del cobro.
Paso 3: conoce el resultado
El pagador completa el pago en la página alojada; tu integración nunca toca datos de tarjeta. Obtén el resultado de una de dos formas.
Webhooks (recomendado)
Suscríbete a los eventos que te importan y reacciona conforme llegan:
checkout_session.completed: la sesión llegó a un estado final.payment.approved: el pago fue aprobado.payment.declined/payment.failed: el pago no se completó.
Consulta Webhooks para el sobre, la verificación de firma y el catálogo completo de eventos.
Consultar la sesión
Puedes recuperar la sesión en cualquier momento con tu llave de API para revisar
su status.
curl https://api.vecnet.io/checkout/v1/sessions/cs_3f9a1c7d2e6b4a8f \
-H "Authorization: Token vk_live_1a2b3c4d5e6f7a8b9c0d"El status de una sesión es uno de pending, completed, expired o
cancelled. Cuando es completed, la fila correspondiente en transactions
lleva el status autoritativo del pago
(ciclo de vida).
Rastrear el ciclo completo
Cada paso escribe en la bitácora de auditoría, enlazado por el
correlation_id de la sesión, que también aparece en la fila resultante de
transactions. Con ese único valor se reconstruye el pago entero. Consulta
Trazabilidad.