Crie um Checkout para cartão de crédito

Crie um Checkout para receber pagamentos com cartão de crédito à vista ou parcelado em uma página hospedada pelo Asaas.

Antes de começar

Antes de criar o Checkout:

• defina se o pagamento será à vista, parcelado ou oferecerá as duas opções;
• defina os itens e valores da venda;
• prepare as URLs de sucesso, cancelamento e expiração;
• configure os Webhooks de Checkout;
• decida se os dados do cliente serão enviados pela aplicação ou preenchidos pelo pagador.

Escolha o tipo de cobrança

Em todos os casos, utilize:

{
  "billingTypes": ["CREDIT_CARD"]
}

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Criar o pedido"] --> B{"Permitir parcelamento?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Configurar INSTALLMENT"]
    BNao --> D["Configurar DETACHED"]

    C --> E["Criar o Checkout"]
    D --> E

    E --> F["Armazenar o ID"]
    F --> G["Disponibilizar o link"]
    G --> H["Receber o Webhook"]
    H --> I["Atualizar o pedido"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

1. Crie um pagamento à vista

Utilize:

POST /v3/checkouts

Exemplo:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado",
    "successUrl": "https://meusite.com/sucesso"
  },
  "items": [
    {
      "name": "Consultoria Financeira",
      "description": "Sessão única de consultoria",
      "quantity": 1,
      "value": 150.00
    }
  ]
}

Com chargeTypes = DETACHED, o Checkout disponibiliza o pagamento único no cartão de crédito.

2. Permita o parcelamento

Para oferecer parcelamento, utilize INSTALLMENT e informe o limite em installment:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["INSTALLMENT"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://meusite.com/cancelado",
    "expiredUrl": "https://meusite.com/expirado",
    "successUrl": "https://meusite.com/sucesso"
  },
  "items": [
    {
      "name": "Camiseta",
      "description": "Camiseta preta",
      "quantity": 2,
      "value": 100.00
    }
  ],
  "installment": {
    "maxInstallmentCount": 6
  }
}

Nesse exemplo, o Checkout permite parcelar o valor em até 6 vezes.

maxInstallmentCount aceita valores de 1 a 21.

Se quiser disponibilizar pagamento à vista e parcelado no mesmo Checkout, informe:

{
  "chargeTypes": ["DETACHED", "INSTALLMENT"],
  "installment": {
    "maxInstallmentCount": 6
  }
}

Consulte o endpoint Criar novo checkout.

Resultado esperado

A API retorna o identificador do Checkout.

Armazene o id para montar o link que será disponibilizado ao pagador.

3. Disponibilize o Checkout

Use o ID retornado para montar a URL do Checkout e redirecionar o pagador.

Consulte Link do checkout e redirecionamento do cliente.

O pagador informará os dados do cartão diretamente na página hospedada pelo Asaas.

Se sua aplicação já possuir os dados cadastrais do cliente, consulte Como informar os dados do cliente.

4. Confirme o pagamento por Webhook

A criação do Checkout não confirma o pagamento.

Utilize:

CHECKOUT_PAID

para atualizar o pedido quando o Checkout for pago.

Também trate CHECKOUT_CANCELED e CHECKOUT_EXPIRED quando esses estados afetarem sua jornada.

Consulte os Eventos para Checkout.

Erros comuns

Se o Checkout não for criado, verifique:

• se CREDIT_CARD foi informado em billingTypes;
• se chargeTypes corresponde ao fluxo escolhido;
• se installment foi enviado quando utilizar INSTALLMENT;
• se maxInstallmentCount está entre 1 e 21;
• se callback e items foram informados corretamente.

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
• Crie um Checkout com Assinatura
• Configure Split de Pagamento
• Consulte o FAQ do Asaas Checkout