public

Create a checkout on a merchant storefront (public)

Public (unauthenticated) checkout creation with a payer-chosen amount — the flow behind the "pay" button of a merchant's public page. Optionally carries a cart (items): every line is rebuilt from the merchant's catalog server-side and the request is rejected when the rebuilt total does not match amount. callback_url/redirect_url always come from the merchant's saved defaults and cannot be set here; the checkout is always live (never sandbox). Rate limit: 10 requests/minute per IP plus 60 checkouts/minute per merchant. NOTE: the 400/404/503-merchant bodies carry only the legacy response.errorMessage envelope (no machine-readable error object).

Errors on this operation are payer-scoped. The caller is an anonymous third party paying a merchant, so an error is only allowed to keep its response.errorMessage and its error.details when it describes the payer, the payer's input, or a fact about the thing being paid — which is every code documented below. Refusals that belong to the MERCHANT'S account (receive limits, onboarding gates, account configuration) answer a fixed neutral message ("Não foi possível gerar o pagamento. Fale com o vendedor.", or "…agora. Tente novamente em alguns minutos." for a 5xx) with error.details OMITTED. error.code is always the real one. Do not build a payer flow that reads error.details from a code not listed here: it is withheld by design, and the same call authenticated as the merchant (POST /api/checkouts) returns the full numbers.

usernamestring required

The merchant's public URL slug (merchant_slug). The path parameter is still named username for backwards compatibility.

Request body

amountinteger required

Charge amount in cents (BRL). Range: 500–600000. When items is sent this MUST equal the sum of qty × the catalog price of every line, otherwise the request is rejected. 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.

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.

Response

Checkout created.

idstring required

Checkout id (chk_*).

amountinteger required

Charge amount in cents (the amount sent in the request).

descriptionstring nullable required

Always null — this endpoint accepts no description field.

expires_atstring required

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

is_liveboolean required

Always true — public storefront checkouts are never sandbox.

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.

Create a checkout on a merchant storefront (public)

Request

Path parameters

Request body

Response

Changes