checkouts

Create a checkout

Creates a charge with a hosted payment page. Default rail (payment_method: "pix"): a PIX QR the payer pays in any bank app. Alternative rail (payment_method: "depix"): the payer sends DePix wallet-to-wallet on Liquid to the merchant's dedicated address — no PIX QR, no payer document, an optional merchant discount, and settlement observed on-chain (approved at the first confirmation, completed at the second). Requires scope merchant_write on the API-key path; a merchant profile is required. sk_test_ creates a sandbox checkout (non-payable placeholder payload — complete it via simulate-payment). Track via GET /api/checkouts/{id} polling or checkout.* webhooks. Supports Idempotency-Key.

post/api/checkouts

Request

  • Base URL: https://api.depixapp.com
  • URL: https://api.depixapp.com/api/checkouts
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional idempotency key (1–255 visible ASCII chars). Retrying with the same key and the SAME body replays the stored response (marked with the Idempotency-Replayed: true header) with zero new side effects; the same key with a DIFFERENT body is rejected with 422 idempotency_key_reuse; a concurrent duplicate gets 409 idempotency_in_flight. Keys expire after 24 h. Responses with status 5xx/429 are never stored, so those retries re-execute.

Request body

amountinteger required

Charge amount in cents (BRL). Range: 500–600000. On the depix rail this is the FACE amount, before the merchant's discount.

payment_method'pix' | 'depix'

Which rail settles the checkout. pix (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. depix: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail.

descriptionstring

Free-text description shown on the checkout page (max 500 chars).

image_urlstring

HTTPS image displayed on the checkout page.

callback_urlstring

HTTPS webhook endpoint for this checkout's checkout.* events (overrides the merchant default).

redirect_urlstring

HTTPS URL the payer is redirected to after completion.

metadataobject

Arbitrary JSON object echoed back in reads and webhooks (max 4KB serialized).

expires_ininteger

How long this checkout stays open, in seconds. pix rail: 300–1200, default 1200. depix rail: 300–3600, default 1800. On the pix rail it governs the checkout, not the PIX BR Code — the payment provider sets its own QR expiry.

expected_discount_pctinteger

The DePix discount percentage the page showed the payer, 0–90. Send it on the depix rail to make a stale page fail loudly: if the merchant's current discount differs, the request is rejected with 409 discount_changed carrying the fresh values instead of charging a different price.

payer_tax_numberstring

CPF/CNPJ of the payer. Required on the pix rail — omitting it returns 400 validation_error naming the field. Ignored on the depix rail (there is no fiat leg to identify a payer for), so a shared integration can keep sending it.

Response

Checkout created.

idstring required

Checkout id (chk_*).

amountinteger required

Charge amount in cents (face value — what the buyer owes before any depix discount).

descriptionstring nullable required

Description echoed back (null when not provided).

image_urlstring nullable required

Image URL echoed back (null when not provided).

expires_atstring required

Expiry timestamp (RFC 3339 UTC, YYYY-MM-DDTHH:MM:SS.sssZ).

is_liveboolean required

False for sandbox checkouts (sk_test_): the payment payload is a non-payable placeholder.

payment_urlstring required

Hosted checkout page URL to hand to the payer.

payment_method'pix' | 'depix'

Which rail settles the checkout. pix (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. depix: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail.

Changes

No recorded changes to this operation across all 1 revision of this API.