Introdução - Asaas Checkout

Crie um Checkout Asaas pela API para vender produtos ou serviços em uma página de pagamento hospedada pelo Asaas.

Quando utilizar

Use o Checkout Asaas quando sua aplicação precisa gerar uma página pronta de pagamento sem construir toda a experiência de cobrança no seu próprio site ou aplicativo.

Ele é indicado para cenários como:

vender um produto ou serviço com pagamento único via Pix ou cartão de crédito;
enviar um link de pagamento para um cliente após um pedido de e-commerce, CRM ou atendimento;
iniciar uma assinatura recorrente com cobrança automática;
dividir o valor recebido entre diferentes contas Asaas usando split de pagamento;
redirecionar o cliente para páginas específicas de sucesso, cancelamento ou expiração.

Considere integrar diretamente com os endpoints de cobranças quando você precisar controlar toda a experiência de pagamento dentro da sua aplicação, aplicar regras muito específicas de checkout ou criar uma jornada que não use a tela hospedada do Asaas.

Pré-requisitos

Antes de criar um Checkout, conclua estas etapas:

Gere uma chave access_token seguindo a página de autenticação.
Defina as formas de pagamento que serão aceitas, como Pix, cartão de crédito ou ambas.
Escolha o tipo de cobrança: avulsa, parcelada ou recorrente.
Liste os produtos ou serviços vendidos, incluindo nome, quantidade e valor.
Crie as URLs do seu site para retorno em caso de sucesso, cancelamento e expiração.
Configure Webhooks se sua aplicação precisar acompanhar criação, pagamento, cancelamento ou expiração do Checkout.

Fluxo de integração

Siga esta sequência para criar e usar um Checkout:

Monte o payload de criação. Informe billingTypes, chargeTypes, minutesToExpire, callback e items.
Envie a requisição para a API. Crie o Checkout com uma requisição POST para https://api.asaas.com/v3/checkouts.
Guarde o ID retornado. A resposta bem-sucedida retorna um identificador único do Checkout.
Monte o link para o cliente. Use o ID retornado na URL https://asaas.com/checkoutSession/show?id=ID_RETORNADO.
Direcione o cliente para o Checkout. Envie o link por e-mail, mensagem, site, aplicativo ou outro canal do seu fluxo.
Trate o retorno do cliente. Use successUrl, cancelUrl e expiredUrl para exibir a próxima ação adequada.
Sincronize o status por Webhook. Use eventos de Checkout para confirmar pagamento, cancelamento ou expiração no seu sistema.

Pedido criado no sistema de origem
↓
Sua aplicação cria o Checkout na API do Asaas
↓
A API retorna o ID do Checkout
↓
Sua aplicação monta e entrega o link ao cliente
↓
Cliente conclui, cancela ou deixa o link expirar
↓
Cliente é redirecionado para a URL configurada
↓
Webhook informa o evento para sua aplicação

Parâmetros essenciais

No corpo da requisição, você define as informações que serão exibidas e usadas na jornada do Checkout.

Campo	Tipo	Obrigatório	Descrição
`billingTypes`	array de strings	Sim	Define os meios de pagamento aceitos no Checkout. Use `PIX`, `CREDIT_CARD` ou ambos, conforme sua venda.
`chargeTypes`	array de strings	Sim	Define o tipo de cobrança. Use `DETACHED` para cobrança avulsa ou `RECURRENT` para assinatura recorrente.
`minutesToExpire`	número	Sim	Define por quantos minutos o link do Checkout permanece válido.
`callback`	objeto	Sim, quando você precisa redirecionar o cliente	Agrupa as URLs de retorno após sucesso, cancelamento ou expiração.
`callback.cancelUrl`	string	Sim, dentro de `callback`	URL para redirecionar o cliente quando ele cancelar a jornada.
`callback.expiredUrl`	string	Sim, dentro de `callback`	URL para redirecionar o cliente quando o link estiver expirado.
`callback.successUrl`	string	Sim, dentro de `callback`	URL para redirecionar o cliente após a conclusão bem-sucedida do Checkout.
`items`	array de objetos	Sim	Define os produtos ou serviços vendidos. Inclua pelo menos um item.
`items[].name`	string	Sim	Nome do produto ou serviço exibido no Checkout.
`items[].description`	string	Não	Descrição complementar do item.
`items[].quantity`	número	Sim	Quantidade do item vendido.
`items[].value`	número	Sim	Valor unitário do item em reais.
`customerData`	objeto	Não	Preenche dados do cliente automaticamente na tela do Checkout, quando enviado.
`splits`	array de objetos	Não	Divide automaticamente o valor recebido entre diferentes carteiras Asaas.
`subscription`	objeto	Sim, para `RECURRENT`	Define as regras da assinatura, como ciclo e datas da recorrência.

Use valores consistentes com o pedido salvo no seu sistema. Divergências em itens, quantidade ou valor podem gerar conciliação incorreta entre o Checkout e a venda original.

Exemplo: criar Checkout para Pix

