Payment Intents
A Payment Intent is instellix’s instruction to move money via a payment provider: charge a customer, refund a payment, or pay out an amount. It represents the collection attempt on the instellix side and is submitted to the connected PSP.
Payment Intents can be created automatically (via Payment Intent Tasks and open items) or manually from a document in the webportal.
Prerequisites
- At least one Customer Payment Account for the customer
- A configured Merchant Payment Account / Gateway and Payment Provider
- Payment Intent processing enabled for the tenant (see below)
Types
| Type | Typical use |
|---|---|
| CHARGING | Collect money (e.g. invoice) |
| REFUND | Return money for a previous charge (e.g. invoice correction) |
| PAYOUT | Pay out money (e.g. credit note) |
Statuses
| Status | Meaning |
|---|---|
| CREATED | Intent exists, processing not finished yet |
| IN_PROGRESS | Being processed / submitted toward the PSP |
| SUBMITTED | Successfully submitted to the PSP; waiting for final outcome |
| RETRY | Scheduled for an automatic retry after a recoverable failure |
| FAILED | Collection attempt failed (may still be retryable, or final) |
| CANCELLED | Cancelled; no further automatic processing |
| PROCESSED | Successfully completed |
For Stripe, intents in SUBMITTED may be polled periodically for an updated status. See Payment Provider Stripe.
Final Retry
When automatic retries are configured, each attempt can be marked as the final retry. In the Payment Intent overview you can filter and sort by Final Retry to find intents where no further automatic collection attempts will follow.
See also Payment Retry Configuration.
Payment Intent Tasks
A Payment Intent Task is the planning step before a Payment Intent. It is created from the open-item (OPOS) situation of a document and is updated when the open item changes (amount, assignments, etc.).
When the task’s due date is reached and the task is still valid, instellix creates the actual Payment Intent.
Task statuses
| Status | Meaning |
|---|---|
| WAITING_FOR_DUE_DATE | Planned; Payment Intent will be created when due |
| PROCESSED | Payment Intent was created |
| FAILED | Creation of the Payment Intent failed |
| CANCELLED | Task cancelled (e.g. open item changed so the planned charge is no longer valid) |
When tasks are used
Typical case: charging on due date. The task holds the planned amount and CPA until due date; then the Payment Intent is created.
Tasks can be enabled/disabled for the tenant (automatic creation and updates from OPOS). If you enable tasks for a tenant that already has open items, not all historical cases get tasks retroactively — new/changed open items create tasks going forward; older cases may need a manual Payment Intent.
You can update a task (for example the Customer Payment Account) while it is still waiting — useful when the payment method changes after the document exists but before charging runs.
Replace failed charges when the payment method changes
When you create or update a Customer Payment Account, you can replace open charging attempts for that customer with the account you just saved. Without this option, creating or updating an account does not change existing Payment Intents.
The option applies to charging Payment Intents of the debtor, including intents on other Customer Payment Accounts and other merchant accounts. The new intents use the account from this create or update.
The Customer Payment Account stored on contracts and orders is left unchanged. Set that reference separately when future invoices should use the new account.
Replacement runs after the account is saved.
What is replaced
Only charging attempts whose open item (OPOS case) is still unbalanced are replaced.
| Payment Intent status when you save the account | Result |
|---|---|
| FAILED, RETRY | Cancelled. A new charging Payment Intent is created on the target account. This also applies when the intent has already reached its final retry. |
| CREATED, IN_PROGRESS, SUBMITTED | Left running at the provider. If it later fails or moves to retry, it is cancelled and replaced once, as long as the open item is still unbalanced. If it is processed or cancelled, no new intent is created. |
If the open item is balanced by the time a running intent fails, nothing is replaced.
Refunds stay on the Customer Payment Account of the original payment.
A replaced Payment Intent keeps the amount of the original Payment Intent. If the open-item balance changes in the meantime, the new charge still uses that original amount.
Payment Intent Tasks that are still waiting for the due date are updated to the target account.
In the webportal
Go to: Billing > Customers > Customer Overview, open the customer, then Customer payment accounts.
On create and on edit, the toggle Replace failed payment intents for this debtor is off by default. Turn it on to run the replacement described above. Leave it off to save the account only.
Via API
Pass the query parameter on create or update. Omit it to save the account without replacing payment intents.
POST /v2/customer-payment-accounts?action=replaceFailedPaymentIntents
PUT /v2/customer-payment-accounts/{customerPaymentAccountIdent}?action=replaceFailedPaymentIntents
| Parameter | Required | Value |
|---|---|---|
action | No | replaceFailedPaymentIntents |
See Create a CustomerPaymentAccount and Update a CustomerPaymentAccount.
Payment Intents in the webportal
Overview
Go to: Payment > Payment Intents
The overview shows Payment Intents and surfaces planned / failed Payment Intent Tasks (for example via summary widgets with counts and links into filtered lists):
- Planned payment intent tasks (
WAITING_FOR_DUE_DATE) - Failed payment intent tasks (
FAILED)
Use the table filters and sorting to work operationally with collection attempts. Available filters include status and Final Retry (Yes / No), so you can focus on intents that will not be retried automatically anymore.
Open a row to see details (amounts, CPA, merchant account, responses from the PSP, retry information, linked payment transaction where available).
Actions on a Payment Intent
Depending on status and permissions:
- Retry — for failed intents that can be retried (also available via API)
- Cancel — for failed intents that should not be processed further (also available via API)
Automatic retries are controlled by the provider Retry Strategy; manual retry is for operator-driven follow-up.
Create a Payment Intent manually
- Open the document (invoice, credit note, deposit invoice, or deposit credit note):
Billing > Documents (or via the customer details page) - Click Create payment intent
- Enter the amount and select the Customer Payment Account
- Select the type according to the document (Charging / Refund / Payout)
- Optionally add a statement descriptor
- Save to start processing
On the document details page
Document details include tabs for related payment objects, including:
- Payment Intent Tasks — planned / related tasks for this document
- Payment Intents — intents already created for this document
This lets you jump from the invoice to the planned charge or to failed/successful intents without searching the global overview.
Enable processing
Two related switches control automation:
| Setting | Effect |
|---|---|
| Payment Intent processing | If disabled, existing and new Payment Intents are not processed further by instellix |
| Payment Intent Task processing | If disabled, tasks are not created/updated automatically from open items |
Enable these only when full-service charging (or the relevant payment setup) is configured for the tenant.
Reporting
Payment Intents are available as a Data Area in Data Reports / Scheduled Reports (from the release that introduced the report; historical data may only start from that date).
Related articles
Updated 9 days ago