Payment Statuses Reference

Complete reference of all order, payment, and payment link statuses.

Complete reference of all statuses used in Paysera Checkout. There are three distinct status types that track different aspects of the payment flow.

Important Distinction

Do not confuse these status types - they track different entities:

• Order Status - Tracks the overall order state
• Payment Status - Tracks individual payment attempts
• Payment Link Status - Tracks the payment link availability

Order Statuses

Orders track the overall transaction state. An order can have multiple payment attempts.

Status	Code	Description	Terminal
Pending Payment	pending_payment	Order created, awaiting payment completion	No
Paid	paid	Order total amount equals amount paid (fully paid)	No
Canceled	canceled	Order was canceled before anything was paid	Yes
Closed	closed	Reserved, not currently used	Yes

Only a pending_payment order with nothing paid can be canceled — by the merchant in the Paysera Merchant Portal, or by Paysera support. Its active payment links are canceled as well, and an order canceled webhook is sent, with the status spelled cancelled (double "l"). A resent webhook carries the full order snapshot, where it is spelled canceled, so match both.

Order Status Transitions

Key Transition: pending_payment → paid

An order transitions from pending_payment to paid when:

• Order Amount Paid equals Order Total Amount to Pay

This happens when one or more payments settle and their total reaches the order amount.

Payment Statuses

Payments track individual payment attempts through the payment provider flow.

#	Status	Code	Description	Terminal
1	Initiated	initiated	Payment request created after payer clicks "Pay"	No
2	Awaiting Authorization	awaiting_authorization	Requires Strong Customer Authentication (SCA/3DS)	No
3	Authorized	authorized	Bank authorized the payment, funds not yet moved	No
4	Processing	processing	Moving through internal processing steps	No
5	Pending Settlement	pending_settlement	In clearing/batch processing stage	No
6	On Hold	on_hold	Paused for compliance or fraud review	No
7	Settled	settled	Funds reached merchant account	No*
8	Failed	failed	Technical failure occurred	Yes
9	Rejected	rejected	Bank explicitly refused the payment	Yes
10	Canceled	canceled	Payment canceled before settlement	Yes
11	Expired	expired	Authorization or session expired	Yes
12	Refunded	refunded	Payment partially or fully returned to payer	Yes
13	Chargeback	chargeback	Dispute/chargeback initiated by cardholder	Yes

*settled can transition to refunded or chargeback

How payment statuses reach you

Payment statuses surface in two places, with one spelling difference:

• Thin payment webhook (event.type = "payment") — payment.status carries only the notifiable statuses: pending_settlement, settled, failed, rejected, cancelled, expired, refunded, chargeback. In-flight statuses (initiated, awaiting_authorization, authorized, processing, on_hold) do not trigger a payment webhook.
• Order snapshot (event.type = "order") — the same payment appears under order.payment_links[].payments[].status using the raw status code, including the in-flight ones.

Spelling: in the thin payment webhook the canceled status is delivered as cancelled (double "l"); in the order snapshot it appears as canceled (single "l"). Match both if you branch on it.

Split payments add one more case. When only part of a split reaches its recipients, the payment-executor holds the payment in a partially_distributed state: the payer paid in full, but one distribution leg was returned or is still held. The thin payment webhook delivers that state as settled — the payer's side of the transaction is complete and the order is settled — and it is sent once: the later move to a fully settled payment does not repeat it. The order snapshot is the exception, and carries the raw partially_distributed string, so treat any status outside the table above as informational rather than failing on it.

For the per-recipient breakdown — which leg was returned, and how much of it stayed with the recipient — read distributions[] on Get a Payment, where delivered_amount is the part the recipient kept, or watch for the recipient.returned webhook.

While a payment is in this state a refund is not yet possible: the refund eligibility endpoint reports eligible: false with reason PAYMENT_NOT_SETTLED. Every leg has already resolved by then, so the payment leaves this state only once the returned leg is re-sent and delivered; until that happens it stays partially_distributed and stays unrefundable.

The payment-executor also has internal payout statuses (error, blocked, pending_retry) that are never delivered to merchant webhooks.

Payment Status Flow

Payment Link Statuses

