Intent: Overview

What is an Intent?

The Intent object is a core grouping entity within our API, designed to represent a single payment-related event or business objective. An Intent 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 request to create a transaction of any type (payment, refund, disbursement, etc.) must reference an Intent.
This means you must first create an Intent, and then associate one or multiple transactions within it as required by your business process.
This approach ensures that all related transactions are grouped together for easier tracking, reconciliation, and reporting.

Key Use Cases

No	Name	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 for 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 and tracking.
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 method isn’t possible, disburse funds via an alternative payment method, linking the new transaction to the original payment.

Intent Lifecycle & Statuses

The Intent object manages the full journey of a payment/disbursement, from initial creation through completion, including any associated updates or reversals. An Intent can have the following statuses:

Status	Description
CREATED	The Intent has been created but no transactions have started processing
IN_PROGRESS	At least one linked transaction is in progress
FINALIZED	All linked transactions have reached their final statuses

💁
Note: If a new transaction is added to an Intent after it has been finalised, the Intent status will return to IN_PROGRESS and will be finalised again when all transactions are completed.

Intent Structure

The table below describes the general information an Intent can contain. These top-level fields provide overall context and grouping for all transactions (such as payments and disbursements) associated with the Intent.

Name	Description
Intent ID	The unique identifier assigned to your Intent.
Payments	Details of all payments that were successfully created under this Intent.
Disbursements	Details of all disbursements that were successfully created under this Intent.
Client Reference	The reference you provided for this Intent, useful for your own tracking or reconciliation.
Payment Creation Errors	Any payments that could not be created, along with error details.
Disbursement Creation Errors	Any disbursements that could not be created, along with error details.
Description	An optional text description of your Intent, as submitted in the request.
Intent Status	The current status of your Intent (for example: Created, In Progress, Finalized).