Payment Method Definition

📓
displayedPaymentMethods
displayedPaymentMethods defines which payment methods are shown to the payer on the Hosted Checkout form. It is the Hosted Checkout alternative to paymentMethodName, which is used in Host-to-Host integrations.
Provide this parameter in paymentIntent.formDetails.displayedPaymentMethods.
To make PIX available on the checkout form, include the PIX value. If PIX is the only value in the array, the payment-method selection step is skipped and the payer is taken directly to the PIX flow.

Payment Method Features

Feature	Value
Country	Brazil
Processing Currencies	BRL
Payments	Yes
*-- Min per transaction amount*	0.10 BRL, unless another limit is defined in your contract
*-- Max per transaction amount*	50,000.00 BRL, unless another limit is defined in your contract
Refunds	Full & Partial
Chargebacks	No

Workflow

Create an Intent with useCheckoutForm set to true and include PIX in paymentIntent.formDetails.displayedPaymentMethods.
Receive the Hosted Checkout URL in paymentIntent.additionalData.url.
Redirect the payer to the returned URL.
The checkout form collects the payer information required for PIX, including the payer's name and valid CPF or CNPJ details.
The platform creates a PIX payment and displays its QR code and PIX Copy and Paste value on the checkout form.
The payer scans the QR code or copies the PIX payload into a PIX-enabled banking or wallet application and confirms the transfer.
Wait for the payment webhook. Treat the payment as successful only when its status becomes CAPTURED.

⚠️
The synchronous Intent response confirms that the Hosted Checkout session was created. It does not create a successful PIX payment and does not confirm that the payer completed the transfer.
The initial response contains the URL of the Carusell Hosted Checkout form, not the PIX Copy and Paste payload. PIX payment data is created and displayed later, inside the checkout flow.

Create Intent Request

Specifics

We use one unified Intent creation request for all supported payment methods: POST /processing/api/v1/intents.

The overall structure is the same, but some fields change depending on the integration type: Host-to-Host or Hosted Checkout.

For Host-to-Host, complete the Payment object.

For Hosted Checkout, complete the PaymentIntent object.

For PIX Hosted Checkout:

Set useCheckoutForm to true.

Provide paymentIntent instead of payments.

Include PIX in paymentIntent.formDetails.displayedPaymentMethods.

Do not send paymentMethodName, paymentInstrument, or PIX incomingDetails in the initial Intent request.

The Hosted Checkout form collects the payer's name and CPF or CNPJ details before creating the PIX payment.

paymentIntent.submittedAmount.currency can be BRL or another supported currency when FX conversion is enabled. The PIX payment itself is authorised in BRL.

Provide a meaningful paymentIntent.description. It is used as the payment reason or order title when the PIX payment is created. Generic or missing transaction context may negatively affect payment conversion.

Provide paymentIntent.webhookUrl and wait for payment status updates instead of treating the Intent creation response as confirmation of payment.

'Intent' vs 'Payment' vs 'PaymentIntent'

Some objects and parameters in this API may appear similar, but they represent different concepts and are used in different integration scenarios. The explanation below clarifies the purpose of each term.

Term	Meaning
Intent	A universal top-level container for transaction-related operations. Depending on the integration scenario, it may contain objects such as `Payment`, `PaymentIntent`, or other transaction types.
Payment	Used in Host-to-Host integrations. You provide the payment method, payment instrument, amount, currency, and payer details upfront because the payment flow is handled on your side. For PIX Host-to-Host, the synchronous response contains the PIX Copy and Paste payload and QR image.
PaymentIntent	Used in Hosted Checkout integrations. It contains the order details and checkout configuration, but not the full PIX payment instrument data. The actual `Payment` object is created later, when the payer provides the required information and starts the PIX payment on the checkout form. Multiple payment attempts may occur within one `Intent`. Each attempt follows the rules and configuration defined in the corresponding `PaymentIntent`.

Request/Response Description

Request Description

{
  "clientReferenceId": "order-20260909-0001",
  "useCheckoutForm": true,
  "paymentIntent": {
    "formDetails": {
      "displayedPaymentMethods": ["PIX"],
      "backToStoreRedirectUrl": "https://merchant.example.com/orders/order-20260909-0001"
    },
    "submittedAmount": {
      "value": 100.00,
      "currency": "BRL"
    },
    "description": "Order 20260909-0001",
    "webhookUrl": "https://merchant.example.com/webhooks/payments"
  }
}

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	Order or Intent reference in the merchant system.
`useCheckoutForm`	Boolean	`Conditional`	Optional in the general Intent contract. Must be set to `true` when using Hosted Checkout.
`paymentIntent`	Object	`Conditional`	Optional in the general Intent contract. Must be provided when using Hosted Checkout. Do not send a `payments` array for the flow described on this page.
`description`	String	`Optional`	Intent-level order description. It can be used as a fallback outside the PIX-specific `paymentIntent.description` contract.
`merchant`	Object	`Optional`	Merchant information. Provide it when merchant details must be associated with the Intent or displayed on the checkout form according to your configuration.