Payment links control access to the payment flow. They have their own lifecycle independent of payment status.

Status	Code	Description	Terminal
Active	active	Link is valid and can initiate a payment session	No
Completed	completed	Payment settled successfully via this link	Yes
Expired	expired	Link lifetime (TTL) passed	Quasi*
Canceled	canceled	Link was invalidated by order update or manual cancel	Yes

*expired is quasi-terminal: it can still transition to completed if a payment that was started before expiration settles during the bank flow.

Payment Link Status Flow

Important Notes

1. No failed status for payment links - Payment links do not have a failed status. If a payment attempt fails, the link remains active (unless expired or canceled), allowing the customer to retry.

2. Expired links can complete - If a customer starts a payment flow before the link expires, and that payment settles after expiration, the link transitions from expired to completed.

Status Mapping Between Entities

Order Status	Typical Payment Status	Payment Link Status
pending_payment	initiated, processing, failed	active
paid	settled	completed
-	refunded, chargeback	-

Where Statuses Surface

Webhooks are the recommended way to track status: every status transition is delivered to your callback_url, and the payload carries the full order snapshot — including nested payment links and individual payment attempts. You can also read current state on demand with GET /merchant-order/integration/v1/orders/{id} and GET /checkout-payment-link/integration/v1/payment-links/{id} (useful for reconciliation or as a backup), but you should not poll them in a tight loop in place of handling webhooks.

Order status appears as the top-level order.status field. Payment status appears for each attempt under order.payment_links[].payments[].status. See Webhooks and the webhook event reference for full payload shapes.

Webhook Payload Snippet (snake_case)

{
  "event": { "name": "amount_paid_updated", "type": "order" },
  "order": {
    "paysera_order_id": "a6f2b8e3-5e5f-47d9-b13f-87ed2db2938a",
    "merchant_order_id": "ORDER-12345",
    "amount": 2500,
    "amount_paid": 2500,
    "currency": "EUR",
    "status": "paid",
    "created_at": 1736433270,
    "updated_at": 1736433500,
    "payment_links": [
      {
        "id": "c8d9e0f1-2a3b-4c5d-6e7f-8a9b0c1d2e3f",
        "name": "Order #12345",
        "payments": [
          {
            "id": "p-1",
            "method": "swedbank",
            "status": "settled",
            "payment_currency": "EUR",
            "payment_amount": 2500
          }
        ]
      }
    ]
  }
}

Status Handling Examples

PHP

<?php

class OrderStatusHandler
{
    public function handleOrderStatus(string $status, string $reference): void
    {
        match ($status) {
            'pending_payment' => $this->awaitPayment($reference),
            'paid' => $this->fulfillOrder($reference),
            'canceled' => $this->handleCancellation($reference),
            'closed' => $this->handleClosure($reference),
            default => $this->logUnknownStatus($status, $reference),
        };
    }
}

class PaymentLinkStatusHandler
{
    public function handleLinkStatus(string $status, string $linkId): void
    {
        match ($status) {
            'active' => $this->trackActiveLink($linkId),
            'completed' => $this->confirmPayment($linkId),
            'expired' => $this->handleExpiredLink($linkId),
            'canceled' => $this->handleCanceledLink($linkId),
            default => $this->logUnknownStatus($status, $linkId),
        };
    }
}

JavaScript

const orderStatusHandlers = {
  pending_payment: (reference) => awaitPayment(reference),
  paid: (reference) => fulfillOrder(reference),
  canceled: (reference) => handleCancellation(reference),
  closed: (reference) => handleClosure(reference),
};

const paymentLinkStatusHandlers = {
  active: (linkId) => trackActiveLink(linkId),
  completed: (linkId) => confirmPayment(linkId),
  expired: (linkId) => handleExpiredLink(linkId),
  canceled: (linkId) => handleCanceledLink(linkId),
};

function handleOrderStatus(status, reference) {
  const handler = orderStatusHandlers[status];
  if (handler) {
    handler(reference);
  } else {
    console.warn(`Unknown order status: ${status}`);
  }
}

Related Documentation

• Payment Flow - Understand the complete payment lifecycle
• Webhook Events - Events triggered by status changes
• Error Codes - Error handling reference