Quickstart

Prerequisites

Cobru account with API credentials from panel.cobru.co
Two credential values from the dashboard: x-api-key, refresh_token
Sandbox base URL: https://dev.cobru.co

This page focuses on the shortest successful path. For the full auth model, token caching, and security guidance, continue with /docs/authentication.

Step 1. Get an access token

curl -X POST https://dev.cobru.co/token/refresh/ \
  -H "x-api-key: $COBRU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh":"'"$COBRU_REFRESH_TOKEN"'"}'

The field is refresh, not refresh_token. The WooCommerce plugin documentation is wrong on this point.

Response 200:

{ "access": "eyJ0eXAi..." }

The access token appears to last about 60 minutes. Cache it for at most 50 minutes.

Step 2. Create a payment

curl -X POST https://dev.cobru.co/cobru/ \
  -H "x-api-key: $COBRU_API_KEY" \
  -H "Authorization: Bearer $COBRU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "description": "Order #123",
    "expiration_days": 1,
    "client_assume_costs": false,
    "iva": 0,
    "payment_method_enabled": "{\"breb\":true,\"bancolombia_qr\":true,\"pse\":true}",
    "payer_redirect_url": "https://yourapp.com/payment-success",
    "callback": "https://yourapp.com/api/cobru/webhook"
  }'

payment_method_enabled must be a JSON-serialized string — run JSON.stringify({...}) before including it in the body. Sending it as a plain object returns HTTP 400.

Always include both payer_redirect_url and callback. Missing either field can return a misleading HTTP 403, even though the root problem is request validation.

Response 201:

{
  "pk": 27150,
  "url": "3gofdf6f",
  "amount": "50000.00",
  "state": 0,
  "fee_amount": 2395,
  "currency_code": "COP",
  "idempotency_key": "3114242222_8de7c88b84..."
}

// CORRECT
const paymentUrl = `${COBRU_BASE_URL}/${response.url}`;
// Example: https://dev.cobru.co/3gofdf6f

// WRONG (WooCommerce plugin pattern — does NOT work)
const paymentUrl = `${COBRU_BASE_URL}/pay/${response.pk}`;

From here you can:

send the link directly in email, SMS, or chat
turn it into a PNG QR using api.qrserver.com
use the BRE-B + QR flow documented in /docs/guides/qr-breb

Step 4. Receive the webhook

export async function POST(request: Request) {
  const payload = await request.json();

  // Persist first, process second.
  console.log('Cobru webhook:', payload);

  return new Response('ok', { status: 200 });
}

Cobru webhooks are not currently signed. Treat the callback as a trigger, not as a source of truth for high-risk operations.

Environment variables

COBRU_BASE_URL=https://dev.cobru.co   # sandbox
COBRU_API_KEY=your_api_key
COBRU_REFRESH_TOKEN=your_refresh_token
NEXT_PUBLIC_APP_URL=https://yourapp.com

Next steps

Read /docs/authentication for token caching and security boundaries.
Read /docs/webhooks for idempotency and verification patterns.
Read /docs/api/cobrus/create for the full payment request and response contract.