Proveedores (PSPs)

Conectá Stripe, Mercado Pago, dLocal y PayPal, y elegí cuál procesa cada pago.

Cauril habla con cada PSP detrás de un adapter. Vos usás la misma API; el adapter traduce a (y desde) cada proveedor, y normaliza estados, montos y errores.

Stripe

Tarjetas y métodos de Stripe. Credenciales: secret_key, webhook_secret.

Mercado Pago

Tarjetas y métodos locales de Latam (ej. Pix). Credenciales: access_token, webhook_secret.

dLocal

Cobertura cross-border de Latam: tarjeta, Pix, boleto, efectivo y transferencia. Credenciales: x_login, x_trans_key, secret_key (firma requests y webhooks). Sin suscripciones nativas todavía.

PayPal

Wallet global (método wallet): el comprador aprueba en PayPal y Cauril captura. Credenciales: client_id, client_secret, webhook_id. Soporta pagos y refunds (total/parcial); suscripciones nativas todavía no.

Dónde obtener las claves

Cada tarjeta abre la pantalla exacta del panel del proveedor donde están las credenciales.

Stripe

Dashboard → Developers → API keys → Secret key en modo test (sk_test_…). El webhook_secret (whsec_…) sale al crear un endpoint en Developers → Webhooks con la webhook_path que te da Cauril.

Mercado Pago

Developers → tu aplicación → Credenciales → access_token. El webhook_secret es la clave secreta que definís en Webhooks/Notificaciones.

dLocal

Panel → Integración → API keys: x_login, x_trans_key y secret_key (firma HMAC).

PayPal

Developer Dashboard → tu app (Sandbox) → client_id y client_secret. El webhook_id se adjunta después (vía PATCH) con la webhook_path de Cauril.

Para el checkout embebido con dLocal, dLocal debe habilitar Smart Fields en tu cuenta. Si los campos de tarjeta no cargan, pedíselo a tu contacto de dLocal.

Conectar

BASH

curl https://api.cauril.com/v1/provider-connections \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "mercadopago",
    "mode": "test",
    "credentials": { "access_token": "TEST-...", "webhook_secret": "..." }
  }'

Al conectar, Cauril valida las credenciales y descubre las capabilities de la cuenta (métodos y monedas soportados). Esas capabilities gatean la creación de pagos: pedir una moneda o un método que el PSP no soporta devuelve 422.

JSON

{
  "object": "provider_connection",
  "status": "connected",
  "capabilities": { "methods": ["card", "pix"], "currencies": ["BRL", "ARS"] },
  "webhook_path": "https://api.cauril.com/internal/webhooks/mercadopago/pcon_01J..."
}

Las credenciales se cifran at-rest y nunca se devuelven en ninguna respuesta. Si las rotás en el PSP, volvé a conectarlas en Cauril.

Qué PSP procesa un pago

Explícito

Pasá "provider": "stripe" en el body del pago para forzar ese PSP.

Por defecto

Si lo omitís, se usa el provider por defecto de tu organización.

Si no especificás provider y no hay uno por defecto configurado, la creación devuelve no_provider_resolved (400).

Webhooks del PSP

Cada conexión tiene su propia URL de ingesta (webhook_path). Configurala como destino de webhooks en el panel del PSP. Cauril verifica la firma del PSP sobre el cuerpo crudo, deduplica entregas repetidas y normaliza el evento antes de reflejarlo en el estado del pago y reenviártelo por tu webhook saliente.

En dLocal la URL de notificación viaja en cada request de pago/refund (no se configura en un panel): Cauril la apunta a la ingesta de esa conexión automáticamente. La firma se verifica con la misma secret_key (HMAC sobre X-Login + X-Date + body).