diff --git a/plans/names-codes/2026-10-21-store-api.md b/plans/names-codes/2026-10-21-store-api.md index 18e78f4f5a..8396648e65 100644 --- a/plans/names-codes/2026-10-21-store-api.md +++ b/plans/names-codes/2026-10-21-store-api.md @@ -497,7 +497,7 @@ A paid order whose name someone registered first keeps what it is worth as a bal - *Once:* each credit adds only the confirmed crypto (or, for Stripe, cents) not yet credited from that invoice, under the invoice's lock, with each credit numbered per invoice and unique, so a repeated, growing or reorganised report, or a second instance, never credits twice, and an unconfirmed payment that is replaced or dropped never credits. - *Which invoices:* a name invoice whose order is `unpaid` and not live, whatever the invoice's own status (a late `Settled` invoice reads `paid` while its order stays `unpaid`). - *When:* after the settlement that recorded the payment commits, by the poller, and again by the poller's pass (at its idle cadence) for any such invoice whose confirmed money is not all credited, so a crash or a failed rate read loses nothing. A cancel by the buyer reads no rate: its late money is credited by the poller. The rate read never runs under the invoice's lock, happens only when crypto is due, and is made once per currency pair per pass. - - *Pending and the alert:* money received but not confirmed (a mempool payment, Monero confirming with a zero figure) is pending and logged at info. The operator is alerted once per invoice, and again only when more money arrives, when money on a closed invoice is still not all credited and its payment was first seen longer ago than the poller's read window (`settleWindow`, about 72 hours). The alert names the crypto received, confirmed and credited (cents for Stripe), and its reason: unconfirmed money ("refund by hand only a transaction confirmed on chain that BTCPay no longer monitors; one still `Processing` there waits"), confirmed money waiting on a failing rate read ("do not refund; fix the rate read"), or confirmed money waiting because the current rate is below the floor (naming both rates: "the coin's price fell by more than half since the invoice; the owner decides: credit at the current rate, or refund by hand"); or money that could not be counted in units. Only one instance logs it, by a conditional write of the alert's mark. + - *Pending and the alert:* money received but not confirmed (a mempool payment, Monero confirming with a zero figure) is pending and logged at info. The operator is alerted once per invoice, and again only when more money arrives, when money on a closed invoice is still not all credited and its payment was first seen longer ago than the poller's read window (`settleWindow`, about 72 hours). The alert names the crypto received, confirmed and credited (cents for Stripe), and its reason: unconfirmed money ("refund by hand only a transaction confirmed on chain that BTCPay no longer monitors; one still `Processing` there waits"), confirmed money waiting on a failing rate read ("do not refund; fix the rate read"), confirmed money waiting because the current rate is below the floor (naming both rates: "the coin's price fell by more than half since the invoice; the owner decides: credit at the current rate, or refund by hand"), or money that could not be counted in units ("check it at the provider"). Only one instance logs it, by a conditional write of the alert's mark. - **Spent:** only by `/spend` (below), signed by the owner, for a new order of the same owner. When the balance covers the new name's price, the price is spent at once and the rest stays as balance. When it does not, all of it pays, and an invoice is made for the difference. - **Held:** while that invoice is open, the new order holds the balance: no other spend and no refund takes it. Settlement queues the new order and spends what it held, in one transaction. Whatever closes the invoice unpaid (a cancel, its expiry, the poller's sweep, a next order closing it as overdue, section 1) releases the hold in the transaction that closes the order. A payment that arrives after that is a late payment (section 1): it is credited to the closed order's own balance, and the released balance is not touched. A hold by an order whose invoice is past its expiry time with no money received reads as free (`held` false), and the next `/spend` of that balance closes that order first, in its own transaction, as section 1 closes an overdue order (below). A refund does not: it waits for the poller's sweep to close the holder. - **Refunded:** only by support, when the buyer writes with the order's reference (its invoice id, or its registration id for an order without an invoice). The operator command `//refund ` (task plan, T26) sets the balance to 0 and adds the cents to `refunded`, which counts every refund of the balance (one can be credited again later, by a late payment or a move); support then pays them back by hand, by the methods that paid them, which the command lists back through every balance the money came from. A held balance is never refunded, overdue holder or not: the command names the holder and its invoice's expiry, and support runs it again once the poller has closed the holder. There is no refund endpoint, no automatic refund, and no refund address given to the service.