Payment lifecycle

A payment can move through several states between creation, customer checkout, confirmation, and settlement.

Understanding these states can help you determine what is happening with a payment, whether you use a ready-made integration or integrate directly with the ICEPAY Checkout API.

ICEPAY exposes two separate status fields. They describe different parts of the payment process and should be considered independently.

Field	Describes	Possible values
status	Where the payment is in its payment lifecycle	started, pending, completed, expired, cancelled
financialStatus	Whether the funds have been received	uncleared, cleared

Completed does not always mean cleared

A payment can have status: "completed" while its financialStatus is still "uncleared".

These values describe different parts of the payment process.

Using a ready-made integration?

If you use an ICEPAY integration for an e-commerce platform, most of the technical payment lifecycle is handled by the integration automatically.

You normally do not need to store ICEPAY statuses, process webhooks, or keep track of payment identifiers yourself.

This page is still useful for understanding the payment information shown in your store and ICEPAY Account.

Lifecycle at a glance

A typical payment moves through the following process:

1. The payment is created

   A payment starts with:

   {
     "status": "started",
     "financialStatus": "uncleared"
   }

2. The customer starts checkout

   The customer continues to ICEPAY Checkout or the selected payment method.

3. The payment is processed

   Some payment methods can return a result almost immediately.

   Others may temporarily place the payment in pending while the final result is being determined.

4. The payment result becomes available

   The payment can become completed, return to started, expire, or be cancelled depending on what happens during checkout.

5. The funds are received

   When the funds have been received and cleared, the financialStatus can change from uncleared to cleared.

Not every payment passes through every step in exactly the same way.

The exact lifecycle depends on the payment method and how quickly the payment provider can confirm the result.

Payment statuses

The status field describes where the payment is in its payment lifecycle.

started

The payment has been created and checkout can begin.

This is the initial state of every new payment.

pending

The payment is being processed, but the final result is not yet known.

Wait for another payment update before treating the payment as successful or unsuccessful.

completed

The payment flow has completed successfully.

The funds may still be uncleared, depending on the payment method.

expired

The payment was not completed within its configured lifetime.

Payments remain open for four hours by default unless a different expiry period was configured.

cancelled

The payment was cancelled and should no longer be considered an active payment attempt.

Payment status transitions

Payment statuses do not always move through a single linear sequence.

A payment that completes immediately can follow:

started → completed

A payment method that requires additional processing can follow:

started → pending → completed

If the payment attempt does not succeed, the payment can return to:

started → pending → started

A payment can also expire or be cancelled:

started → expired
started → cancelled

Late payment confirmations

An expired payment is usually no longer an active payment attempt.

There are, however, situations where the customer already entered an external payment environment before the ICEPAY payment expired.

For example, the customer may still be completing the payment with their bank when the payment reaches its expiry time.

A confirmation received afterwards can still result in:

expired → pending
expired → completed

A payment can still change after expiry

When reviewing a payment, always consider its latest status.

A payment that was previously shown as expired may receive a later update if the customer had already started the payment process.

Building a custom integration?

Do not treat expired as a state that can never change.

Continue processing valid webhook updates even when your application previously stored the payment as expired.

Financial status

The financialStatus field answers a different question:

Have the funds actually been received?

uncleared

The funds have not yet been confirmed as received.

Every newly created payment starts with this financial status.

cleared

The funds have been received and cleared.

This indicates that the financial side of the payment has been completed.

A payment can therefore be successfully completed while its funds are still uncleared:

{
  "status": "completed",
  "financialStatus": "uncleared"
}

Later, when the funds have been received:

{
  "status": "completed",
  "financialStatus": "cleared"
}

For some payment methods, confirmation of the customer’s payment and receipt of the funds do not happen at exactly the same time.

For payment methods where ICEPAY does not collect the funds, the financial status may remain uncleared.

When should an order be fulfilled?

Some payment methods guarantee settlement once the payment reaches completed. For these methods, you can fulfil the order even while financialStatus is still uncleared.

For payment methods without this guarantee, wait until financialStatus is cleared before fulfilling the order to ensure the funds have been received.

See Payment methods for each method’s Settlement details and guidance on whether to check financialStatus before fulfilling an order. That page also explains how financial status behaves for methods where ICEPAY does not collect the funds.

If you use a ready-made integration, this behaviour is generally handled by the integration and its configuration.

Building a custom integration?

If you process payment status updates yourself, always use the payment method reported by the latest verified payment state when determining whether funds have settled.

See Payment-method changes and redirect settings for implementation guidance.

Payment status and order status

The payment status in ICEPAY and the order status in your store are related, but they are not the same thing.

For example, your store might represent ICEPAY payment states like this:

