Inicio rápido
Obtén tus llaves, llama a la API y crea tu primera sesión de checkout alojado en minutos.
Esta guía te lleva de cero a una sesión de checkout alojado funcionando. Vas a obtener una llave de API, verificar la conectividad, listar transacciones y crear una sesión a la que puedas redirigir a un pagador.
Empieza en sandbox: usa las mismas rutas, sin dinero real.
| Ambiente | URL base | Uso |
|---|---|---|
| Sandbox | https://staging-api.vecnet.io | Integración y pruebas. Sin dinero real. |
| Producción | https://api.vecnet.io | Cobros reales. |
Las páginas alojadas (checkout y ligas de pago) viven en https://pagos.vecnet.io.
Usa siempre la url exacta que devuelve la API; nunca construyas el host a mano.
Los montos van siempre en unidades mínimas (centavos); la moneda por defecto es MXN.
Obtén una llave de API
Tu integración se autentica con una llave de API del comercio. Crea una desde el panel, o con el endpoint de abajo si tienes acceso de operador. La llave en claro se devuelve una sola vez.
curl -X POST https://staging-api.vecnet.io/api/api-keys \
-H "Authorization: Bearer <jwt>" \
-H "X-Merchant-Id: mrc_3f9a2c1b" \
-H "Content-Type: application/json" \
-d '{"name": "Integración checkout"}'{
"id": "key_4f0c1a9b",
"name": "Integración checkout",
"key": "vk_test_1a2b3c4d5e6f7a8b9c0d",
"merchant_id": "mrc_3f9a2c1b"
}Guarda el valor de key ahora. No se puede recuperar después.
Verifica el estado y lista transacciones
Confirma que la API responde. GET /health no requiere autenticación.
curl https://staging-api.vecnet.io/health{ "status": "ok" }Ahora haz una llamada autenticada con tu llave. Las respuestas de lista son un
sobre con data, count, limit y offset:
curl https://staging-api.vecnet.io/api/transactions \
-H "Authorization: Token vk_test_1a2b3c4d5e6f7a8b9c0d"{
"data": [
{
"id": "txn_91kd02hsa7",
"rail": "online_cnp",
"amount_cents": 150000,
"currency": "MXN",
"status": "approved"
}
],
"count": 1,
"limit": 50,
"offset": 0
}Crea una sesión de checkout alojado
Crea la sesión con tu llave de API. La llave va en el encabezado
Authorization: Token.
curl -X POST https://staging-api.vecnet.io/checkout/v1/sessions \
-H "Authorization: Token vk_test_1a2b3c4d5e6f7a8b9c0d" \
-H "Content-Type: application/json" \
-d '{
"customer": { "first_name": "Ana", "last_name": "López", "email": "ana@example.com" },
"amount_total": 150000,
"currency": "MXN",
"line_items": [
{ "name": "Plan Pro", "quantity": 1, "unit_price": 150000, "product_id": "prod_001" }
],
"return_url": "https://tienda.example.com/retorno",
"payment_method_types": ["card", "spei"]
}'La respuesta es el objeto de sesión. Aquí created_at y modified_at son
milisegundos desde época (a diferencia de los demás recursos). Redirige al
pagador a url.
{
"id": "cs_a1b2c3d4e5",
"url": "https://pagos.vecnet.io/checkout/cs_a1b2c3d4e5",
"status": "pending",
"amount_total": 150000,
"currency": "MXN",
"created_at": 1782138600000,
"modified_at": 1782138600000
}Redirige al pagador y lee el resultado
Envía el navegador del pagador a la url de la sesión. La página alojada de
Vecnet muestra la sesión, cobra y regresa al pagador a tu return_url.
Conoce el resultado de una de dos formas:
- Webhooks (recomendado): suscríbete a
payment.approved,payment.declinedycheckout_session.completed. Consulta Webhooks. - Consulta (polling): recupera la sesión y lee su
status:
curl https://staging-api.vecnet.io/checkout/v1/sessions/cs_a1b2c3d4e5 \
-H "Authorization: Token vk_test_1a2b3c4d5e6f7a8b9c0d"Cuando tu integración esté lista, cambia la URL base a
https://api.vecnet.io y usa una llave de producción. Nada más cambia.