paymentIntent

Parameter	Type	Required	Description
`formDetails`	Object	`Required`	Checkout-form configuration. Required for Carusell Hosted Checkout.
`submittedAmount`	Object	`Required`	Order amount and submitted currency.
`authorizationAmount`	Object	`Optional`	Authorisation amount and currency when these are supplied explicitly under an agreed FX flow. For PIX, the authorisation currency must be `BRL`. Do not send this object unless the FX flow is enabled for you.
`description`	String	`Required`	Meaningful payment reason or order title. The value is used when the checkout creates the PIX payment.
`webhookUrl`	String	`Required`	HTTPS URL to which payment status change webhooks for payments created within the Intent will be sent.

formDetails

Parameter	Type	Required	Description
`template`	String	`Optional`	Name of a checkout template configured for the settlement account. If omitted, the default template is used.
`displayedPaymentMethods`	Array of Strings	`Conditional`	Include `PIX` to make PIX available on the checkout form. If only `PIX` is provided, the payment-method selection step is skipped. If omitted, the form shows the methods available under the account configuration.
`backToStoreRedirectUrl`	String	`Optional`	HTTPS URL to which the payer can return after leaving or completing the checkout flow. The Back to Store control is unavailable when this parameter is omitted.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Submitted order amount. The applicable PIX limit is normally from `0.10` to `50,000.00` BRL unless another limit is defined in your contract.
`currency`	String	`Required`	Submitted currency in ISO 4217 alpha-3 format. Use `BRL` when no FX conversion is required. Another supported currency may be used when FX is enabled.

authorizationAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Explicit PIX authorisation amount. Supply it only as part of an agreed FX flow.
`currency`	String	`Required`	Authorisation currency in ISO 4217 alpha-3 format. For PIX, the value must be `BRL`.

merchant

Parameter	Type	Required	Description
`name`	String	`Optional`	Store name that may be displayed on the checkout form when this presentation is configured.
`website`	String	`Optional`	Merchant website associated with the Intent.

Response Description

{
  "intentId": "232510340021612544",
  "checkoutForm": true,
  "paymentIntent": {
    "intentSessionId": "232510340080332800",
    "backToStoreRedirectUrl": "https://merchant.example.com/orders/order-20260909-0001",
    "displayedPaymentMethods": ["PIX"],
    "submittedAmount": {
      "value": 100.00,
      "currency": "BRL"
    },
    "description": "Order 20260909-0001",
    "webhookUrl": "https://merchant.example.com/webhooks/payments",
    "additionalData": {
      "url": "https://checkout.carusell.world/session/232510340080332800",
      "expirationDateTime": "2026-09-09T14:20:00Z"
    }
  },
  "clientReferenceIntentId": "order-20260909-0001",
  "processingStatusCode": "CODE_PI0000",
  "intentStatus": "CREATED"
}

📓
The paymentIntent object is flattened in the response. Checkout-form fields such as backToStoreRedirectUrl and displayedPaymentMethods are returned directly under paymentIntent, not inside formDetails. The request's template field is not echoed back.
The response does not contain a payments array because the payer has not yet created a PIX payment. A Payment is created later from the Hosted Checkout session.

Top-Level Response Parameters

Parameter	Type	Required	Description
`intentId`	String	`Required`	Unique identifier of the Intent in our platform.
`checkoutForm`	Boolean	`Required`	`true` when the response contains a Hosted Checkout session.
`paymentIntent`	Object	`Conditional`	Required in a successful Hosted Checkout Intent response.
`clientReferenceIntentId`	String	`Required`	Merchant's Intent reference returned from `clientReferenceId` in the request.
`merchant`	Object	`Optional`	Merchant information returned when it was provided in the request.
`processingStatusCode`	String	`Required`	Intent processing status code. `CODE_PI0000` indicates successful Intent processing.
`statusMessage`	String	`Optional`	Processing status message, normally returned when an error occurs.
`description`	String	`Optional`	Intent-level description returned when it was supplied in the request.
`intentStatus`	String	`Required`	Current Intent status. A newly created Hosted Checkout Intent normally has the `CREATED` status.

paymentIntent

