Quickstart

Todo lo que sigue usa la URL base https://api.cauril.com y tu API key de test (sk_test_…) como Bearer token.

1. Tu API key de test

   Al crear tu cuenta, Cauril genera una API key de test (sk_test_…) automáticamente, la ves una vez al entrar. Después la gestionás en API keys (generás más o las revocás). Guardala en una variable de entorno y usala como Bearer token en todo lo que sigue; nunca la subas al repo.

   BASH

   export CAURIL_API_KEY=sk_test_...

2. Conectá un PSP

   Conectá tu cuenta de PSP (en modo test). Las credenciales se cifran at-rest y nunca se devuelven. La respuesta trae webhook_path: la URL que vas a configurar en el PSP.

   ¿Preferís sin código? Conectá el PSP desde el dashboard en Proveedores: validamos las credenciales al instante.

   BASH

   curl https://api.cauril.com/v1/provider-connections \
     -H "Authorization: Bearer $CAURIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "provider": "stripe",
       "mode": "test",
       "credentials": { "secret_key": "sk_test_...", "webhook_secret": "whsec_..." }
     }'

   Respuesta

   {
     "object": "provider_connection",
     "id": "pcon_01J...",
     "provider": "stripe",
     "status": "connected",
     "capabilities": { "methods": ["card"], "currencies": ["USD", "BRL"] },
     "webhook_path": "https://api.cauril.com/internal/webhooks/stripe/pcon_01J..."
   }

   Configurá webhook_path como destino de webhooks en el panel del PSP.

3. Creá un pago

   El método de pago se tokeniza del lado del cliente/PSP: Cauril nunca ve PAN ni CVV. El header Idempotency-Key es obligatorio.

   El token lo genera el PSP del lado del cliente, nunca tu servidor. En producción lo obtenés con el SDK del PSP en tu front-end (p.ej. Stripe.js) o, más simple, con el checkout embebido de Cauril, que monta el campo del PSP y te devuelve el token sin que un dato de tarjeta toque tu código. Para probar contra Stripe sandbox usá su token de test pm_card_visa.

   BASH

   curl https://api.cauril.com/v1/payments \
     -H "Authorization: Bearer $CAURIL_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 5000,
       "currency": "USD",
       "payment_method": { "type": "card", "token": "pm_card_visa" }
     }'

   Respuesta

   {
     "object": "payment",
     "id": "pay_01J...",
     "status": "processing",
     "amount": 5000,
     "currency": "USD",
     "provider": "stripe"
   }

   El estado al crear el pago puede ser processing, requires_action (el comprador debe completar un paso, p.ej. 3-D Secure) o succeeded. El estado definitivo llega por webhook, no lo asumas de la respuesta, ver Ciclo de vida del pago. El amount es siempre un entero en la unidad mínima de la moneda (5000 = USD 50.00). Nunca decimales.

4. Recibí el webhook

   Suscribite a eventos. El secret se devuelve una sola vez: guardalo para verificar la firma.

   BASH

   curl https://api.cauril.com/v1/webhooks/endpoints \
     -H "Authorization: Bearer $CAURIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "url": "https://tuapp.com/webhooks/cauril", "enabled_events": ["payment.succeeded", "payment.failed"] }'

   Cada entrega llega firmada en el header Cauril-Signature. Verificala antes de confiar en el payload → Webhooks.

¿Sin cuenta de PSP todavía?

Para recorrer el ciclo de vida completo sin un PSP real, conectá un proveedor mock (mismo paso 2, con "provider": "mock" y credenciales vacías). Después controlás el resultado del pago con el token que mandás, sin tokenización:

tok_succeed     → status: succeeded
tok_processing  → status: processing  (se resuelve por webhook)
tok_action      → status: requires_action
tok_fail        → status: failed

Es la forma más rápida de ver estados, webhooks y reembolsos end-to-end antes de conectar Stripe o Mercado Pago.

Próximo paso