Guia de Checkout

Confira o guia de Checkout para mais informações.

Endpoint responsável por criar um novo Checkout Asaas, permitindo disponibilizar uma página de pagamento hospedada pelo Asaas para que o pagador conclua uma cobrança utilizando as formas de pagamento configuradas.

O Checkout concentra toda a experiência de pagamento em uma única URL, dispensando que a aplicação implemente sua própria interface para coleta de dados de pagamento.

Após a criação, a API retorna as informações necessárias para disponibilizar o checkout ao pagador.

Quando utilizar

Este endpoint é recomendado quando sua aplicação deseja:

• disponibilizar uma página de pagamento hospedada pelo Asaas;
• aceitar múltiplas formas de pagamento em um único fluxo;
• criar cobranças avulsas, parceladas ou recorrentes através do Checkout;
• reduzir a implementação de interfaces próprias para pagamento;
• utilizar uma experiência de pagamento já preparada pelo Asaas.

Principais parâmetros da requisição

Alguns parâmetros possuem papel fundamental no comportamento do Checkout:

• billingTypes — define quais formas de pagamento estarão disponíveis ao pagador.
• chargeTypes — determina se o checkout criará cobranças avulsas, parceladas ou assinaturas.
• minutesToExpire — tempo de validade do checkout antes da expiração.
• items — produtos ou serviços apresentados durante o pagamento.
• customerData — informações do pagador utilizadas durante o checkout.
• callback — configura o redirecionamento automático após a conclusão do pagamento.
• externalReference — identificador do checkout no sistema de origem.
• subscription — obrigatório quando o checkout criar assinaturas (RECURRENT).
• installment — obrigatório quando o checkout permitir parcelamentos (INSTALLMENT).
• splits — define a distribuição automática dos valores entre contas, quando aplicável.

Regras de negócio importantes

O comportamento do Checkout depende diretamente da combinação entre os tipos de cobrança e as formas de pagamento informadas.

Algumas regras importantes:

• pelo menos uma forma de pagamento deve ser informada em billingTypes;
• pelo menos um tipo de cobrança deve ser informado em chargeTypes;
• o objeto subscription é obrigatório quando o checkout utilizar cobranças recorrentes (RECURRENT);
• o objeto installment deve ser enviado quando o checkout permitir parcelamentos (INSTALLMENT);
• caso utilize Split de Pagamentos, as regras de divisão devem ser informadas através de splits.

Caso essas dependências não sejam respeitadas, a requisição poderá ser recusada pela API.

Como funciona o fluxo

Em uma integração típica, a criação do Checkout segue a seguinte jornada:

Criar Checkout
        ↓
Receber URL do Checkout
        ↓
Enviar URL ao pagador
        ↓
Pagador realiza o pagamento
        ↓
Asaas processa a cobrança
        ↓
Webhook informa o resultado
        ↓
Aplicação atualiza o status

Embora a resposta da criação do Checkout seja síncrona, o resultado do pagamento ocorre posteriormente e deve ser acompanhado através dos eventos enviados por Webhook.

Comportamentos importantes

Após a criação do Checkout:

• a URL poderá ser compartilhada com o pagador;
• o Checkout permanecerá disponível até sua expiração;
• o pagamento poderá ocorrer em momento posterior à criação;
• o status financeiro deverá ser acompanhado através da API ou dos Webhooks;
• diferentes formas de pagamento podem gerar comportamentos distintos quanto ao prazo de confirmação.

O endpoint cria apenas o Checkout. A confirmação financeira depende da ação do pagador.

Boas práticas

Impactos operacionais

A criação do Checkout inicia apenas a jornada de pagamento.

A confirmação da cobrança depende da conclusão do pagamento pelo usuário e pode ocorrer de forma assíncrona, especialmente em pagamentos via Pix ou boleto.

Por esse motivo, recomenda-se que a integração trate corretamente os Webhooks enviados pelo Asaas para manter o status financeiro sincronizado com a aplicação.

Próximos passos

Após criar um Checkout, normalmente a integração segue para:

• Configuração de Webhooks.
• Eventos do Checkout.
• Recuperar um Checkout.