Orders, payments, and refunds

​

One record, nine operations

​

The amounts on an order

​

The state machine

• stale_quote — a shop order whose gateway quote lapsed. Its window is the quote’s validity, and delivering at a rate that no longer holds can cost more than the customer paid.
• limit_exceeded — its promotion or trial was claimed by another order while it sat closed. See Catalog and promotions.
• subscription_unavailable — the subscription it opened was released while it sat closed, and the concurrency ceiling will not open another. See Subscriptions.

​

The payment window

​

What the customer sees: the payment phase

• Web. /account/orders/{id} renders a three-step progress bar — paid, provisioning, ready — driven only by the phase, so a reload or a second tab shows the same progress.
• Telegram. The order screen switches on the same phase and offers a different keyboard per phase: the provider link and Cancel while pending, Connect once completed.

​

Quoting a checkout

1. Resolve the plan version for the requested currency. A version that is archived, retired, or carries no price in that currency yields plan_unavailable.
2. Check the operation against the plan’s upgrade and downgrade policies.
3. Read the available wallet balance — the total minus what the customer’s own draft and pending orders have already claimed.
4. Resolve the promotion, if a code was given, taking FOR UPDATE on the promotion row so two customers racing for the last use of a limited code serialise instead of both succeeding.
5. Resolve the squad selection against the plan version’s selection policy.
6. Price any add-ons at full catalogue price, because an add-on bought with the plan covers the whole first period.
7. Split what is due into a wallet part and an external part.

​

Wallet credit is applied before external payment

due      = subtotal - discount
wallet   = min(available balance, due)
external = due - wallet

​

The checkout session

• Every edit statement requires the checkout to have no order yet, so an edit arriving after confirmation is reported as 409 checkout_settled rather than as a missing checkout.
• A lifecycle change with more than one subscription and no named target is refused with 422 subscription_target_required. The panel must ask rather than let the server guess.
• A currency the chosen adapter cannot settle is refused at selection time.
• A checkout expires an hour after it opens; reading an expired one deletes it, so the customer restarts from a fresh quote rather than a stale price.
• In Telegram, required-channel membership is re-checked at the moment of confirmation, because a customer can leave a channel between browsing and paying.

​

Payment intents

1. The idempotency key is validated (8 to 128 characters).
2. An unregistered provider is refused with “payment provider is not enabled”.
3. A PostgreSQL advisory lock keyed on provider + ":" + key serialises concurrent attempts.
4. The order must be pending and owe an external amount, otherwise “order does not require an external payment”.
5. An existing intent under the same key with a different order, amount or currency is refused with “idempotency key was already used with different payment parameters”; the same parameters return the intent unchanged.
6. If the adapter can recover an invoice by merchant reference (CryptoBot can), Omniflow adopts the invoice it already created rather than creating a second one.
7. Otherwise the adapter is asked to create the payment, and its status, reference and checkout URL are stored.

​

The provider contract

​

Webhook intake and idempotency

1. The named adapter must be registered and declare webhook support. This is what closes the public route for telegram_stars and manual — Telegram does not sign Bot API updates for a public HTTP route, so accepting a “Stars webhook” there would be accepting unauthenticated money.
2. The body is hashed.
3. The adapter verifies the signature. A failure still writes a row, with signature_valid = false, an event ID derived from the body digest, and an empty body — the digest identifies repeated garbage, and storing whatever a stranger posts would hand them the database’s disk — increments omniflow_provider_webhooks_total{outcome="signature_invalid"}, and answers 400.
4. The event is inserted into provider_webhook_events on (provider, provider_event_id). If the stored row already reads processed or ignored, the request returns duplicate and stops. This is the deduplication guard.
5. For YooKassa only, the referenced payment is re-fetched over the authenticated API and the polled status and amount replace the notification’s — YooKassa does not sign its callbacks, so authenticity is established by asking the provider directly. The re-fetch is made only for a payment intent this installation opened: a notification naming an unknown payment completes as failed with payment_not_found without calling YooKassa, so a stranger posting well-formed bodies cannot make the API spend provider requests. A failed re-fetch completes the row as failed with reconciliation_failed and applies nothing.
6. A verified event that is not a success is completed as ignored, not as a failure.
7. The intent is found by provider reference, falling back to the order carried in the merchant reference. No match completes the row as failed with payment_not_found.
8. The payment is applied through the shared settlement path, and the row is completed as processed carrying the classification.

​

Payment classification

​

When a payment does not settle

​

Settlement: what a paid order produces

1. The double-entry revenue movement.
2. The entitlement schedule is computed from the operation and the plan’s policies: a purchase starts now; an extension or renewal ends at max(now, current end) + duration; an upgrade either replaces or stacks; a downgrade takes effect immediately or at the current end.
3. The entitlement is created with the squad set the customer confirmed, falling back to the plan version’s own set.
4. Add-on lines are applied, idempotent on the order and add-on version.
5. A fulfillment operation is created with the key order:{orderID}:fulfill and the desired Remnawave state.
6. An outbox_events row with topic order.paid is written.
7. An operator notice is queued, deduplicated on the order.
8. Referral rewards are granted, in this same transaction, so a retried webhook can never credit twice.

