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

3.1 KiB

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.