# 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](/docs/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](/docs/errors).

```bash
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:

```bash
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](/docs/banking-transfers) — note the all-in `fxRate` and the `sourceAmount` debited from your balance:

```json
{
  "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](/docs/banking-webhooks), or poll `GET /v1/banking/transfers/:transferId`.

## Accept your first PIX payment

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

```bash
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 }
  }'
```

```bash
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](/docs/checkout-sessions)) gives you a hosted `checkoutUrl` to redirect to, or a raw `pix.code` to render as your own QR:

```json
{
  "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](/docs/checkout-webhooks) arrives — match it by `data.urlParams.txn_id`. Never fulfil from a success page or browser redirect.