Sessions

Create a PIX charge from a product and get a hosted URL plus a raw PIX code for a transparent checkout.

A session creates one PIX charge from an active PIX product and returns two presentations of that same charge: a Dolafy-hosted checkoutUrl and the raw PIX Copia e Cola string in pix.code. Render the code as your own QR image for a transparent checkout, or redirect the buyer to the URL. Switching between them never creates a second charge.

Create a session

POST /v1/checkout/sessions
x-api-key: dlfy_live_...
Idempotency-Key: session:txn_1048
content-type: application/json

Provide exactly one of productId (≤ 120 chars) or externalProductId (≤ 200 chars). Optional fields: transactionReference (≤ 200), userId (≤ 200), buyerEmail (valid email, ≤ 320), description (≤ 500), and discountPercent. The discount may be a number or numeric string greater than 0 and less than 100, with at most two decimal places. It changes only this session’s charge; the reusable product and its rail remain unchanged. If transactionReference is omitted, Dolafy generates txn_<uuid>.

Request

{
  "externalProductId": "curso-pro",
  "transactionReference": "txn_1048",
  "userId": "user_42",
  "buyerEmail": "ana.silva@example.com",
  "description": "Curso Pro checkout",
  "discountPercent": "20.00"
}

Response

Returns 201 Created on first creation, 200 OK on an identical replay.

{
  "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",
    "expiresAt": "2026-07-22T12:30:00.000Z",
    "product": {
      "id": "6a713a92-350a-4cc6-a996-1e55e97d3a36",
      "externalProductId": "curso-pro",
      "slug": "c-8f41a2d9",
      "name": "Curso Pro",
      "amount": "39.92",
      "currency": "BRL"
    },
    "pricing": {
      "originalAmount": "49.90",
      "discountPercent": "20.00",
      "discountAmount": "9.98",
      "finalAmount": "39.92",
      "currency": "BRL"
    },
    "pix": {
      "code": "000201...6304ABCD",
      "amount": "39.92",
      "currency": "BRL",
      "expiresAt": "2026-07-22T12:30:00.000Z"
    }
  }
}

Notes

• session.id is the checkout charge id. pix.code is the payable Copia e Cola payload — not a bank PIX key.
• The hosted URL uses the reserved dolafy_session_id parameter to load and poll that already-created charge; opening it never creates a second charge. This parameter is not copied into your attribution, webhook data.urlParams, or success redirects. Treat the full hosted URL as payment-session data — do not expose it in logs.
• session.status is the current normalized status — normally created on first response; a replay can return a later pending, paid, expired, or failed.
• pricing makes the one-off adjustment auditable. product.amount and pricing.finalAmount are the final charge total; pix.amount is the exact BRL amount the buyer must pay.
• When discountPercent is omitted, pricing.discountPercent is null, discountAmount is 0.00, and the original and final amounts are equal.
• transactionReference is persisted as txn_id and userId as the charge externalId; both are returned by the Transactions reads and included in webhook data.
• Confirmation is driven by webhooks — checkout.payment.completed or checkout.payment.failed. It never depends on a success page or browser redirect. Fulfil only after checkout.payment.completed.

Idempotency & conflicts

An identical retry with the same Idempotency-Key returns the same charge, hosted URL, and PIX code. Replaying a completed session still works even after its product is archived.

• Reusing an idempotency key with a different body → 409 idempotency_key_conflict.
• Changing discountPercent changes the body. Equivalent forms such as 20, "20", and "20.00" normalize identically.
• Assigning the same transactionReference to another session → 409 transaction_reference_conflict.

Rate limits

Session creation is limited per customer and per organization: 3 new sessions per customer per 10 minutes, and 30 per organization per minute. Exceeding a limit returns 429 with a Retry-After header and either checkout_session_customer_rate_limit_exceeded or checkout_session_organization_rate_limit_exceeded. Customer identity is derived from userId, then buyerEmail, then transactionReference. Identical idempotent replays do not consume the limit.

Errors

Rare edge-case codes are listed under Advanced.

Advanced

Discount rounding and limits

The discount is calculated with exact basis-point arithmetic and rounded half-up to cents. A discount that rounds to less than one cent, or that produces a PIX total below R$1.00, is rejected before payment instructions are created — see the codes below. Discounts are accepted only by this authenticated session endpoint; do not add discount query parameters to reusable hosted product links.

Rare errors