Asaas Checkout FAQ
Find quick answers about Checkout configuration, payment, expiration, redirection, and tracking.
To implement a specific flow, follow the guides indicated in each answer.
Which payment methods are available?
Checkout accepts:
PIX;CREDIT_CARD.
You can provide one or both in billingTypes.
To choose the flow, see Asaas Checkout.
Which charge types can be created?
The chargeTypes field accepts:
| Value | Use |
|---|---|
DETACHED | One-off payment |
INSTALLMENT | Installment payment |
RECURRENT | Recurring subscription |
INSTALLMENT requires the installment configuration and RECURRENT requires subscription.
See the Create new checkout endpoint.
Does creating the Checkout mean the payment was confirmed?
No.
Creating it starts the payment journey. The financial result occurs after the payer's action.
Use CHECKOUT_PAID to identify when the Checkout was paid.
Which statuses can a Checkout have?
A Checkout can have the following statuses:
| Status | Meaning |
|---|---|
ACTIVE | Available for payment |
PAID | Paid |
CANCELED | Canceled |
EXPIRED | Expired |
Prefer Webhooks to react to status changes instead of continuously querying the API.
Does successUrl confirm that the payment was approved?
successUrl confirm that the payment was approved?No.
successUrl, cancelUrl, and expiredUrl control the browser redirect.
Use Webhooks to confirm the Checkout result. Do not mark an order as paid just because the payer reached the successUrl.
See Checkout link and customer redirection.
How do I get the link that will be sent to the payer?
After creating the Checkout, use the id returned by the API to make the payment page available.
Building the link and the redirect are detailed in Checkout link and customer redirection.
How long is the Checkout available?
The minutesToExpire field defines the validity period and accepts values between 10 and 1440 minutes.
After expiration, the Checkout is no longer available for payment. If the payer still needs to complete the purchase, create a new Checkout.
Can I cancel a Checkout before it expires?
Yes.
Use:
POST /v3/checkouts/{id}/cancelAfter cancellation, track CHECKOUT_CANCELED to synchronize your application.
See the Cancel a checkout endpoint.
Can I send pre-filled customer data?
Yes.
Send customerData when your application already has the payer's data. If this information is not sent, the payer can fill it in during the Checkout.
See How to provide customer data.
Can I offer credit card installments?
Yes.
Use INSTALLMENT in chargeTypes and configure the installment object.
maxInstallmentCount accepts values between 1 and 21.
Can I create a subscription through Checkout?
Yes.
Use RECURRENT in chargeTypes and send the subscription object with the recurrence rules.
See Checkout with Subscription.
Can I use Payment Split?
Yes.
Include splits when creating the Checkout to distribute amounts among Asaas accounts.
The rules for fixed value, percentage, and settlement are detailed in Checkout with Payment Split.
How do I relate the Checkout to the order in my system?
Use externalReference to store the identifier of your application's order, cart, or contract.
The field accepts up to 200 characters.
Also keep the Checkout id associated with the same record to make reconciliation and support easier.
Can the same Webhook be received more than once?
Yes.
Webhooks use at least once delivery, so the same event may be resent.
Implement idempotency using the event id to avoid duplicate processing.
The main Checkout events are:
CHECKOUT_CREATED;CHECKOUT_PAID;CHECKOUT_CANCELED;CHECKOUT_EXPIRED.
Where can I check Checkout creation errors?
Validation errors may return HTTP 400, and authentication problems may return HTTP 401.
See Common Asaas Checkout errors to review required fields, authentication, callbacks, expiration, and reconciliation.
Next steps
Updated 2 days ago