DiscordStatus
Guias / Guides

Checkout for Pix

Example payload and integration flow for creating a standalone checkout with Pix payment, expiration, and redirect URLs.

Create a standalone checkout to receive a payment via Pix, define when the link expires, and redirect the customer back to your site.

Use this checkout type when you sell a product or service with a single payment, such as a course, ticket, e-commerce order, or one-time charge. The customer accesses the checkout link, pays with Pix, and returns to the configured URL based on the journey outcome.

Before You Begin

  1. Define your site's URLs for success, cancellation, and expiration scenarios.
  2. List the items being charged, including name, quantity, and value.
  3. Use customerData if you want to pre-fill customer information when creating the checkout.

Integration Flow

  1. Build the payload with billingTypes, chargeTypes, minutesToExpire, callback, and items.
  2. Send the payload in the checkout creation flow via the API.
  3. After the API returns the checkout ID, use that ID to display or share the payment link with the customer.
  4. Direct the customer to the checkout to complete the Pix payment.
  5. Handle the customer's return via the URL configured in successUrl, cancelUrl, or expiredUrl.

Example Payload

Use this JSON body when creating the checkout:

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

This payload creates a checkout with:

  • Pix payment
  • Standalone charge with chargeTypes set to DETACHED
  • Link valid for 60 minutes
  • A product called "Marketing Course" valued at R$ 297.00
  • Redirect to your site after success, cancellation, or expiration

Main Parameters

FieldTypeRequiredDescription
billingTypesarray of stringsYesDefines the payment methods accepted at checkout. Use ["PIX"] to accept Pix.
chargeTypesarray of stringsYesDefines the charge type. Use ["DETACHED"] for a standalone charge.
minutesToExpirenumberYesDefines how many minutes the checkout link remains valid. In the example, 60 equals 1 hour.
callbackobjectYes, when you need to redirect the customerGroups the URLs where the customer will be sent after success, cancellation, or expiration.
callback.cancelUrlstringYes, within callbackURL to redirect the customer when they cancel or abandon the journey through the cancellation flow.
callback.expiredUrlstringYes, within callbackURL to redirect the customer when the checkout link has expired.
callback.successUrlstringYes, within callbackURL to redirect the customer after successful checkout completion.
itemsarray of objectsYesDefines what you are selling. Include at least one item.
items[].namestringYesName of the product or service displayed at checkout.
items[].descriptionstringNoAdditional description of the item.
items[].quantitynumberYesQuantity of the item being sold.
items[].valuenumberYesUnit price of the item in BRL. In the example, 297.00 represents R$ 297.00.

Important Behaviors

  • The link becomes invalid after the period defined in minutesToExpire.
  • If the customer accesses an expired checkout, use expiredUrl to explain the next step, such as generating a new checkout.
  • If the customer cancels the journey, use cancelUrl to allow them to try again or return to the cart.
  • If the checkout is completed successfully, use successUrl to show the order confirmation or post-payment instructions.
⚠️

Do not use this payload for subscriptions or installments without including the specific fields for those checkout types. For recurring charges, use the appropriate charge type described on the subscription page.

Best Practices

  • Create clear return pages for successUrl, cancelUrl, and expiredUrl, informing the customer of the purchase status and next action.
  • Validate that all items have name, quantity, and value before sending the payload.
  • Use values consistent with the cart or order saved in your system to avoid discrepancies between the checkout and the sale.
  • Generate a new checkout when the link expires, rather than reusing an old link.
  • Do not rely solely on browser redirects to reconcile orders; also handle events and confirmations in your payment flow.

Next Steps