Asaas Checkout

Create a payment page hosted by Asaas to sell products, services, subscriptions, or installment plans without building your own checkout screen.

When to use Asaas Checkout

Use Asaas Checkout when your application already has a purchase flow, but you want to direct the payer to a page hosted by Asaas to complete the payment.

This model is suitable for:

• selling on e-commerce and SaaS platforms;
• accepting Pix and card in a single flow;
• creating one-off, installment, or recurring charges;
• reducing the implementation effort of the payment interface;
• redirecting the payer back to your site upon completion, cancellation, or expiration of the checkout;
• using payment splits when the sale needs to distribute amounts between accounts.

Key concepts

Integration flow

1. Create the order in your system and generate an internal identifier.
2. Send a request to create the checkout with payment methods, charge type, items, customer data, and callback URLs.
3. Store the id, link, status, and externalReference returned by the API.
4. Redirect the payer to the checkout link.
5. Wait for the payer's action. Creating the checkout does not confirm payment.
6. Receive Webhook events to update the financial status in your system.
7. Use the externalReference to reconcile the received event with the original order.

Order created in your system
        ↓
Create Checkout on Asaas
        ↓
Receive Checkout link
        ↓
Redirect payer
        ↓
Payer completes, cancels, or lets it expire
        ↓
Webhook reports the result
        ↓
System updates the order

Example: creating a one-off checkout

Use this example to create a checkout with Pix and credit card for a one-off sale.

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/checkouts \
  --header 'accept: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "billingTypes": ["PIX", "CREDIT_CARD"],
    "chargeTypes": ["DETACHED"],
    "minutesToExpire": 60,
    "externalReference": "order-1001",
    "callback": {
      "successUrl": "https://example.com/asaas/checkout/success",
      "cancelUrl": "https://example.com/asaas/checkout/cancel",
      "expiredUrl": "https://example.com/asaas/checkout/expired"
    },
    "items": [
      {
        "externalReference": "product-001",
        "name": "T-shirt",
        "description": "Cotton t-shirt",
        "quantity": 2,
        "value": 100,
        "imageBase64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII="
      }
    ],
    "customerData": {
      "name": "John Doe",
      "cpfCnpj": "24971563792",
      "email": "[email protected]",
      "phone": "4738010919"
    }
  }'

Successful response:

{
  "id": "131ca662-56c8-4479-b5b3-fd61a413fce7",
  "link": "https://sandbox.asaas.com/checkoutSession/show/131ca662-56c8-4479-b5b3-fd61a413fce7",
  "status": "ACTIVE",
  "billingTypes": ["PIX", "CREDIT_CARD"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "externalReference": "order-1001"
}

After receiving this response, save the checkout id and redirect the payer to the link.

Important rules and behaviors

• Send at least one value in billingTypes and at least one value in chargeTypes.
• Configure subscription when using RECURRENT.
• Configure installment when using INSTALLMENT; maxInstallmentCount accepts values from 1 to 21.
• Use minutesToExpire between 10 and 1440 minutes.
• Creating the checkout returns a payment page, not a financial confirmation.
• The checkout can be ACTIVE, CANCELED, EXPIRED, or PAID.
• Pix and card payments may have different confirmation timelines and behaviors.
• Webhooks use at least once delivery (the same event may arrive more than once). Implement idempotency using the event identifier.

Error handling

The API may reject checkout creation when there is invalid data or incorrect authentication.

Validation error example:

{
  "errors": [
    {
      "code": "error_code",
      "description": "Error description"
    }
  ]
}

Invalid authentication example:

{
  "errors": [
    {
      "code": "invalid_access_token",
      "description": "The provided API key is invalid"
    }
  ]
}

Implementation best practices

• Save the externalReference along with the order to reconcile events, reports, and support.
• Log the final payload sent to the API in a secure environment to facilitate diagnosis of 400 errors.
• Do not mark the order as paid based solely on the redirect to successUrl.
• Process Webhooks idempotently to avoid duplication on resent events.
• Set an expiration time compatible with the payer's journey.
• Test in Sandbox first before releasing the checkout to production.

Related content

• Create new checkout
• Cancel a checkout
• Receive Asaas events at your Webhook endpoint
• Webhook events