Checkout

Sessões de checkout separam a criação autenticada pelo lojista das chamadas públicas do comprador. O checkout aceita PIX e cartão à vista pela fatura oficial do Asaas quando o lojista possui integração real disponível.

Autenticação

Há dois modos seguros para criar uma sessão:

• Backend próprio: use uma chave secreta com o escopo checkout_sessions.create.
• Widget oficial MuPag: use uma chave publishable com o escopo checkout_sessions.create.

Nunca exponha uma chave secreta no navegador. A chave publishable só pode acessar operações explicitamente liberadas para uso no frontend.

Fluxo

1. Seu backend ou o widget oficial cria a sessão em POST /v1/checkout-sessions.
2. O frontend usa os endpoints públicos da sessão para aplicar cupom e pagar via PIX ou abrir a fatura oficial do Asaas retornada em hosted_payment_url.
3. O status final da venda chega por consulta da sessão e por webhook.

Campos chave

• success_url e cancel_url
• items
• customer_id ou customer_data
• allowed_payment_methods: pix, credit_card ou ambos, conforme disponibilidade do lojista
• affiliate_code e coupon_id quando aplicável

O comprador informa os dados do cartão somente na página oficial do Asaas. O checkout MuPag não recebe cartão, CVV ou token PSP. Contas exclusivamente simuladas não oferecem essa fatura; use PIX nesses cenários.

Ao reabrir a sessão, consulte /v1/checkout-sessions/{id}/status para retomar a mesma cobrança. expires_at é o prazo da sessão; charge_expires_at informa a validade da cobrança PIX. Quando esse prazo não estiver confirmado, aguarde o polling antes de exibir o QR Code.

Uma rejeição antes da reserva libera a tentativa para correção. Se já houver uma cobrança com falha terminal, a sessão é concluída e uma nova tentativa usa /renew. Respostas incertas preservam o vínculo e retornam conflito enquanto o pagamento é conciliado.

Idempotência

Os POST públicos /select-method, /coupon e /pay exigem o header Idempotency-Key: um único valor de 1 a 128 caracteres ASCII visíveis (0x21–0x7E). Sem o header, o gateway responde 400 com idempotency_key_required. Valor inválido responde idempotency_key_invalid. O DELETE do cupom não exige o header. POST /renew também exige o header, e o serviço de renovação usa esse valor.

A cobrança de pay não usa a chave enviada pelo cliente. A chave persistida é checkout:{sessionId}. Se a sessão já tem cobrança concluída, a resposta devolve essa cobrança e não chama o PSP de novo.