• A mid-period add-on whose subscription disappeared between purchase and settlement does not roll the money back. The order stays paid, an audit event addon.no_active_entitlement is written with category financial and outcome failure, and an operator notice is queued. Refunding automatically would be deciding on the customer’s behalf what they wanted.
• A saved cart released by a settled top-up is charged after the commit, because a cart failure must never roll back a payment that was received. See Wallet top-up and saved carts.

​

Manual payments

curl -X POST https://example.com/v1/admin/payments/{paymentID}/manual-decision \
  -H "Authorization: Bearer $APP_OPERATOR_TOKEN" \
  -H "Idempotency-Key: manual-2026-08-13-0001" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "operatorID": "ops@example.com", "reason": "Bank transfer received"}'

​

Refunds

• Refuse without a valid idempotency key and a non-empty reason.
• Take the advisory lock refund:{paymentIntentID}, so refund mutations on one intent serialise.
• Refuse unless the intent is succeeded, the currency matches, and the amount is positive and no greater than the intent.
• Refuse unless the adapter is registered, declares refund support, and the intent has a provider reference. CryptoBot therefore cannot be refunded at all.
• Sum the pending, processing and succeeded refunds already on the intent and refuse if this one would take the total past the intent amount — before the provider is called, because a provider that accepts an over-refund is a provider you then have to argue with.
• Write the refunds row first — pending, with no provider reference, unique on intent and idempotency key — so the refund is on record, and its amount reserved, before any request leaves.
• Call the adapter under the refund’s idempotency key and write its answer onto the row: the status and the provider’s reference. Only if the provider reported success are the ledger movement and the new order state recorded.

• A definite refusal on the first request — the provider answered 4xx other than 408, 409 or 429, or the adapter cannot refund — marks the row failed, which frees the amount it reserved.
• No answer — a timeout, an outage, a 5xx, or a crash — leaves it pending with no provider reference. Repeating the refund request with the same idempotency key asks the provider again, and so does the background reconciler, every minute, for any such row between one minute and a day old. The provider recognises the key, so asking again cannot refund twice.
• A revival that still cannot get an answer queues one incident notice with status refund_outcome_unknown, deduplicated per refund, so an operator checks the outcome at the provider. After a day — how long a provider holds an idempotency key — the reconciler stops asking.

​

What a refund takes back

• A full refund of a subscription order (purchase, extension, renewal, upgrade, downgrade reaching refunded) takes the period it bought off the entitlement it created. Every schedule adds the plan’s duration to a base, so the end moves back by exactly that duration: a refunded extension falls back to the end the customer had before it, and a refunded purchase ends now. Time already used is never clawed back, and a paused entitlement ends at its pause instant. A reconcile operation keyed refund:{refundID}:revoke pushes the shorter end to Remnawave, which then expires the user at that end plus the plan’s grace period. An entitlement that has not started yet — an at_expiry downgrade — or that was never provisioned is retired as superseded instead, and its create is cancelled when it runs. An entitlement a later change already superseded is left alone, because the refunded period now sits under that change; the refund notice says so.
• A refund of a wallet top-up debits the refunded amount from the wallet (ledger type debit, key refund-debit:{refundID}), because that credit is the money that went back. When the available balance no longer covers it — the customer spent it, or an unpaid order has it reserved — nothing is debited, since the ledger never goes negative, and an incident notice with status topup_refund_wallet_short is queued for an operator to resolve.
• A partial refund of a subscription order changes nothing but the money: it is usually a goodwill gesture, and whether access should change is the operator’s decision. An order paid partly from the wallet can only ever be partially refunded through the provider, so it is in the same position.

• Telegram Stars refunds the whole charge or nothing, and needs the paying Telegram account, which is recorded only when the payment was started from a surface that knows it. A Stars payment started in the web panel carries no Telegram identifier and cannot be refunded through the adapter.
• CryptoBot has no refund API.
• YooKassa supports full and partial refunds.
• Manual returns a pending refund record; the money moves however the operator sent it.

​

Reconciliation and stuck payments

​

What an operator sees

• Orders. Filter by state and operation, cursor-paginated, with a CSV export. Columns: created at, customer, operation, state badge, paid, refunded. A row opens the order. GET /v1/panel/finance/orders — permission finance.read.
• Stuck. The reconciliation queue described above.
• Charges. Failed automatic renewal attempts with attempt number, funding source, outcome and failure code. It is a review surface only: nothing re-triggers a charge from here, because the customer has already been told to renew and charging them again from a panel click would be an attempt they did not ask for.

order_id, created_at_utc, updated_at_utc, customer_id, state, operation,
currency, subtotal_minor, discount_minor, wallet_minor, external_minor,
paid_minor, refunded_minor, providers

​

Metrics