Order Lifecycle

Every order moves through a defined set of states. Understanding the lifecycle helps you decide when to deliver the gift card, when invalidation is possible, and which webhook events to expect.

Order States

State	Final	Description
processing	No	The order has been created and is being processed. Delivery information is not yet available.
completed	Yes*	The order was processed successfully and the delivery information is available.
failed	Yes	The order could not be processed. No value was delivered and your balance is not affected.
invalidated	Yes	The order was invalidated via the invalidation endpoint. The gift card can no longer be used.
refunded	Yes	The order was refunded by finperks based on a specific support agreement. Code details are no longer returned.

* completed is final except for the two explicit exits below: invalidation within the invalidation period and refunds triggered by finperks.

With processing_mode: sync, the creation request only returns once the order has left the processing state, so the response contains either a completed order including delivery information or an error. With processing_mode: async, the creation response returns a processing order and you receive the final state via webhook or by polling GET /orders/{id}. See Processing Modes.

caution

Even in sync mode, your code must be able to handle a processing order in the creation response. If your original request timed out on your side and you retry it with the same Idempotency-Key while the order is still being processed, the retry returns the order in its current state — which may still be processing. In that case, keep polling GET /orders/{id} or wait for the webhook event to receive the final state.

Webhook Events

When you subscribe to order webhooks, an event is sent for each state change. The payload's data object contains the full order. The data.state field represents the current state at the time of sending the webhooks. See Webhooks.

Since webhooks are retried on failure, events can arrive late or out of order in rare cases. When in doubt, retrieve the current state via GET /orders/{id}.

Invalidation

Invalidation is meant for correcting mistakes and technical issues, e.g. when your own transaction towards your customer failed after the order was already placed.

• Invalidation is only possible for completed orders. Orders that are still processing cannot be invalidated, because a clean rollback cannot be guaranteed mid-processing.
• Invalidation is only allowed for a short period after the order completes. The exact duration depends on your agreement with finperks. Invalidate as soon as possible after you detect a problem.
• Some orders are fulfilled from pre-purchased stock (see Stock Availability) and cannot be invalidated at all. In this case the API returns the order_invalidation_not_supported error.

Error code	Meaning
order_processing	The order is still processing and cannot be invalidated yet.
order_invalidated	The order has already been invalidated. If this occurs on a retry, your earlier invalidation succeeded.
order_failed	The order already failed; there is nothing to invalidate.
order_invalidation_period_expired	The invalidation period has passed. Contact support if the order still needs to be reversed.
order_invalidation_not_supported	The order cannot be invalidated, e.g. because it was fulfilled from pre-purchased stock.

If you are unsure whether an order creation request succeeded (e.g. after a network failure), first recover the order using your idempotency key — see Idempotency — and then invalidate if necessary.

Refunds

Refunds move a completed order to refunded. In live mode, refunds are exclusively triggered by finperks based on specific agreements and after review of the support case — there is no self-service refund endpoint. Once refunded, the order's code details are no longer returned.

In the sandbox environment, you can simulate a refund via POST /orders/{id}/actions/refund to test your handling of the refunded state and webhook event.