Introduction - Asaas Checkout

Create an Asaas Checkout via API to sell products or services on a payment page hosted by Asaas.

When to Use It

Use Asaas Checkout when your application needs to generate a ready-made payment page without building the entire charge experience on your own website or app.

It is recommended for scenarios such as:

• selling a product or service with a one-time payment via Pix or credit card;
• sending a payment link to a customer after an e-commerce, CRM, or support order;
• starting a recurring subscription with automatic billing;
• splitting the received amount between different Asaas accounts using payment split;
• redirecting the customer to specific success, cancellation, or expiration pages.

Consider integrating directly with the charge endpoints when you need to control the entire payment experience within your application, apply very specific checkout rules, or create a journey that does not use the Asaas hosted screen.

Prerequisites

Before creating a Checkout, complete these steps:

1. Generate an access_token key following the authentication page.
2. Define the payment methods that will be accepted, such as Pix, credit card, or both.
3. Choose the charge type: one-time, installment, or recurring.
4. List the products or services being sold, including name, quantity, and value.
5. Create the URLs on your website for redirects in case of success, cancellation, and expiration.
6. Configure Webhooks if your application needs to track Checkout creation, payment, cancellation, or expiration.

Integration Flow

Follow this sequence to create and use a Checkout:

1. Build the creation payload. Provide billingTypes, chargeTypes, minutesToExpire, callback, and items.
2. Send the request to the API. Create the Checkout with a POST request to https://api.asaas.com/v3/checkouts.
3. Save the returned ID. A successful response returns a unique Checkout identifier.
4. Build the customer link. Use the returned ID in the URL https://asaas.com/checkoutSession/show?id=RETURNED_ID.
5. Direct the customer to the Checkout. Send the link via email, message, website, app, or another channel in your flow.
6. Handle the customer's return. Use successUrl, cancelUrl, and expiredUrl to display the appropriate next action.
7. Sync status via Webhook. Use Checkout events to confirm payment, cancellation, or expiration in your system.

Order created in the source system
↓
Your application creates the Checkout in the Asaas API
↓
The API returns the Checkout ID
↓
Your application builds and delivers the link to the customer
↓
Customer completes, cancels, or lets the link expire
↓
Customer is redirected to the configured URL
↓
Webhook notifies your application of the event

Essential Parameters

In the request body, you define the information that will be displayed and used in the Checkout journey.

⚠️ Warning
Use values consistent with the order saved in your system. Discrepancies in items, quantity, or value may cause incorrect reconciliation between the Checkout and the original sale.

Example: Creating a Checkout for Pix

This example creates a one-time charge via Pix, with a link valid for 60 minutes and return URLs for success, cancellation, and expiration.

curl --request POST \
  --url https://api.asaas.com/v3/checkouts \
  --header 'Content-Type: application/json' \
  --header 'access_token: YOUR_ACCESS_TOKEN' \
  --data '{
    "billingTypes": ["PIX"],
    "chargeTypes": ["DETACHED"],
    "minutesToExpire": 60,
    "callback": {
      "cancelUrl": "https://mywebsite.com/cancelled",
      "expiredUrl": "https://mywebsite.com/expired",
      "successUrl": "https://mywebsite.com/success"
    },
    "items": [
      {
        "name": "Marketing Course",
        "description": "Complete digital marketing course",
        "quantity": 1,
        "value": 297.00
      }
    ]
  }'

Expected response on a successful creation:

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

With the returned id, build the Checkout link:

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

Send this link to the customer or integrate it into your website's payment button.

Important Behaviors

• The link becomes invalid after the period defined in minutesToExpire.
• If the customer accesses an expired Checkout, redirect them to expiredUrl and offer a way to generate a new link.
• If the customer cancels the journey, redirect them to cancelUrl and allow a new attempt or return to cart.
• If the Checkout is successfully completed, redirect them to successUrl with order confirmation or post-payment instructions.
• If customerData is provided, identification and address fields may be pre-filled automatically on the Checkout screen.
• For recurring subscriptions, use chargeTypes with RECURRENT and send the subscription object with the recurrence rules.
• For payment split, send splits with the wallets and the fixed or percentage amounts that should receive part of the payment.
• Do not rely solely on browser redirection to confirm payment. Use Webhooks to keep the order status synchronized.

Error Handling and Best Practices

When developing your integration:

• test the complete flow in Sandbox before sending real links to customers;
• save the Checkout ID returned by the API for auditing, support, and reconciliation;
• create clear pages for successUrl, cancelUrl, and expiredUrl;
• implement idempotency in Webhook processing using the received event identifier;
• respond to Webhooks quickly and process internal rules in the background;
• monitor failures to avoid expired links, unreconciled orders, or duplicate events.

Operational Impacts

Creating a Checkout can initiate a real sale, generate a payment link, create a recurring subscription, or distribute amounts via split, depending on the payload sent.

Incorrect configurations can affect the charged amount, link validity, customer return experience, and financial reconciliation of the order. Therefore, validate the payload with real test data, monitor Checkout events, and record the identifiers returned by the API.

Next Steps

Refer to these resources to continue the implementation:

• Checkout for Pix — create a one-time Checkout with Pix, expiration, and return URLs.
• Checkout with Subscription (recurring) — configure recurring charges with RECURRENT.
• Checkout with Payment Split — split amounts between different Asaas wallets.
• Checkout link and customer redirect — build the final URL using the ID returned by the API.
• Events for Checkout — sync creation, payment, cancellation, and expiration via Webhooks.
• How to provide customer data — pre-fill customer data automatically in the Checkout.
• API Reference — check fields, responses, and rules for each endpoint.