wealth/docs/decisions/0033-abandoned-payment-is-s...

30 lines
3.1 KiB
Markdown
Raw Normal View History

# 0033 A payment left at the bank is settled when the investor comes back
Status: Proposed · Area: architecture · Date: 2026-10-08 · Decided by: agent
## Context
An investor who backs out of the gateway (back button) never reaches `/payment/return`, so the payment stays `pending` and blocks a new one until the API reviews it (checkout answers `pending_review`, subscribe 409). U10 ۶.۳ expects checkout to be untouched. The API settles such a payment on request: `POST /subscriptions/payments/:id/abandon` asks the bank and answers `completed`, `abandoned`, `pending` or `closed`. A bank that has not been paid yet answers "not paid", so the request must never be sent while the bank's page may still be open.
## Decision
- The payment sent to the bank is kept as `paymentId` in the checkout draft (0030), only when the browser really leaves for a bank URL. `settleAbandonedPayment` is the one action that settles it, deduplicated while in flight, and it keeps each step in the store's in-memory `settlement`.
- Only the page that came back settles: a page restored from the back cache that sent the payment itself (`sentHere`, in memory), or a document opened from the history (`back_forward`). A new tab, a reload or a typed address never settles; that payment goes to the API's review.
- A `pending` answer is not asked again in the same page load.
- The app shell triggers the action for a signed-in investor outside `/payment/*`, once the draft is restored and again on a bfcache `pageshow`; moving between pages triggers nothing. When a settlement ends it invalidates checkout, channel, subscription and transaction queries.
- Checkout's screen read awaits the action before it reads, so the screen never shows a settled payment as in review. It shows a same-size skeleton with «در حال بررسی پرداخت قبلی شما با بانک…» while the store says settling. It goes to the result page when this creator's settlement is `completed`, before any other way out. It shows the pending state only when the bank has not answered.
- `/payment/return` forgets the draft's payment, once the draft is restored, when it is the one returned, so a bank answer is never settled twice.
## Alternatives
- Settle on every app load that finds a payment in the draft: a second tab or a reload while the bank's page is open would abandon a payment the investor may still pay.
- Remember the leaving tab in `sessionStorage`: more precise, but it needs a second storage lib for one flag. The history-load check covers backing out.
- Let the review run: the investor cannot retry for 15 minutes and may pay twice from another device.
- Settle only on the checkout page: the subscriptions and transactions tabs would show a stale pending payment.
## Consequences
- One extra request after a gateway round trip that did not come back; none otherwise.
- An investor who closes the bank's tab and opens the app fresh, rather than going back, waits for the API's review (15 minutes) before paying again.
- A payment the bank has not answered stays pending (`pending` outcome). The draft keeps it, and the next page opened from the history asks again.