Implemente o Asaas Checkout

Crie um Checkout pela API, disponibilize a página de pagamento ao pagador e acompanhe o resultado por Webhook.

Antes de começar

Antes de criar o Checkout:

• defina se aceitará Pix, cartão de crédito ou ambos;
• escolha entre cobrança avulsa, parcelada ou recorrente;
• defina o tempo de expiração;
• prepare os itens que serão apresentados ao pagador;
• configure as URLs de sucesso, cancelamento e expiração;
• configure os Webhooks de Checkout.

Se precisar apenas entender qual modalidade atende à sua operação, consulte Asaas Checkout.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Criar o pedido"] --> B["Criar o Checkout"]
    B --> C["Armazenar o ID"]
    C --> D["Montar o link"]
    D --> E["Redirecionar o pagador"]
    E --> F["Pagador conclui a jornada"]
    F --> G["Receber o Webhook"]
    G --> H["Atualizar o pedido"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F,G validacao
    class H sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Defina o tipo de Checkout

Os campos billingTypes e chargeTypes definem o fluxo principal.

Alguns fluxos exigem configurações adicionais:

• installment para parcelamento;
• subscription para recorrência;
• splits para Split de Pagamentos.

Consulte o guia específico antes de montar esses payloads:

• Checkout para Pix
• Checkout para Cartão de Crédito
• Checkout com Assinatura
• Checkout com Split de Pagamento

2. Crie o Checkout

Envie uma requisição para:

POST /v3/checkouts

Exemplo de uma cobrança avulsa com Pix e cartão de crédito:

{
  "billingTypes": [
    "PIX",
    "CREDIT_CARD"
  ],
  "chargeTypes": [
    "DETACHED"
  ],
  "minutesToExpire": 60,
  "externalReference": "pedido-1001",
  "callback": {
    "successUrl": "https://meusite.com/sucesso",
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado"
  },
  "items": [
    {
      "name": "Curso de Marketing",
      "description": "Curso completo de marketing digital",
      "quantity": 1,
      "value": 297.00
    }
  ]
}

minutesToExpire aceita valores entre 10 e 1440 minutos.

Utilize externalReference para relacionar o Checkout ao pedido, carrinho ou contrato no seu sistema.

Consulte o endpoint Criar novo checkout.

Dados do cliente

Você pode:

• informar customer, caso o cliente já esteja cadastrado;
• enviar customerData para preencher os dados diretamente;
• não enviar nenhum deles e deixar o pagador preencher as informações no Checkout.

Não envie customer e customerData na mesma requisição.

Consulte Como informar os dados do cliente.

3. Armazene o ID

Uma criação bem-sucedida retorna o identificador do Checkout:

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

Armazene esse ID junto ao pedido no seu sistema.

Resultado esperado

Com o id, sua aplicação poderá montar a URL do Checkout e disponibilizá-la ao pagador.

4. Monte o link do Checkout

Utilize o ID retornado neste formato:

https://asaas.com/checkoutSession/show?id=ID_RETORNADO

Exemplo:

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

Redirecione o pagador para essa URL ou compartilhe o link pelo canal utilizado na sua jornada.

Consulte Link do checkout e redirecionamento do cliente.

5. Trate o retorno do pagador

O objeto callback define para onde o pagador será direcionado após a jornada:

6. Acompanhe o Checkout por Webhook

Acompanhe os eventos:

Consulte os Eventos para Checkout.

Erros comuns

Se o Checkout não for criado, verifique:

• se billingTypes e chargeTypes foram informados;
• se minutesToExpire está entre 10 e 1440;
• se callback e items foram preenchidos corretamente;
• se subscription foi enviado para RECURRENT;
• se installment foi enviado quando o Checkout utilizar INSTALLMENT;
• se a API key pertence ao ambiente utilizado.

Para outros cenários, consulte Erros comuns e boas práticas.

Próximos passos

• Configure o link e o redirecionamento
• Acompanhe os Eventos para Checkout
• Informe os dados do cliente
• Consulte erros comuns do Checkout
• Consulte o FAQ do Asaas Checkout