Transaction Lifecycle
Every payment on Plirin follows a consistent lifecycle from creation to settlement.
Lifecycle stages
Section titled “Lifecycle stages”created → pending → confirming → confirmed → settled| Stage | Description |
|---|---|
| Created | Payment link generated, waiting for customer |
| Pending | Customer initiated payment, transaction submitted to blockchain |
| Confirming | Transaction detected on-chain, awaiting sufficient confirmations |
| Confirmed | Transaction confirmed on-chain with proof |
| Settled | Funds credited to merchant wallet, transaction recorded |
| Reverted | A confirmed payment the chain later contradicted. See below |
When a confirmed payment is reverted
Section titled “When a confirmed payment is reverted”Rarely, a payment that Plirin has already confirmed turns out not to have settled after all. Plirin re-checks confirmed payments against their chain independently of the original confirmation, and if that check finds the money never moved, the payment is moved to Reverted.
The usual cause is a chain reorganisation: the block carrying the transaction was displaced, taking the transaction with it. The confirmation-depth rules above exist to make this very unlikely, but “very unlikely” is not “impossible”, so the state exists.
Reverted is not the same as Failed. A failed payment never confirmed, so you never acted on it. A reverted payment was reported to you as settled, and you may already have shipped. It appears as its own status in the dashboard, with its own filter, precisely so it does not disappear into the noise of ordinary failures.
What happens automatically: the payment leaves your revenue figures, the
platform fee charged on it is reversed, a payment.reverted webhook is sent,
and an audit entry records the change with the evidence behind it.
What you should do: treat it like a chargeback. Reverse whatever the confirmation triggered. The transaction’s detail view in the dashboard explains the state in place and tells you what to check, so you do not have to remember what “reverted” means when you meet one.
What your customer sees. If they still have the checkout open, it stops showing the confirming screen and tells them the payment was reversed, with instructions to contact you rather than simply paying again — paying twice for an order you may already have shipped helps nobody.
Reverted is terminal. A reverted payment is never restored to confirmed. If the customer pays again, that is a new payment.
How finality is decided
Section titled “How finality is decided”A transaction appearing on-chain is not the same as a transaction that will stay there. Plirin waits for finality before marking a payment confirmed, and what “final” means differs by chain.
Solana waits for the finalized commitment level, which is the network’s
own guarantee that a block will not be rolled back.
EVM chains (Ethereum, Base, Polygon) have no equivalent flag, so finality is measured in block depth: how many blocks have been built on top of the one carrying your payment. A transaction in the newest block can still be displaced by a chain reorganisation. Plirin therefore requires a minimum number of confirmations per network before confirming:
| Network | Confirmations required | Approximate wait |
|---|---|---|
| Ethereum | 12 | ~2.5 minutes |
| Base | 30 | ~1 minute |
| Polygon | 60 | ~2 minutes |
Confirmations are counted inclusive of the block containing the transaction, matching how block explorers display them: a transaction in the newest block has one confirmation.
The wait is deliberate. A payment marked confirmed is a payment you can ship against, so Plirin would rather take an extra minute than tell you money arrived that a reorganisation later removes.
During this window the payment’s stored status is still pending — there is no separate “confirming” status in the API, in webhooks, or in your exports. The confirmation progress described below is display detail on the checkout, not a state your integration has to handle. Nothing fires until the payment is confirmed.
Your customer is not left guessing. As soon as the payment appears on-chain, the checkout switches to “Payment received — confirming on the network”, with a live count of confirmations against the number required. They are told not to pay again, which is the thing an unexplained wait otherwise invites. This is display only: the payment is not settled, no webhook has fired, and nothing in your dashboard treats it as revenue until the full depth is reached.
Solana has no equivalent screen because it does not need one: finalized
arrives in about 13 seconds.
If Plirin cannot reach the chain to check depth, the payment stays pending and is re-checked on the next reconciliation pass rather than being confirmed optimistically. The checkout keeps showing the customer that their payment was received, but the confirmation count disappears, because at that moment we do not know how far along it is — which is a different thing from it being at zero.
Self-hosted operators can adjust these thresholds per network with the
EVM_MIN_CONFIRMATIONS environment variable — see the backend configuration
reference.
Transaction details
Section titled “Transaction details”Once settled, each transaction records:
- Transaction hash — on-chain proof (links to blockchain explorer)
- Customer wallet — the address that sent payment
- Merchant wallet — the address that received payment
- Token — USDC or USDT
- Amount — the payment amount after fees
- Fee — the Plirin transaction fee
- Blockchain — which network the transaction settled on
- Timestamp — when the transaction was confirmed
Viewing transactions
Section titled “Viewing transactions”All transactions are visible in the Transactions page with filtering by date range, status, token, and blockchain. Click any transaction to see full details including the on-chain transaction hash.