Crie um Checkout para Pix

Crie um Checkout avulso para receber um pagamento via Pix em uma página hospedada pelo Asaas.

Utilize billingTypes = PIX e chargeTypes = DETACHED para esse fluxo.

Antes de começar

Antes de criar o Checkout:

• defina os itens e valores da venda;
• prepare as URLs de sucesso, cancelamento e expiração;
• defina por quanto tempo o Checkout ficará disponível;
• configure os Webhooks de Checkout;
• decida se os dados do cliente serão enviados pela aplicação ou preenchidos pelo pagador.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Criar o pedido"] --> B["Criar o Checkout para Pix"]
    B --> C["Armazenar o ID"]
    C --> D["Montar o link"]
    D --> E["Redirecionar o pagador"]
    E --> F["Pagador realiza o Pix"]
    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. Crie o Checkout

Envie uma requisição para:

POST /v3/checkouts

Exemplo:

{
  "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
    }
  ]
}

Nesse exemplo:

• billingTypes = PIX disponibiliza o pagamento via Pix;
• chargeTypes = DETACHED cria uma cobrança avulsa;
• minutesToExpire = 60 mantém o Checkout disponível por 60 minutos;
• callback define as URLs de retorno;
• items identifica o que está sendo vendido.

minutesToExpire aceita valores entre 10 e 1440 minutos.

Consulte o endpoint Criar novo checkout.

2. 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 da sua aplicação.

Resultado esperado

Com o id retornado, monte a URL que será disponibilizada ao pagador.

3. Disponibilize o Checkout

Utilize o ID 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.

4. Trate o retorno do pagador

O callback define o redirecionamento após a jornada:

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

O redirecionamento não deve ser utilizado como confirmação financeira.

5. Confirme o pagamento por Webhook

Utilize os eventos de Checkout para sincronizar o pedido com sua aplicação.

Para confirmar a conclusão financeira, trate:

CHECKOUT_PAID

Também utilize CHECKOUT_CANCELED e CHECKOUT_EXPIRED quando precisar encerrar ou atualizar pedidos que não foram pagos.

Consulte os Eventos para Checkout.

Prefira Webhooks a consultas periódicas para acompanhar mudanças de estado. Os eventos utilizam entrega at least once, portanto processe-os de forma idempotente utilizando o id do evento.

Dados do cliente

Se sua aplicação já possuir os dados do pagador, eles podem ser enviados na criação do Checkout.

Caso contrário, o pagador poderá informá-los diretamente na página.

Consulte Como informar os dados do cliente.

Próximos passos

• Configure o link e o redirecionamento
• Acompanhe os Eventos para Checkout
• Informe os dados do cliente
• Implemente o Checkout para Cartão de Crédito
• Consulte erros comuns do Checkout
• Consulte o FAQ do Asaas Checkout