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

Variables de 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 · Comprobar tu 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 · Crear un link de pago de 50 USDT
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-Key en todos los POST (Idempotencia).
  • Deduplica los webhooks por Clobepay-Event-Id y responde 2xx rápido.
  • Reintenta 429 y 5xx con espera creciente (Errores).