Quickstart

Make a pay-out and a pay-in against the sandbox. You need curl and the sandbox key below. Nothing else.

Sandbox
Base URL https://apidocs.borderli.io. API key brly_test_key_001. No money moves.

Pay a QR code

One request decodes the QR and pays it. The three payer_* fields identify the person paying; the rail requires them.

curl -X POST https://apidocs.borderli.io/v1/pay \
  -H "Content-Type: application/json" \
  -H "x-api-key: brly_test_key_001" \
  -H "Idempotency-Key: quickstart-pay-001" \
  -d '{
    "qr_string": "PIX:quickstart_test",
    "payer_name": "Maria Silva",
    "payer_account": "0001234567",
    "payer_tax_id": "12345678909"
  }'

You get 202 Accepted and a pending transaction:

{
  "transaction": {
    "id": "txn_01J...",
    "instructionId": "ins_01J...",
    "status": "pending",
    "direction": "payout",
    "rail": "partner",
    "createdAt": "2026-09-14T10:00:00.000Z",
    "updatedAt": "2026-09-14T10:00:00.000Z"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

The payment settles a few seconds later. Borderli tells you by webhook. Until you have a webhook endpoint, poll:

curl https://apidocs.borderli.io/v1/transactions/txn_01J... \
  -H "x-api-key: brly_test_key_001"

When status is completed, result holds what settled. When it is failed, error.reason says why.

Show the amount before paying

If your user should confirm the amount and the recipient first, split the call in two. Resolve the QR:

curl -X POST https://apidocs.borderli.io/v1/resolve \
  -H "Content-Type: application/json" \
  -H "x-api-key: brly_test_key_001" \
  -d '{ "qr_string": "PIX:quickstart_test", "wallet_currency": "USD" }'
{
  "instruction": {
    "id": "ins_01J...",
    "amount": 1000,
    "currency": "BRL",
    "creditor": { "name": "Padaria do Centro", "account": "merchant-pix-key@example.com" },
    "scheme": "pix",
    "country": "BR",
    "fx": { "walletCurrency": "USD", "rate": 0.19, "convertedAmount": 190, "quoteExpiresAt": "..." },
    "expiresAt": "..."
  },
  "request_id": "..."
}

Show fx.convertedAmount and creditor.name to your user. When they confirm, execute the instruction:

curl -X POST https://apidocs.borderli.io/v1/execute \
  -H "Content-Type: application/json" \
  -H "x-api-key: brly_test_key_001" \
  -H "Idempotency-Key: quickstart-exec-001" \
  -d '{
    "instruction_id": "ins_01J...",
    "payer_name": "Maria Silva",
    "payer_account": "0001234567",
    "payer_tax_id": "12345678909"
  }'

An instruction is valid for 30 minutes. After that, resolve again.

Collect a payment

Ask for a QR worth R$10.00 that a Brazilian payer will scan:

curl -X POST https://apidocs.borderli.io/v1/collect \
  -H "Content-Type: application/json" \
  -H "x-api-key: brly_test_key_001" \
  -H "Idempotency-Key: quickstart-collect-001" \
  -d '{
    "amount": 1000,
    "local_currency": "BRL",
    "local_country": "BR",
    "qr_from": "BR",
    "merchant_tax_id": "12345678000195"
  }'
{
  "transaction": { "id": "txn_01J...", "status": "pending", "direction": "payin" },
  "qr": {
    "data": "00020101021126...",
    "charged": { "value": 1000, "currency": "BRL" },
    "exchange_rate": null,
    "expires_at": "2026-09-14T10:10:00.000Z"
  },
  "request_id": "..."
}

Render qr.data as a QR image. The payer has 10 minutes to scan it. When they pay, you get a transaction.completed webhook. If nobody pays, the transaction becomes canceled.

Next