Payment

A payment represents a single purchase attempt by an end user, the core unit used to capture funds. Every payment belongs to a payment order, is made up of one or more items, and moves through a lifecycle of statuses from initiation to a terminal state.

Each payment has a payment_id, a single payment method (card, Swish, deposit, Autogiro, …), a list of items, and a current status. Its items decide where the money goes, and its status decides what can happen next: the order can't split until the payment is terminal, and only a completed payment can be refunded.

Items decide where the money goes

An item is an order line. Each carries a name, an amount in minor units, a VAT rate, and the recipient that should receive its funds. Because each item names its own recipient, a single payment can fund several merchants or liquidity accounts at once.

Anatomy of an item

Field	Meaning
`name`	The product or service this line represents.
`amount`	Charge for this item, in the minor unit of the payment currency (öre, cents).
`merchant_id`	The merchant that receives this item's funds.
`liquidity_account_id`	The liquidity account that receiver this item's funds
`vat_rate`	VAT rate applied to the item, used for reporting and reconciliation.
`tags`	Optional labels for later filtering in operations or statistics.

Status & lifecycle

Every payment starts at INITIATED and, once initiation succeeds, moves to PENDING while the acquiring transaction is in flight. From there it lands on a terminal status that never changes again. A few statuses apply only to ping/deposit payments, where the deposited amount is outside Ping's control. These compare the cumulative funds received across all transfers against the payment's total_amount, and each incoming transfer triggers a fresh status callback.

Status	Terminal	Scope	Meaning
`INITIATED`	No	All	The initial status of every payment.
`PENDING`	No	All	Initiation succeeded; the acquiring transaction is ongoing.
`COMPLETED`	Yes	All	The payer paid the full amount. The only status from which a refund is possible.
`CRASHED`	Yes	All	The payment crashed due to a provider error. A new payment is needed to retry.
`ABORTED`	Yes	All	The payer did not go through with the payment.
`EXPIRED`	Yes	All	Not paid within the session lifetime, which varies by method.
`DECLINED`	Yes	All	Declined by the provider.
`STOPPED`	Yes	All	A PENDING payment manually stopped by the tenant.
`FUNDED`	No	ping/deposit	The exact amount was received, but `complete_when_funded` is false, so it does not auto-complete.
`UNDERFUNDED`	No	ping/deposit	Cumulative funds received are less than the expected `total_amount`. A further transfer may still arrive, so don't reconcile immediately.
`OVERFUNDED`	No	ping/deposit	Cumulative funds received exceed the payment `total_amount`.