Create a Checkout for Pix

Create a one-off Checkout to receive a payment via Pix on a page hosted by Asaas.

Use billingTypes = PIX and chargeTypes = DETACHED for this flow.

Before you start

Before creating the Checkout:

• define the items and values of the sale;
• prepare the success, cancellation, and expiration URLs;
• define how long the Checkout will remain available;
• configure the Checkout Webhooks;
• decide whether the customer data will be sent by the application or filled in by the payer.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Create the order"] --> B["Create the Checkout for Pix"]
  B --> C["Store the ID"]
  C --> D["Build the link"]
  D --> E["Redirect the payer"]
  E --> F["Payer makes the Pix payment"]
  F --> G["Receive the Webhook"]
  G --> H["Update the order"]

  classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
  classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
  classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

  class A inicio
  class B,C,D,E,F,G validacao
  class H sucesso

  linkStyle default stroke:#94A3B8,stroke-width:2px

1. Create the Checkout

Send a request to:

POST /v3/checkouts

Example:

{
  "billingTypes": ["PIX"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired",
    "successUrl": "https://mysite.com/success"
  },
  "items": [
    {
      "name": "Marketing Course",
      "description": "Complete digital marketing course",
      "quantity": 1,
      "value": 297.00
    }
  ]
}

In this example:

• billingTypes = PIX enables payment via Pix;
• chargeTypes = DETACHED creates a one-off charge;
• minutesToExpire = 60 keeps the Checkout available for 60 minutes;
• callback defines the return URLs;
• items identifies what is being sold.

minutesToExpire accepts values between 10 and 1440 minutes.

See the Create new checkout endpoint.

2. Store the ID

A successful creation returns the Checkout identifier:

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

Store this ID along with the order in your application.

Expected result

With the returned id, build the URL that will be made available to the payer.

3. Make the Checkout available

Use the ID in this format:

https://asaas.com/checkoutSession/show?id=RETURNED_ID

Example:

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

Redirect the payer to this URL or share the link through the channel used in your journey.

See Checkout link and customer redirection.

4. Handle the payer's return

The callback defines the redirect after the journey:

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

The redirect must not be used as financial confirmation.

5. Confirm the payment via Webhook

Use the Checkout events to synchronize the order with your application.

To confirm financial completion, handle:

CHECKOUT_PAID

Also use CHECKOUT_CANCELED and CHECKOUT_EXPIRED when you need to close or update orders that were not paid.

See the Events for Checkout.

Prefer Webhooks over periodic queries to track status changes. Events use at least once delivery, so process them idempotently using the event id.

Customer data

If your application already has the payer's data, it can be sent when creating the Checkout.

Otherwise, the payer can provide it directly on the page.

See How to provide customer data.

Next steps

• Set up the link and redirection
• Track the Events for Checkout
• Provide customer data
• Implement Checkout for Credit Card
• See common Checkout errors
• See the Asaas Checkout FAQ