Inicio rápido
De la llave de prueba a tu primer link de pago y su webhook, en cinco pasos.
Esta guía te lleva de cero a un cobro confirmado en el entorno de pruebas. Todo ocurre de servidor a servidor: tu backend llama a la API con una llave secreta y Clobepay te avisa por webhook cuando el dinero queda liquidado.
1. Obtén una llave de prueba
En el panel, entra a Configuración de integración y crea una llave secreta de pruebas (prefijo sk_test_). Se muestra una sola vez: guárdala en tu gestor de secretos. Detalles en Llaves de API.
2. Configura tu entorno
export CLOBEPAY_API_BASE="<URL base de pruebas, incluye /api/v1>"
export CLOBEPAY_API_KEY="<tu llave sk_test_>"3. Comprueba la llave
curl "$CLOBEPAY_API_BASE/me" \
-H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta esperada: HTTP 200
La respuesta trae tu identificador de comercio (MID), el entorno y los scopes de la llave.
4. Crea un link de pago
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \
-H "Authorization: Bearer $CLOBEPAY_API_KEY" \
-H "Idempotency-Key: order-10042" \
-H "Content-Type: application/json" \
-d '{"amount":"50.00","description":"Pedido 10042","orderReference":"10042","metadata":{"cart_id":"c_77"}}'Respuesta esperada: HTTP 201
Redirige a tu cliente a la publicUrl de la respuesta. El link y su payin nacen en pending. Más en Links de pago.
5. Espera la confirmación
Da de alta un endpoint de webhooks, verifica la firma Clobepay-Signature y marca la orden como pagada solo cuando recibas payin.settled (o cuando GET /payins/{id} devuelva settled). El regreso del cliente a tu sitio no confirma el pago.
Antes de pasar a producción
- Usa una llave
sk_live_solo en tus servidores de producción. - Envía
Idempotency-Keyen todos los POST (Idempotencia). - Deduplica los webhooks por
Clobepay-Event-Idy responde 2xx rápido. - Reintenta 429 y 5xx con espera creciente (Errores).