Implement Asaas Checkout

Create a Checkout via API, make the payment page available to the payer, and track the result via Webhook.

Before you start

Before creating the Checkout:

• decide whether you will accept Pix, credit card, or both;
• choose between a one-off, installment, or recurring charge;
• define the expiration time;
• prepare the items that will be shown to the payer;
• configure the success, cancellation, and expiration URLs;
• configure the Checkout Webhooks.

If you only need to understand which option fits your operation, see Asaas Checkout.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Create the order"] --> B["Create the Checkout"]
  B --> C["Store the ID"]
  C --> D["Build the link"]
  D --> E["Redirect the payer"]
  E --> F["Payer completes the journey"]
  F --> G["Receive the Webhook"]
  G --> H["Update the order"]

  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. Define the Checkout type

The billingTypes and chargeTypes fields define the main flow.

Some flows require additional settings:

• installment for installment payments;
• subscription for recurring payments;
• splits for Payment Split.

See the specific guide before building these payloads:

• Checkout for Pix
• Checkout for Credit Card
• Checkout with Subscription
• Checkout with Payment Split

2. Create the Checkout

Send a request to:

POST /v3/checkouts

Example of a one-off charge with Pix and credit card:

{
  "billingTypes": [
    "PIX",
    "CREDIT_CARD"
  ],
  "chargeTypes": [
    "DETACHED"
  ],
  "minutesToExpire": 60,
  "externalReference": "order-1001",
  "callback": {
    "successUrl": "https://mysite.com/success",
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired"
  },
  "items": [
    {
      "name": "Marketing Course",
      "description": "Complete digital marketing course",
      "quantity": 1,
      "value": 297.00
    }
  ]
}

minutesToExpire accepts values between 10 and 1440 minutes.

Use externalReference to relate the Checkout to the order, cart, or contract in your system.

See the Create new checkout endpoint.

Customer data

You can:

• provide customer, if the customer is already registered;
• send customerData to fill in the data directly;
• send neither and let the payer fill in the information at Checkout.

Do not send customer and customerData in the same request.

See How to provide customer data.

3. Store the ID

A successful creation returns the Checkout identifier:

{
  "id": "c7b1c696-b27b-4d3d-80b9-d1c018e387f8"
}

Store this ID along with the order in your system.

Expected result

With the id, your application can build the Checkout URL and make it available to the payer.

4. Build the Checkout link

Use the returned ID in this format:

https://asaas.com/checkoutSession/show?id=RETURNED_ID

Example:

https://asaas.com/checkoutSession/show?id=c7b1c696-b27b-4d3d-80b9-d1c018e387f8

Redirect the payer to this URL or share the link through the channel used in your journey.

See Checkout link and customer redirection.

5. Handle the payer's return

The callback object defines where the payer will be directed after the journey:

6. Track the Checkout via Webhook

Track the events:

See the Events for Checkout.

Common errors

If the Checkout is not created, check:

• whether billingTypes and chargeTypes were provided;
• whether minutesToExpire is between 10 and 1440;
• whether callback and items were filled in correctly;
• whether subscription was sent for RECURRENT;
• whether installment was sent when the Checkout uses INSTALLMENT;
• whether the API key belongs to the environment being used.

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
• See common Checkout errors
• See the Asaas Checkout FAQ