Parameter	Type	Required	Description
`intentSessionId`	String	`Optional`	Internal identifier of the checkout session associated with the Payment Intent.
`backToStoreRedirectUrl`	String	`Required`	URL supplied in the request, or the platform response value used for the checkout's return-to-store behaviour.
`displayedPaymentMethods`	Array of Strings	`Optional`	Payment methods made available to the payer. For the PIX-only flow, the value is `["PIX"]`.
`submittedAmount`	Object	`Required`	Submitted order amount and currency returned from the request.
`description`	String	`Required`	Payment Intent description returned from the request.
`webhookUrl`	String	`Required`	Webhook URL for payments created within this Intent, returned from the request.
`additionalData`	Object	`Required`	Checkout access information, including the Hosted Checkout URL and session expiration.
`payer`	Object	`Optional`	Payer details when they were supplied in the request or otherwise associated with the Payment Intent. Payer data collected later may be returned through payment resources.
`payee`	Object	`Optional`	Payee details when applicable.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Submitted order amount returned from the request.
`currency`	String	`Required`	Submitted currency returned from the request. It may differ from the PIX authorisation currency when FX conversion is applied.

additionalData

Parameter	Type	Required	Description
`url`	String	`Required`	Carusell Hosted Checkout URL. Redirect the payer to this URL to continue the payment. It is not the PIX Copy and Paste payload and must not be displayed as a PIX QR code.
`expirationDateTime`	DateTime	`Optional`	Date and time when the checkout session expires, in ISO 8601 format. The default session lifetime is 20 minutes unless another value is configured for your account. Until expiry, the payer can access the form and may make multiple payment attempts. After expiry, create a new Intent if another attempt is required.

merchant

Parameter	Type	Required	Description
`name`	String	`Optional`	Store name returned from the request. It may be displayed on the checkout form when configured.
`website`	String	`Optional`	Merchant website returned from the request.

PIX Checkout Experience

📘
The payer completes all PIX-specific steps on the Carusell Hosted Checkout form. The merchant must redirect the payer to paymentIntent.additionalData.url; the merchant does not render the PIX QR code or Copy and Paste payload in this integration.

The checkout flow must request and validate the information required to create a PIX payment:

Information	Checkout behaviour
Payer first name	Collected on the checkout form and used to create the PIX payment.
Payer last name	Collected on the checkout form and used to create the PIX payment.
Document type	The payer selects `CPF` or `CNPJ`.
Document number	The payer provides a valid number matching the selected document type. CPF contains 11 digits and CNPJ contains 14 digits, excluding standard formatting punctuation.
Email	Optional. Collected only when required by the configured checkout experience.
Phone	Optional. Collected only when required by the configured checkout experience.

After the payment is created, the checkout form displays both representations of the same PIX payment:

a QR code for scanning from another device;
a PIX Copy and Paste value for use in a PIX-enabled banking or wallet application.

The payer must not modify the PIX payload, amount, CRC, or any other character in the Copy and Paste value.

Payment Statuses

Status	Meaning	Merchant action
`AUTHORIZATION_REQUESTED`	The PIX payment was created and is waiting for the payer to complete the transfer.	Wait for a webhook. Do not fulfil the order.
`CAPTURED`	The PIX transfer was successfully completed.	Fulfil the order.
`DECLINED`	The payment was rejected.	Do not fulfil the order. The payer may start another attempt while the checkout session remains active.
`CANCELLED`	The payment was cancelled or expired before completion.	Do not fulfil the order.
`ERROR`	A technical or processing error prevented the payment from completing.	Do not fulfil the order. Use the error fields for diagnostics and allow another attempt only when appropriate.

⚠️
A checkout session and a PIX payment have separate lifecycles. paymentIntent.additionalData.expirationDateTime describes the checkout session lifetime. A PIX payment created during that session has its own payment status and may expire independently.

Refunds

PIX payments completed through Hosted Checkout support the same refund flow as PIX payments created through Host-to-Host integration.

A refund can be created only after the PIX payment reaches CAPTURED.
Use the payment id received through the payment webhook or retrieved from the Intent or Payment API.
Create the refund with POST /api/v1/refunds.
Full and partial refunds are returned to the original PIX payment source.
Refund processing is asynchronous. Treat it as successful only when the refund reaches REFUNDED.

Webhooks

🔗
Payment status notifications

The platform sends payment webhooks to paymentIntent.webhookUrl whenever the status of a PIX payment created within the checkout session changes.

The synchronous Intent response only creates the checkout session. Fulfil the order only after receiving a payment with status CAPTURED.

A payer may make multiple payment attempts during the checkout session lifetime. Correlate each webhook by its platform payment ID and correlate the overall checkout flow by the Intent ID.

Webhooks may be delivered more than once. Process them idempotently.

If a webhook is delayed or missed, retrieve the Intent or Payment by ID to reconcile the latest state.

For more information about payment webhooks, see the dedicated page.