Create a Checkout for credit card

Create a Checkout to receive credit card payments, in full or in installments, on a page hosted by Asaas.

Before you start

Before creating the Checkout:

• decide whether the payment will be in full, in installments, or offer both options;
• define the items and values of the sale;
• prepare the success, cancellation, and expiration URLs;
• configure the Checkout Webhooks;
• decide whether the customer data will be sent by the application or filled in by the payer.

Choose the charge type

In all cases, use:

{
  "billingTypes": ["CREDIT_CARD"]
}

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Create the order"] --> B{"Allow installments?"}

  B --> BSim(("Yes"))
  B --> BNao(("No"))

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

  C --> E["Create the Checkout"]
  D --> E

  E --> F["Store the ID"]
  F --> G["Make the link available"]
  G --> H["Receive the Webhook"]
  H --> I["Update the order"]

  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. Create a payment in full

Use:

POST /v3/checkouts

Example:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired",
    "successUrl": "https://mysite.com/success"
  },
  "items": [
    {
      "name": "Financial Consulting",
      "description": "Single consulting session",
      "quantity": 1,
      "value": 150.00
    }
  ]
}

With chargeTypes = DETACHED, the Checkout offers a single credit card payment.

2. Allow installments

To offer installments, use INSTALLMENT and set the limit in installment:

{
  "billingTypes": ["CREDIT_CARD"],
  "chargeTypes": ["INSTALLMENT"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired",
    "successUrl": "https://mysite.com/success"
  },
  "items": [
    {
      "name": "T-shirt",
      "description": "Black t-shirt",
      "quantity": 2,
      "value": 100.00
    }
  ],
  "installment": {
    "maxInstallmentCount": 6
  }
}

In this example, the Checkout allows the amount to be split into up to 6 installments.

maxInstallmentCount accepts values from 1 to 21.

If you want to offer payment in full and in installments in the same Checkout, send:

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

See the Create new checkout endpoint.

Expected result

The API returns the Checkout identifier.

Store the id to build the link that will be made available to the payer.

3. Make the Checkout available

Use the returned ID to build the Checkout URL and redirect the payer.

See Checkout link and customer redirection.

The payer will enter the card details directly on the page hosted by Asaas.

If your application already has the customer's registration data, see How to provide customer data.

4. Confirm the payment via Webhook

Creating the Checkout does not confirm the payment.

Use:

CHECKOUT_PAID

to update the order when the Checkout is paid.

Also handle CHECKOUT_CANCELED and CHECKOUT_EXPIRED when these statuses affect your journey.

See the Events for Checkout.

Common errors

If the Checkout is not created, check:

• whether CREDIT_CARD was provided in billingTypes;
• whether chargeTypes matches the chosen flow;
• whether installment was sent when using INSTALLMENT;
• whether maxInstallmentCount is between 1 and 21;
• whether callback and items were provided correctly.

For other scenarios, see Common errors and best practices.

Next steps

• Set up the link and redirection
• Track the Events for Checkout
• Provide customer data
• Create a Checkout with Subscription
• Set up Payment Split
• See the Asaas Checkout FAQ