Checkout

Checkout sessions separate authenticated merchant session creation from public buyer actions. Checkout supports PIX and single-payment cards through the official Asaas invoice when the merchant has an available real integration.

Authentication

There are two secure ways to create a session:

• Your backend: use a secret key with the checkout_sessions.create scope.
• Official MuPag widget: use a publishable key with the checkout_sessions.create scope.

Never expose a secret key in the browser. A publishable key can only access operations explicitly allowed for frontend use.

Flow

1. Your backend or the official widget creates the session with POST /v1/checkout-sessions.
2. The frontend uses public session endpoints to apply a coupon and pay with PIX or open the official Asaas invoice returned in hosted_payment_url.
3. The final status is confirmed by session reads and webhook events.

Key fields

• success_url and cancel_url
• items
• customer_id or customer_data
• allowed_payment_methods: pix, credit_card, or both, depending on merchant availability
• affiliate_code and coupon_id when relevant

The buyer enters card details only on the official Asaas page. MuPag checkout never receives card details, CVV, or PSP tokens. Simulation-only accounts do not provide this invoice; use PIX for those scenarios.

When reopening a session, query /v1/checkout-sessions/{id}/status to resume the same charge. expires_at is the session deadline; charge_expires_at is the PIX charge expiration. When that deadline is unconfirmed, keep polling before displaying a payable QR code.

A rejection before charge reservation releases the attempt for correction. If a charge already has an authoritative terminal failure, the session completes and a new attempt uses /renew. Uncertain outcomes preserve the charge binding and return a conflict while payment is reconciled.

Idempotency

The public POST routes /select-method, /coupon, and /pay require the Idempotency-Key header: one value of 1 to 128 visible ASCII characters (0x21–0x7E). Without the header, the gateway responds 400 with idempotency_key_required. An invalid value responds idempotency_key_invalid. Coupon DELETE does not require the header. POST /renew also requires the header, and the renewal service uses that value.

The pay charge does not use the key sent by the client. The persisted key is checkout:{sessionId}. If the session already has a completed charge, the response returns that charge and does not call the PSP again.