feat(finance): a payment session hands back the gateway page it is waiting at

Author: beanbocchi

api/openapi.gen.yaml

@@ -2861,6 +2861,11 @@ components:
             type: object
         PaymentSession:
             properties:
+                checkout_url:
+                    description: |
+                        The gateway page an unfinished payment attempt is still waiting at — send the payer straight back to it. Empty when there is nothing to return to: no attempt yet, a rail that redirects nowhere, or a session past its deadline. A client that finds it empty has to ask for a rail first, through `POST /payment-sessions/{id}/payments`.
+                    example: https://api.shopnexus.io/api/v1/webhooks/payment/sepay/checkout?ref=txn_ev6mj8exxkxwe
+                    type: string
                 created_at:
                     format: date-time
                     type: string
@@ -2902,6 +2907,7 @@ components:
                 - currency
                 - total_amount
                 - outstanding
+                - checkout_url
                 - note
                 - created_at
                 - paid_at
@@ -4081,7 +4087,8 @@ components:
                     format: int64
                     type: integer
                 checkout_url:
-                    description: Where to send the payer for this leg. Empty once the rail no longer needs it, or for rails that have none.
+                    description: Where to send the payer for this leg, answered for as long as the leg can still be paid. Empty once it has settled or expired, and for rails that redirect nowhere.
+                    example: https://api.shopnexus.io/api/v1/webhooks/payment/sepay/checkout?ref=txn_ev6mj8exxkxwe
                     type: string
                 created_at:
                     format: date-time
@@ -10031,6 +10038,8 @@ paths:
             description: |
                 Creates a ledger leg on the chosen rail and returns it with the gateway redirect in `checkout_url`. Omit `amount` to tender the whole outstanding balance; pass it to split the session across several rails, calling this again per rail until the total is covered.
 
+                Tendering a rail that already has an unfinished attempt **resumes** it: the same leg comes back with the same `checkout_url`, and `amount` is ignored. A redirect rail reports nothing when the payer closes its tab, so a second live gateway page would be one the session cannot account for — whichever payment landed second would have no outstanding balance left to settle against.
+
                 The leg starts `pending` and only the provider's webhook settles it — this response is not a receipt. Poll the session or the leg for the outcome.
             parameters:
                 - in: path

internal/module/finance/adapter/postgres/session.go

@@ -99,13 +99,14 @@ func (r *Repo) NextTransactionID(ctx context.Context) (int64, error) {
 }
 
 const transactionColumns = `id, session_id, status::text, note, error, payment_option,
-	       provider_ref, data, amount, currency, reverses_id, created_at, settled_at, expired_at`
+	       provider_ref, checkout_url, data, amount, currency, reverses_id, created_at,
+	       settled_at, expired_at`
 
 func scanTransaction(row pgx.Row) (domain.Transaction, error) {
 	var t domain.Transaction
 	err := row.Scan(&t.ID, &t.SessionID, &t.Status, &t.Note, &t.Error, &t.PaymentOption,
-		&t.ProviderRef, &t.Data, &t.Amount, &t.Currency, &t.ReversesID, &t.CreatedAt,
-		&t.SettledAt, &t.ExpiredAt)
+		&t.ProviderRef, &t.CheckoutURL, &t.Data, &t.Amount, &t.Currency, &t.ReversesID,
+		&t.CreatedAt, &t.SettledAt, &t.ExpiredAt)
 	if dbx.IsNoRows(err) {
 		return domain.Transaction{}, domain.ErrTransactionNotFound
 	}
@@ -117,15 +118,16 @@ func scanTransaction(row pgx.Row) (domain.Transaction, error) {
 
 func (r *Repo) InsertTransaction(ctx context.Context, t *domain.Transaction) error {
 	const q = `INSERT INTO transaction
