API Reference

View as Markdown

Quickstart

Send your first PIX payout and accept your first stablecoin or 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",
    "network": null,
    "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",
    "destinationAddress": null,
    "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.

Accept a stablecoin payment in your own checkout

Create a USD product with an enabled stablecoin payment method, then create one session per order:

curl -X POST "$BASE_URL/v1/checkout/products" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: catalog:pro-plan:v1" \
  -H "content-type: application/json" \
  -d '{
    "externalProductId": "pro-plan",
    "name": "Pro Plan",
    "amount": "29.00",
    "paymentMethods": { "networks": ["base"], "tokens": ["usdc"] }
  }'
curl -X POST "$BASE_URL/v1/checkout/sessions" \
  -H "x-api-key: dlfy_live_..." \
  -H "Idempotency-Key: session:txn_2049" \
  -H "content-type: application/json" \
  -d '{
    "externalProductId": "pro-plan",
    "transactionReference": "txn_2049",
    "userId": "user_42",
    "amount": "37.45",
    "paymentMethod": {
      "type": "crypto",
      "chain": "base",
      "settlementCurrency": "USDC"
    }
  }'

Here amount overrides the reusable product’s catalog price for this order only. Omit it to use the catalog price. Render session.stablecoin.amount, token, network, and depositAddress in your UI. You may also redirect to session.checkoutUrl; both presentations track the same charge. The full response and safety notes are in Sessions.

If the buyer sends less than the requested amount, the checkout.payment.underpaid webhook reports the cumulative amount received, the remaining amount, and the individual deposit receipt. Treat it as informational and fulfil only after checkout.payment.completed.