Solve common Asaas Checkout errors

Use this page to identify failures in Checkout creation, redirection, and synchronization.

For the complete fields and schemas, see the Checkout creation reference.

Missing required fields

When a required field is not sent, the API may return:

{
  "errors": [
    {
      "code": "invalid_object",
      "description": "The items field must be provided."
    }
  ]
}

Before resending the request, check:

• billingTypes;
• chargeTypes;
• callback with cancelUrl, expiredUrl, and successUrl;
• items with name, quantity, and value.

items[].description is optional.

Some charge types have additional dependencies:

See the Create new checkout endpoint.

Authentication error

If the API returns HTTP 401, check whether:

• the access_token header was sent;
• the API Key is valid and active;
• the key belongs to the same environment as the URL used;
• there are no spaces or extra characters in the key.

Do not expose the API Key in the front end, source code, public logs, or repositories.

See Authentication.

Invalid callback URLs

The documentation examples may use fictitious URLs:

"cancelUrl": "https://example.com/asaas/checkout/cancel",
"expiredUrl": "https://example.com/asaas/checkout/expired",
"successUrl": "https://example.com/asaas/checkout/success"

Replace these URLs with the real routes of your application and test all three scenarios before using Checkout in Production.

successUrl controls the payer's redirect and does not confirm the payment.

See Checkout link and customer redirection.

Expired Checkout

minutesToExpire defines how long the Checkout remains available and accepts values between 10 and 1440 minutes.

When the Checkout expires, create a new Checkout if the payer still needs to complete the purchase.

Use expiredUrl to direct the payer to the corresponding flow in your application.

Unreconciled payment

Do not update the order just because the payer was directed to successUrl.

Use the Checkout events to synchronize the result:

Webhooks use at least once delivery, so the same event may be sent again.

Implement idempotency using the event id.

See the Events for Checkout.

Duplicate Checkout for the same order

Store the id returned at creation and associate it with the order in your system.

You can also use externalReference to relate the Checkout to the internal sale identifier.

Before recreating a Checkout after a failure in your application, check whether the first one was already created.

Test before Production

Use the Sandbox to validate:

• Checkout creation;
• redirects;
• expiration;
• Webhook processing;
• error handling.

The Sandbox account, API Key, and data are independent from Production.

See the Sandbox guide.

Next steps

• Implement Asaas Checkout
• See the Create new checkout endpoint
• Set up the link and redirection
• Track the Events for Checkout
• Test your integration in Sandbox
• See the Asaas Checkout FAQ