Este exemplo cria uma cobrança avulsa via Pix, com link válido por 60 minutos e URLs de retorno para sucesso, cancelamento e expiração.

curl --request POST \
  --url https://api.asaas.com/v3/checkouts \
  --header 'Content-Type: application/json' \
  --header 'access_token: SEU_ACCESS_TOKEN' \
  --data '{
    "billingTypes": ["PIX"],
    "chargeTypes": ["DETACHED"],
    "minutesToExpire": 60,
    "callback": {
      "cancelUrl": "https://meusite.com/cancelado",
      "expiredUrl": "https://meusite.com/expirado",
      "successUrl": "https://meusite.com/sucesso"
    },
    "items": [
      {
        "name": "Curso de Marketing",
        "description": "Curso completo de marketing digital",
        "quantity": 1,
        "value": 297.00
      }
    ]
  }'

Resposta esperada em uma criação bem-sucedida:

{
  "id": "c7b1c696-b27b-4d3d-80b9-d1c018e387f8"
}

Com o id retornado, monte o link do Checkout:

https://asaas.com/checkoutSession/show?id=c7b1c696-b27b-4d3d-80b9-d1c018e387f8

Envie esse link para o cliente ou integre-o ao botão de pagamento do seu site.

Comportamentos importantes

O link deixa de ser válido após o período definido em minutesToExpire.
Se o cliente acessar um Checkout expirado, direcione-o para expiredUrl e ofereça uma forma de gerar um novo link.
Se o cliente cancelar a jornada, direcione-o para cancelUrl e permita uma nova tentativa ou retorno ao carrinho.
Se o Checkout for concluído com sucesso, direcione-o para successUrl com a confirmação do pedido ou instruções pós-pagamento.
Se customerData for enviado, os campos de identificação e endereço podem vir preenchidos automaticamente na tela do Checkout.
Para assinatura recorrente, use chargeTypes com RECURRENT e envie o objeto subscription com as regras da recorrência.
Para split de pagamento, envie splits com as carteiras e os valores fixos ou percentuais que devem receber parte do pagamento.
Não dependa apenas do redirecionamento do navegador para confirmar pagamento. Use Webhooks para manter o status do pedido sincronizado.

Tratamento de erros e boas práticas

Situação	Possível causa	Como tratar
Falha de autenticação	`access_token` ausente, inválido ou pertencente a outro ambiente.	Gere uma chave válida e revise o header `access_token` antes de reenviar a requisição.
Erro de validação	Campos obrigatórios ausentes ou dados em formato incompatível com a operação.	Valide `billingTypes`, `chargeTypes`, `minutesToExpire`, `callback` e `items` antes de chamar a API.
Link expirado	O prazo definido em `minutesToExpire` terminou.	Crie um novo Checkout e redirecione o cliente para uma página que explique a expiração.
Pagamento não conciliado	A aplicação considerou apenas o redirecionamento do navegador.	Configure Webhooks de Checkout para receber eventos como `CHECKOUT_PAID`, `CHECKOUT_CANCELED` e `CHECKOUT_EXPIRED`.
Duplicidade em reprocessos	A aplicação criou mais de um Checkout para o mesmo pedido.	Salve o ID do Checkout junto ao pedido e verifique se já existe um Checkout ativo antes de criar outro.
Erro em split ou recorrência	Dados de carteiras, percentuais, valores ou datas de assinatura inconsistentes.	Teste o payload em Sandbox e valide as regras específicas nas páginas de split e assinatura antes de publicar.

Ao desenvolver sua integração:

teste o fluxo completo em Sandbox antes de enviar links reais para clientes;
salve o ID do Checkout retornado pela API para auditoria, suporte e conciliação;
crie páginas claras para successUrl, cancelUrl e expiredUrl;
implemente idempotência no processamento de Webhooks usando o identificador do evento recebido;
responda rapidamente aos Webhooks e processe regras internas em segundo plano;
monitore falhas para evitar links expirados, pedidos sem conciliação ou eventos duplicados.

Impactos operacionais

A criação de um Checkout pode iniciar uma venda real, gerar um link de pagamento, criar uma assinatura recorrente ou distribuir valores por split, dependendo do payload enviado.

Configurações incorretas podem afetar o valor cobrado, a validade do link, a experiência de retorno do cliente e a conciliação financeira do pedido. Por isso, valide o payload com dados reais de teste, acompanhe os eventos do Checkout e registre os identificadores retornados pela API.

Próximos passos

Consulte estes conteúdos para continuar a implementação:

Checkout para Pix — crie um Checkout avulso com Pix, expiração e URLs de retorno.
Checkout com Assinatura (recorrente) — configure cobranças recorrentes com RECURRENT.
Checkout com Split de Pagamento — divida valores entre diferentes carteiras Asaas.
Link do checkout e redirecionamento do cliente — monte a URL final usando o ID retornado pela API.
Eventos para Checkout — sincronize criação, pagamento, cancelamento e expiração por Webhooks.
Como informar os dados do cliente — preencha dados do cliente automaticamente no Checkout.
Referência da API — consulte campos, respostas e regras de cada endpoint.