Resolva erros comuns do Asaas Checkout

Use esta página para identificar falhas na criação, redirecionamento e sincronização do Checkout.

Para os campos e schemas completos, consulte a referência de criação do Checkout.

Campos obrigatórios ausentes

Quando um campo obrigatório não é enviado, a API pode retornar:

{
   "errors": [
       {
           "code": "invalid_object",
           "description": "O campo items deve ser informado."
       }
   ]
}

Antes de reenviar a requisição, verifique:

• billingTypes;
• chargeTypes;
• callback com cancelUrl, expiredUrl e successUrl;
• items com name, quantity e value.

items[].description é opcional.

Alguns tipos de cobrança possuem dependências adicionais:

Consulte o endpoint Criar novo checkout.

Erro de autenticação

Se a API retornar HTTP 401, verifique se:

• o header access_token foi enviado;
• a API Key está válida e ativa;
• a chave pertence ao mesmo ambiente da URL utilizada;
• não existem espaços ou caracteres adicionais na chave.

Não exponha a API Key no front-end, código-fonte, logs públicos ou repositórios.

Consulte Autenticação.

URLs de callback inválidas

Os exemplos da documentação podem utilizar URLs fictícias:

"cancelUrl": "https://example.com/asaas/checkout/cancel",
"expiredUrl": "https://example.com/asaas/checkout/expired",
"successUrl": "https://example.com/asaas/checkout/success"

Substitua essas URLs pelas rotas reais da sua aplicação e teste os três cenários antes de utilizar o Checkout em Produção.

successUrl controla o redirecionamento do pagador e não confirma o pagamento.

Consulte Link do checkout e redirecionamento do cliente.

Checkout expirado

minutesToExpire define por quanto tempo o Checkout permanece disponível e aceita valores entre 10 e 1440 minutos.

Quando o Checkout expirar, crie um novo Checkout caso o pagador ainda precise concluir a compra.

Utilize expiredUrl para direcioná-lo ao fluxo correspondente na sua aplicação.

Pagamento não conciliado

Não atualize o pedido apenas porque o pagador foi direcionado para successUrl.

Utilize os eventos de Checkout para sincronizar o resultado:

Os Webhooks utilizam entrega at least once, portanto um mesmo evento pode ser enviado novamente.

Implemente idempotência utilizando o id do evento.

Consulte os Eventos para Checkout.

Checkout duplicado para o mesmo pedido

Armazene o id retornado pela criação e associe-o ao pedido no seu sistema.

Você também pode utilizar externalReference para relacionar o Checkout ao identificador interno da venda.

Antes de recriar um Checkout após uma falha da sua aplicação, verifique se o primeiro já foi criado.

Teste antes de Produção

Utilize o Sandbox para validar:

• criação do Checkout;
• redirecionamentos;
• expiração;
• processamento dos Webhooks;
• tratamento de erros.

A conta, a API Key e os dados do Sandbox são independentes de Produção.

Consulte o guia do Sandbox.

Próximos passos

• Implemente o Asaas Checkout
• Consulte o endpoint Criar novo checkout
• Configure o link e o redirecionamento
• Acompanhe os Eventos para Checkout
• Teste sua integração no Sandbox
• Consulte o FAQ do Asaas Checkout