Asaas Checkout

Crie uma página de pagamento hospedada pelo Asaas para vender produtos, serviços, assinaturas ou parcelamentos sem construir uma tela própria de checkout.

Quando usar o Asaas Checkout

Use o Asaas Checkout quando sua aplicação já possui um fluxo de compra, mas você quer direcionar o pagador para uma página hospedada pelo Asaas para concluir o pagamento.

Esse modelo é indicado para:

• vender em e-commerces e plataformas SaaS;
• aceitar Pix e cartão em um único fluxo;
• criar cobranças avulsas, parceladas ou recorrentes;
• reduzir o esforço de implementação da interface de pagamento;
• redirecionar o pagador de volta ao seu site ao concluir, cancelar ou deixar o checkout expirar;
• usar split de pagamentos quando a venda precisar distribuir valores entre contas.

Conceitos principais

Fluxo de integração

1. Crie o pedido no seu sistema e gere um identificador interno.
2. Envie uma requisição para criar o checkout com formas de pagamento, tipo de cobrança, itens, dados do cliente e URLs de callback.
3. Armazene o id, o link, o status e o externalReference retornados pela API.
4. Redirecione o pagador para o link do checkout.
5. Aguarde a ação do pagador. A criação do checkout não confirma o pagamento.
6. Receba os eventos de Webhook para atualizar o status financeiro no seu sistema.
7. Use o externalReference para reconciliar o evento recebido com o pedido original.

Pedido criado no seu sistema
        ↓
Criar Checkout no Asaas
        ↓
Receber link do Checkout
        ↓
Redirecionar pagador
        ↓
Pagador conclui, cancela ou deixa expirar
        ↓
Webhook informa o resultado
        ↓
Sistema atualiza o pedido

Exemplo: criar um checkout avulso

Use este exemplo para criar um checkout com Pix e cartão de crédito para uma venda avulsa.

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/checkouts \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "billingTypes": ["PIX", "CREDIT_CARD"],
    "chargeTypes": ["DETACHED"],
    "minutesToExpire": 60,
    "externalReference": "pedido-1001",
    "callback": {
      "successUrl": "https://example.com/asaas/checkout/success",
      "cancelUrl": "https://example.com/asaas/checkout/cancel",
      "expiredUrl": "https://example.com/asaas/checkout/expired"
    },
    "items": [
      {
        "externalReference": "produto-001",
        "name": "Camiseta",
        "description": "Camiseta algodao",
        "quantity": 2,
        "value": 100,
        "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="
      }
    ],
    "customerData": {
      "name": "John Doe",
      "cpfCnpj": "24971563792",
      "email": "[email protected]",
      "phone": "4738010919"
    }
  }'

Resposta de sucesso:

{
  "id": "131ca662-56c8-4479-b5b3-fd61a413fce7",
  "link": "https://sandbox.asaas.com/checkoutSession/show/131ca662-56c8-4479-b5b3-fd61a413fce7",
  "status": "ACTIVE",
  "billingTypes": ["PIX", "CREDIT_CARD"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "externalReference": "pedido-1001"
}

Depois de receber essa resposta, salve o id do checkout e redirecione o pagador para o link.

Regras e comportamentos importantes

• Envie pelo menos um valor em billingTypes e pelo menos um valor em chargeTypes.
• Configure subscription quando usar RECURRENT.
• Configure installment quando usar INSTALLMENT; maxInstallmentCount aceita valores de 1 a 21.
• Use minutesToExpire entre 10 e 1440 minutos.
• A criação do checkout retorna uma página de pagamento, não uma confirmação financeira.
• O checkout pode ficar ACTIVE, CANCELED, EXPIRED ou PAID.
• Pagamentos por Pix e cartão podem ter prazos e comportamentos de confirmação diferentes.
• Webhooks usam entrega do tipo at least once (o mesmo evento pode chegar mais de uma vez). Implemente idempotência usando o identificador do evento.

Tratamento de erros

A API pode recusar a criação do checkout quando houver dados inválidos ou autenticação incorreta.

Exemplo de erro de validação:

{
  "errors": [
    {
      "code": "error_code",
      "description": "Error description"
    }
  ]
}

Exemplo de autenticação inválida:

{
  "errors": [
    {
      "code": "invalid_access_token",
      "description": "A chave de API fornecida é inválida"
    }
  ]
}

Boas práticas de implementação

• Salve o externalReference junto ao pedido para conciliar eventos, relatórios e suporte.
• Registre o payload final enviado à API em ambiente seguro para facilitar diagnóstico de erros 400.
• Não marque o pedido como pago usando apenas o redirecionamento para successUrl.
• Processe Webhooks de forma idempotente para evitar duplicidade em eventos reenviados.
• Defina um tempo de expiração compatível com a jornada do pagador.
• Teste primeiro em Sandbox antes de liberar o checkout em produção.

Conteúdos relacionados

• Criar novo checkout
• Cancelar um checkout
• Receba eventos do Asaas no seu endpoint de Webhook
• Eventos de Webhooks