What is an Intent?

The Intent object is a core grouping entity within the Carusell API. It represents a single payment-related event or business objective and acts as a container for one or more financial transactions — such as payments, refunds, or disbursements — that are logically connected to a single customer action or business workflow.

💡
Every transaction must belong to an Intent. You must first create an Intent, then associate one or more transactions with it. This ensures all related transactions are grouped together for easier tracking, reconciliation, and reporting.

📦 Container

Groups all related transactions under one business operation

🔍 Trackable

A single ID lets you track, manage, and reconcile every linked transaction

🔄 Stateful

Has its own lifecycle and status reflecting the progress of all underlying transactions

Key Use Cases

#	Use Case	Description
1	Payment Collection	Group the payment and any subsequent refunds or adjustments for a single purchase.
2	Multiple Payment Attempts	If a payment attempt is declined, a new attempt can be added under the same Intent — allowing seamless retries without losing the context of the original operation.
3	Partial Settlements or Split Payments	A payment may be completed in several parts (e.g. card + voucher + bank transfer). The Intent groups all these transactions for complete visibility.
4	Payouts / Disbursements	Organise multiple outbound payments under a single business process — such as payroll or mass payouts.
5	Non-native Refunds	When a refund to the original payment method isn't possible, disburse funds via an alternative method — linking the new transaction to the original payment.

Integration Scenarios

The Intent works the same way across both integration types. The only difference is which object you populate in the create request.

⚠️
An Intent contains either payments or disbursements — not both. The create endpoint is the same for both flows.


You provide	The full payment or disbursement details — payment method, instrument, amount, currency, payer/payee data
You build	The payment UX on your side
Object to populate	`payments` or `disbursements` array on the Intent
When transaction is created	Immediately, as part of the Intent creation request
Best for	Integrators who are PCI-compliant and want full control over the user experience
Supported methods	See the full list of supported payment methods (H2H)

Intent Lifecycle & Statuses

The Intent manages the full journey of its transactions — from creation through completion, including any updates or reversals.

Status	Description
`CREATED`	The Intent has been created, but no transactions have started processing yet.
`IN_PROGRESS`	At least one linked transaction is currently being processed.
`FINALIZED`	All linked transactions have reached their final statuses (succeeded, failed, declined, etc.).
`CANCELLED_BY_CLIENT`	Hosted Checkout only. Triggered when the payer returns to your store from the checkout form to change the order or amount. The current Intent is cancelled, all unfinished payments are cancelled where possible (note: some payment methods such as certain QR-based payments cannot be cancelled), and a new Intent must be created for the updated order.

📓
Re-finalisation
If a new transaction is added to an Intent that has already been finalised, the Intent status returns to IN_PROGRESS and will be finalised again once all transactions reach their final states.

What's Next

Create a new Intent

Build the create request for both Host-to-Host and Hosted Checkout

Get Intent details

Retrieve the current state of an Intent and all its linked transactions