Erros comuns

1. Campos obrigatórios ausentes

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

Como evitar: Sempre preencha os campos obrigatórios:

• billingTypes
• chargeTypes
• callback com cancelUrl, expiredUrl, successUrl
• items com name, description, value, quantity

Dicas:

Organização e clareza — Estruture suas requisições com indentação clara e nomeie bem seus itens (name, description) — isso ajuda na conversão e na visualização.

Segurança — Mantenha seu access_token seguro e nunca exponha em repositórios públicos.

Testes e ambiente sandbox — Use o ambiente de testes para validar integrações antes de ir para produção.

Fluxo de expiração ajustado — Use minutesToExpire de forma estratégica.

Experiência do cliente — Envie imagens base64 nos itens do checkout para uma tela mais visual e profissional. Preencha customerData sempre que possível para agilizar o preenchimento dos dados do cliente.

Reaproveitamento — Cadastrou um cliente via API? Use o campo customer nas próximas vendas com esse mesmo comprador.

Validação de regras de negócio — Confira se sua lógica de chargeTypes e billingTypes está conforme as seguintes combinações válidas:

🚧

Atenção:

Personalize suas URLs antes de testar seu Checkout

Ao seguir o guia de criação de novo checkout (documentação oficial), muitos clientes utilizam exemplos de URLs como:

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

Por quê?

Essas URLs são fictícias — se você deixá-las como estão, seu cliente será redirecionado para páginas que não existem ou resultarão em erro 404.

• Ambiente de teste/produção: Sempre utilize as URLs do seu domínio e revise se estão corretas.
• Validação e segurança: URLs válidas garantem a experiência adequada do cliente ao finalizar, cancelar ou quando o checkout expirar.

Boas práticas

• Altere os campos "successUrl", "cancelUrl" e "expiredUrl" para as rotas reais do seu site, onde o cliente será informado sobre o status da compra.
• Teste o fluxo completo após salvar as URLs, garantindo que o redirecionamento está funcionando corretamente.
• Nunca use exemplos como "https://example.com/asaas/checkout/expired" em produção.