Checkout Guide

Check out the Checkout guide for more information.

This endpoint is responsible for creating a new Asaas Checkout, allowing you to provide a hosted payment page where the payer can complete a payment using the configured payment methods.

Checkout centralizes the entire payment experience into a single URL, eliminating the need for your application to implement its own payment data collection interface.

After the Checkout is created, the API returns the information required to make it available to the payer.

When to use

This endpoint is recommended when your application needs to:

• provide an Asaas-hosted payment page;
• accept multiple payment methods within a single payment flow;
• create one-time, installment, or recurring charges through Checkout;
• reduce the implementation effort of custom payment interfaces;
• provide a payment experience already handled by Asaas.

Main request parameters

Some parameters play a key role in the Checkout behavior:

• billingTypes — defines which payment methods will be available to the payer.
• chargeTypes — determines whether the Checkout will create one-time charges, installment payments, or subscriptions.
• minutesToExpire — defines how long the Checkout remains available before expiring.
• items — products or services displayed during the payment process.
• customerData — payer information used during Checkout.
• callback — configures the automatic redirection after the payment is completed.
• externalReference — identifier of the Checkout in your own system.
• subscription — required when the Checkout creates subscriptions (RECURRENT).
• installment — required when the Checkout supports installment payments (INSTALLMENT).
• splits — defines how payment amounts will be distributed between accounts, when applicable.

Important business rules

The Checkout behavior depends directly on the combination of charge types and payment methods provided.

Some important rules include:

• at least one payment method must be specified in billingTypes;
• at least one charge type must be specified in chargeTypes;
• the subscription object is required when the Checkout creates recurring charges (RECURRENT);
• the installment object must be provided when the Checkout allows installment payments (INSTALLMENT);
• if Payment Split is used, the split configuration must be provided through splits.

If these dependencies are not met, the API may reject the request.

How the flow works

In a typical integration, the Checkout creation flow follows this journey:

Create Checkout
        ↓
Receive Checkout URL
        ↓
Send URL to the payer
        ↓
Payer completes payment
        ↓
Asaas processes the payment
        ↓
Webhook reports the result
        ↓
Application updates the status

Although the Checkout creation response is synchronous, the payment result occurs later and should be tracked through Webhook events.

Important behaviors

After the Checkout is created:

• the Checkout URL can be shared with the payer;
• the Checkout remains available until it expires;
• the payment may occur after the Checkout is created;
• the payment status should be monitored through the API or Webhooks;
• different payment methods may have different confirmation times.

This endpoint only creates the Checkout. Payment confirmation depends on the payer completing the payment.

Best practices

Operational impacts

Creating a Checkout only starts the payment journey.

Payment confirmation depends on the payer completing the payment and may occur asynchronously, especially for Pix and bank slip payments.

For this reason, your integration should properly process the Webhooks sent by Asaas to keep the payment status synchronized with your application.

Next steps

After creating a Checkout, integrations typically proceed to:

• Webhook configuration.
• Checkout events.
• Retrieve a Checkout.