ICEPAY payment state	Possible store order state
started	Awaiting payment
pending	Payment processing
completed + uncleared	Payment completed
completed + cleared	Paid
expired	Payment expired
cancelled	Payment cancelled

Order statuses can differ between platforms

The exact order status shown in your store depends on your e-commerce platform, the integration, and its configuration.

The examples above illustrate the general relationship and are not a fixed mapping used by every integration.

Keeping payment information up to date

After the customer enters checkout, two different mechanisms help keep the payment information synchronised.

Webhook

A server-to-server notification that communicates payment changes to the integration or application.

It does not depend on the customer’s browser returning to the store.

Customer return

The customer is redirected back to the store after leaving the payment flow.

This is mainly used to continue the customer’s checkout experience.

For merchants using a ready-made integration, these mechanisms normally work in the background.

Their purpose is to make sure the order in the store reflects the latest known payment state.

Using a ready-made integration?

The integration normally processes ICEPAY payment updates and updates the corresponding order in your store automatically.

You generally do not need to implement webhook handling yourself.

Customer return

The customer returning to your store should not by itself be considered proof that the payment succeeded.

The customer may return while the payment is still being processed, or the browser may never return even though the payment completed successfully.

For a merchant using a ready-made integration, the payment result page and order status are normally handled automatically.

Identifying a payment

Every ICEPAY payment has a unique payment key, for example:

pi-01j1ps8zf4jgnk0c3dnd477sp1

This key identifies the payment within ICEPAY.

Your own reference identifies the payment or order from your application’s perspective.

Using a ready-made integration?

The integration normally keeps track of the ICEPAY payment key and associates it with the corresponding order automatically.

You generally do not need to manage this identifier yourself.

Building a custom integration?

Store the ICEPAY payment key with your own payment record.

You will need it when retrieving the payment, processing payment updates, creating refunds, or performing other payment operations.

Multiple payment attempts

A customer may try to pay for the same order more than once.

For example:

1. The customer starts an iDEAL | Wero payment.
2. The customer cancels the payment or the attempt does not complete.
3. The customer returns to the store.
4. The customer chooses another payment method.
5. A new payment attempt is created.
6. The second payment completes successfully.

The order may remain the same, but multiple payment attempts can exist behind it.

Using a ready-made integration?

The integration normally keeps track of payment attempts for you.

Depending on your platform, information about previous attempts may be available in the order details or payment history.

Building a custom integration?

Consider storing payment attempts separately from the order itself.

One order can then reference multiple ICEPAY payment keys without losing the history of previous attempts.

Payment expiry

Payments remain open for four hours by default.

A different payment lifetime can be configured when creating the payment using expireAfter:

{
  "expireAfter": 1440
}

expireAfter is specified in minutes. In this example, the payment remains open for 24 hours.

Once the configured lifetime has passed, a payment that has not completed can move to expired.

Remember that a later payment confirmation may still be received when the customer had already entered an external payment flow before the payment expired.

Using a ready-made integration?

Payment expiry is generally managed by the integration.

You may still see an expired payment in your store or ICEPAY Account when a customer started checkout but did not finish the payment in time.

After completion

A completed payment can still be involved in other financial processes.

These can include:

• full or partial refunds;
• disputes and chargebacks;
• payment forwarding;
• settlement and reconciliation.

These processes are separate from the original payment lifecycle.

For example, creating a refund does not mean that the original payment stops being completed. The refund has its own lifecycle and status.

Refunds

Learn how full and partial refunds work.

Disputes & chargebacks

Understand what happens when a payment is disputed.

What this means for you

If you use a ready-made integration

In most cases, the integration handles the technical payment lifecycle for you.

The most important things to understand are:

• what started, pending, completed, expired, and cancelled mean;
• that a completed payment is not always financially cleared immediately;
• that some payment methods take longer to confirm than others;
• that the order status shown by your store can differ from the ICEPAY payment status;
• that payment updates can still arrive after the customer leaves checkout;
• that an order can have more than one payment attempt.

If an order appears to have an unexpected payment state, check the payment information in both your store and ICEPAY before taking manual action.

If you build a custom integration

Your integration should:

• store the ICEPAY payment key with the corresponding payment record;
• store status and financialStatus separately;
• use webhooks for backend payment updates;
• verify webhook signatures before processing them;
• process webhook updates idempotently;
• not rely on the customer’s browser redirect as confirmation of payment;
• keep your application’s order state separate from the ICEPAY payment state;
• support multiple payment attempts where appropriate;
• account for asynchronous and late payment updates;
• explicitly define whether fulfilment requires completed, cleared, or both.

Continue reading

Payment methods

Explore payment methods, settlement guarantees, and when to check financial status before fulfilling an order.