-	             (id, session_id, status, note, error, payment_option, provider_ref, data,
-	              amount, currency, reverses_id, expired_at)
+	             (id, session_id, status, note, error, payment_option, provider_ref,
+	              checkout_url, data, amount, currency, reverses_id, expired_at)
 	           VALUES (@id, @session_id, @status, @note, @error, @payment_option, @provider_ref,
-	                   @data, @amount, @currency, @reverses_id, @expired_at)
+	                   @checkout_url, @data, @amount, @currency, @reverses_id, @expired_at)
 	           RETURNING created_at`
 	args := pgx.NamedArgs{
 		"id": t.ID, "session_id": t.SessionID, "status": t.Status, "note": t.Note,
 		"error": t.Error, "payment_option": t.PaymentOption, "provider_ref": t.ProviderRef,
-		"data": dbx.JSONObject(rawJSON(t.Data)), "amount": t.Amount, "currency": t.Currency,
+		"checkout_url": t.CheckoutURL,
+		"data":         dbx.JSONObject(rawJSON(t.Data)), "amount": t.Amount, "currency": t.Currency,
 		"reverses_id": t.ReversesID, "expired_at": t.ExpiredAt,
 	}
 	if err := r.pool.QueryRow(ctx, q, args).Scan(&t.CreatedAt); err != nil {

internal/module/finance/api/api.go

@@ -25,7 +25,12 @@ type Session struct {
 	// Outstanding is the total less what has already settled on a rail: what a further
 	// payment may still tender. Computed, because a stored copy is a second fact to
 	// keep in step with every leg.
-	Outstanding int64  `json:"outstanding"`
+	Outstanding int64 `json:"outstanding"`
+	// CheckoutURL is the gateway page a payment attempt on this session is still waiting at,
+	// so a payer who closed that tab can be sent straight back to it. Empty when there is
+	// nothing to go back to — no attempt yet, a rail that redirects nowhere, or a session
+	// past its deadline — and a client then has to choose a rail first.
+	CheckoutURL string `json:"checkout_url"`
 	Note        string `json:"note"`
 	// Data is the checkout context whoever opened the session wrote — the draft or offer it came
 	// from, and the delivery charge included in the total. Read back rather than kept only by the
@@ -59,8 +64,9 @@ type Transaction struct {
 	// provider gave, the reason a reversal was made.
 	Note       string                 `json:"note"`
 	ReversesID *id.ID[id.Transaction] `json:"reverses_id"`
-	// CheckoutURL is the gateway's redirect, present only while the leg is pending and
-	// only for a rail that redirects. Not a receipt: the webhook settles the leg.
+	// CheckoutURL is the gateway page this leg sent the payer to, answered for as long as the
+	// leg can still be paid — tendering the same rail again hands back this same leg rather
+	// than opening a second one. Not a receipt: the webhook settles the leg.
 	CheckoutURL string     `json:"checkout_url"`
 	Error       string     `json:"error"`
 	CreatedAt   time.Time  `json:"created_at"`

internal/module/finance/api/openapi/payment-session.yaml

@@ -82,6 +82,13 @@ paths:
         again per rail until the total is covered.
 
 
+        Tendering a rail that already has an unfinished attempt **resumes** it: the same leg
+        comes back with the same `checkout_url`, and `amount` is ignored. A redirect rail
+        reports nothing when the payer closes its tab, so a second live gateway page would be
+        one the session cannot account for — whichever payment landed second would have no
+        outstanding balance left to settle against.
+
+
         The leg starts `pending` and only the provider's webhook settles it — this
         response is not a receipt. Poll the session or the leg for the outcome.
       security: [{ bearerAuth: [] }]
@@ -169,14 +176,22 @@ components:
             The total less what has already settled on a rail: what a further payment may
             still tender. Computed, because a stored copy would be a second fact to keep in
             step with every leg.
+        checkout_url:
+          type: string
+          example: 'https://api.shopnexus.io/api/v1/webhooks/payment/sepay/checkout?ref=txn_ev6mj8exxkxwe'
+          description: >
+            The gateway page an unfinished payment attempt is still waiting at — send the payer
+            straight back to it. Empty when there is nothing to return to: no attempt yet, a rail
+            that redirects nowhere, or a session past its deadline. A client that finds it empty
+            has to ask for a rail first, through `POST /payment-sessions/{id}/payments`.
         note: { type: string }
         created_at: { type: string, format: date-time }
         paid_at: { type: string, format: date-time, nullable: true }
         expired_at:
           type: string
           format: date-time
           description: A session still unsettled past this point is voided by a job.
-      required: [id, kind, status, currency, total_amount, outstanding, note, created_at, paid_at, expired_at]
+      required: [id, kind, status, currency, total_amount, outstanding, checkout_url, note, created_at, paid_at, expired_at]
 
     PaymentSessionPage:
       type: object
@@ -208,8 +223,10 @@ components:
           description: The leg this one reverses. Set on reversals, null on originals.
         checkout_url:
           type: string
-          description: Where to send the payer for this leg. Empty once the rail no
-            longer needs it, or for rails that have none.
+          example: 'https://api.shopnexus.io/api/v1/webhooks/payment/sepay/checkout?ref=txn_ev6mj8exxkxwe'
+          description: Where to send the payer for this leg, answered for as long as the leg
+            can still be paid. Empty once it has settled or expired, and for rails that
+            redirect nowhere.
         error: { type: string, description: Empty unless the rail reported a failure on this leg. }
         note: { type: string }
         created_at: { type: string, format: date-time }

internal/module/finance/domain/session.go

@@ -90,6 +90,13 @@ func (s Session) Settled() bool {
 // them. Without this a requester could drive their own cash-out to `success`.
 func (s Session) RailPayable() bool { return s.Kind == KindBuyerCheckout }
 
+// Resumable reports whether an unfinished attempt on this session may still be reopened.
+// Past the deadline or already settled it may not: the payer would be sent to a live gateway
+// page for money the session can no longer account for, and nothing downstream would credit it.
+func (s Session) Resumable(now time.Time) bool {
+	return !s.Settled() && now.Before(s.ExpiredAt)
+}
+
 // Charge is the session accepting a payment attempt. Only a pending session is
 // payable — a processing one already has a leg in flight, and paying twice is what
 // the status is there to prevent.

internal/module/finance/domain/transaction.go

@@ -25,6 +25,9 @@ type Transaction struct {
 	// redelivered webhook being booked as a second charge. NULL only while the leg is
 	// pending and the gateway has not assigned one.
 	ProviderRef *string
+	// CheckoutURL is the gateway page this leg sent the payer to. Nil for a direct-debit
+	// rail, which decides on the spot and has nowhere to send anybody.
+	CheckoutURL *string
 	Data        []byte
 	// Amount is signed: positive is the charge, negative is the reversal.
 	Amount     int64  `validate:"required"`
@@ -51,6 +54,19 @@ func NewCharge(id, sessionID int64, option, currency string, amount int64, data
 	return t, nil
 }
 
+// Resumable reports whether the payer can be sent back to this leg's gateway page.
+//
+// A redirect rail reports nothing when the payer closes its tab, so an abandoned attempt is
+// indistinguishable from one still in progress — and it is the same attempt either way. That
+// is what makes reopening the right answer and a second leg the wrong one: two live pages on
+// one session can both be paid, and the second payment has no outstanding balance to land on.
+func (t Transaction) Resumable(now time.Time) bool {
+	if t.Status != StatusPending || t.CheckoutURL == nil || *t.CheckoutURL == "" {
+		return false
+	}
+	return t.ExpiredAt == nil || now.Before(*t.ExpiredAt)
+}
+
 // NewReversal is the refund leg: a negative row pointing at the charge it undoes.
 // The original has to have settled — reversing something that never happened is a
 // bookkeeping error, not a refund.

internal/module/finance/migrations/001_init.sql

@@ -104,6 +104,11 @@ CREATE TABLE IF NOT EXISTS "transaction" (
     -- not assigned one yet.
     "provider_ref" TEXT,
 
+    -- Where the payer was sent for this leg. Stored, not just returned once, because a
+    -- redirect rail reports nothing when the payer closes its tab: the leg stays pending
+    -- and this is the only way back to the page they left. NULL for a rail that has none.
+    "checkout_url" TEXT,
+
     -- Rail-specific payload: gateway request/response, webhook payload, processor IDs
     "data" JSONB NOT NULL,
 

internal/module/finance/service.go

@@ -146,14 +146,15 @@ func (s *Service) paymentOption(ctx context.Context, slug string) (common.Option
 // DTO, so this needs no bounds of its own.
 func offsetOf(page, limit int) int { return (page - 1) * limit }
 
-func toAPISession(s domain.Session, outstanding int64) financeapi.Session {
+func toAPISession(s domain.Session, t tender) financeapi.Session {
 	return financeapi.Session{
 		ID:          id.Of[id.PaymentSession](s.ID),
 		Kind:        s.Kind,
 		Status:      s.Status,
 		Currency:    s.Currency,
 		TotalAmount: s.TotalAmount,
-		Outstanding: outstanding,
+		Outstanding: t.Outstanding,
+		CheckoutURL: t.CheckoutURL,
 		Note:        s.Note,
 		Data:        rawOrEmpty(s.Data),
 		CreatedAt:   s.CreatedAt,
@@ -172,7 +173,13 @@ func toAPIWallet(w domain.Wallet) financeapi.Wallet {
 	}
 }
 
-func toAPITransaction(t domain.Transaction, checkoutURL string) financeapi.Transaction {
+func toAPITransaction(t domain.Transaction) financeapi.Transaction {
+	// Only while the leg can still be paid: the field is where to send the payer, and a
+	// settled or expired leg's page is somewhere they must not be sent.
+	checkoutURL := ""
+	if t.Resumable(time.Now()) {
+		checkoutURL = *t.CheckoutURL
+	}
 	out := financeapi.Transaction{
 		ID:            id.Of[id.Transaction](t.ID),
 		SessionID:     id.Of[id.PaymentSession](t.SessionID),