API Reference

View as Markdown

Quickstart

Send your first PIX payout and accept your first PIX payment in a few minutes.

Two short happy paths to your first live API calls. You need three things first:

  1. An API key — created in your dashboard under Developers → Keys. See Authentication.
  2. Your API base URL — shown in your dashboard next to the key. Set it as BASE_URL below; all paths in these docs are relative to it.
  3. A server to call from. The API is server-side only — never ship your key in client code.

Send your first payout

Save a PIX recipient once, then send money to its id. Both calls require an Idempotency-Key — see Errors & Idempotency.

curl -X POST "$BASE_URL/v1/banking/recipients" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: recipient-acme-pix-001" \
  -H "content-type: application/json" \
  -d '{
    "name": "Acme Ltda",
    "type": "business",
    "currency": "BRL",
    "rail": "pix",
    "pix": { "key": "finance@acme.example", "documentNumber": "12345678000199" }
  }'

The response includes recipient.id. Use it to create a transfer — amount is what the recipient receives, in BRL:

curl -X POST "$BASE_URL/v1/banking/transfers" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: pix-acme-1048" \
  -H "content-type: application/json" \
  -d '{
    "recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "amount": "100.00",
    "currency": "BRL",
    "rail": "pix",
    "memo": "Invoice 1048",
    "description": "Acme Ltda supplier payout"
  }'

Returns 201 Created with the transfer object — note the all-in fxRate and the sourceAmount debited from your balance:

{
  "transfer": {
    "id": "7b4f1f9c-7d92-4d12-a4aa-9c5b2f4f9b25",
    "object": "banking.transfer",
    "status": "pending",
    "direction": "debit",
    "rail": "pix",
    "description": "Acme Ltda supplier payout",
    "memo": "Invoice 1048",
    "sourceCurrency": "USDC",
    "sourceAmount": "18.82",
    "destinationCurrency": "BRL",
    "destinationAmount": "100.00",
    "fxRate": "5.31349628",
    "recipientId": "9a5b47c1-234d-4841-a5b8-d1b790f774be",
    "idempotencyKey": "pix-acme-1048",
    "createdAt": "2026-06-25T12:00:00.000Z",
    "updatedAt": "2026-06-25T12:00:00.000Z",
    "completedAt": null
  }
}

Confirm the payout with the banking.transfer.completed webhook, or poll GET /v1/banking/transfers/:transferId.

Accept your first PIX payment

Create a reusable PIX product once, then create one session per order:

curl -X POST "$BASE_URL/v1/checkout/products" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: catalog:curso-pro:v1" \
  -H "content-type: application/json" \
  -d '{
    "externalProductId": "curso-pro",
    "name": "Curso Pro",
    "amount": "49.90",
    "paymentMethods": { "pix": true }
  }'
curl -X POST "$BASE_URL/v1/checkout/sessions" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: session:txn_1048" \
  -H "content-type: application/json" \
  -d '{
    "externalProductId": "curso-pro",
    "transactionReference": "txn_1048",
    "userId": "user_42",
    "buyerEmail": "ana.silva@example.com"
  }'

The session response (trimmed — full shape in Sessions) gives you a hosted checkoutUrl to redirect to, or a raw pix.code to render as your own QR:

{
  "session": {
    "id": "310ace43-4c69-4fd2-acd8-94645dbe1938",
    "transactionReference": "txn_1048",
    "status": "created",
    "checkoutUrl": "https://dolafy.com/checkout/c-8f41a2d9?dolafy_session_id=310ace43-4c69-4fd2-acd8-94645dbe1938",
    "pix": { "code": "000201...6304ABCD", "amount": "49.90", "currency": "BRL" }
  }
}

Fulfil the order when the checkout.payment.completed webhook arrives — match it by data.urlParams.txn_id. Never fulfil from a success page or browser redirect.