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). |
Updated about 21 hours ago