memorypayment

package
v0.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package memorypayment simulates outbound payment operations in process. It performs no network requests, renewals, or webhook processing. State and idempotency keys last until Reset; this is not durable provider storage.

Approval, completion, settlement, and subscription lifecycle are independent: create an open checkout, call ApproveCheckout, complete a payment checkout, then call ResolvePayment with a terminal outcome. Subscription creation records a pending subscription; approval completes enrollment but does not activate it. Completing an already complete checkout only observes its state, even with a new key. Tests use ResolveSubscription to change lifecycle without inventing paid invoices. PreparePayment instead creates only an unconfirmed pending payment and inert memory.authorization token. It never creates a hosted checkout; explicitly call ResolvePayment to simulate a subsequent provider outcome.

Example:

driver := memorypayment.New()
request := payment.NewCheckoutRequest(payment.Money{Amount: 1200, Currency: "USD"},
	"https://shop.example/paid", "order-1")
checkout, err := driver.CreateCheckout(ctx, request)
if err != nil { return err }
if err := driver.ApproveCheckout(ctx, checkout.ID); err != nil { return err }

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver is a concurrent in-memory simulator, not a payment processor. Construct it with New; its zero value is not ready for mutations. Reads return detached snapshots and never advance approval or settlement. Mutations sharing an operation and key replay their original response, even after later controls. Reusing that key with different input returns payment.ErrInvalidRequest.

Example:

driver := memorypayment.New()
var backend payment.Driver = driver
_ = backend

func New

func New() *Driver

New creates an empty simulator without settings, I/O, or background work. Tests drive external outcomes through ApproveCheckout and ResolvePayment.

Example:

driver := memorypayment.New()
_ = payment.New(driver)

func (*Driver) ApproveCheckout

func (driver *Driver) ApproveCheckout(ctx context.Context, id payment.CheckoutID) error

ApproveCheckout simulates customer approval without settlement or activation. Payment approval requires explicit completion; subscription approval completes enrollment but leaves lifecycle pending. Repeated approval, including already completed checkouts, is harmless. Expired or canceled checkouts reject approval with payment.ErrInvalidState; missing IDs return payment.ErrNotFound.

Example:

if err := driver.ApproveCheckout(ctx, checkout.ID); err != nil { return err }

func (*Driver) CancelSubscription

func (driver *Driver) CancelSubscription(
	ctx context.Context, request payment.CancelSubscriptionRequest,
) error

CancelSubscription immediately cancels a known subscription. Repeated calls succeed without refunds, proration, invoice writes, or time-based behavior.

Example:

err := driver.CancelSubscription(ctx, payment.NewCancelSubscriptionRequest(id))
if err != nil { return err }

func (*Driver) CompleteCheckout

func (driver *Driver) CompleteCheckout(
	ctx context.Context, request payment.CompleteCheckoutRequest,
) (payment.Checkout, error)

CompleteCheckout creates one pending payment for an approved payment checkout that needs completion. Settlement requires ResolvePayment; GET never settles it. Already completed checkouts, including approved subscription enrollments, are observed without creating money movements or changing lifecycle. New keys retain that observation; existing keys replay their original response.

Example:

checkout, err := driver.CompleteCheckout(ctx, payment.NewCompleteCheckoutRequest(id, "capture-1"))
if err != nil { return err }
_ = checkout.PaymentID

func (*Driver) CreateCheckout

func (driver *Driver) CreateCheckout(
	ctx context.Context, request payment.CheckoutRequest,
) (payment.Checkout, error)

CreateCheckout records an open approval flow with a non-routable approval URL. It neither approves nor creates a payment; completion becomes necessary only after approval. Same-input key replays return the original detached response; changed-input key reuse is invalid.

Example:

request := payment.NewCheckoutRequest(payment.Money{Amount: 1000, Currency: "USD"},
	"https://shop.example/paid", "order-1")
checkout, err := driver.CreateCheckout(ctx, request)
if err != nil { return err }
_ = checkout.ApprovalURL

func (*Driver) CreateSubscriptionCheckout

func (driver *Driver) CreateSubscriptionCheckout(
	ctx context.Context, request payment.SubscriptionCheckoutRequest,
) (payment.Checkout, error)

CreateSubscriptionCheckout records an open approval and pending subscription for the supplied plan reference. It does not infer a price, create a payment, activate the subscription, or schedule future renewals.

Example:

request := payment.NewSubscriptionCheckoutRequest("plan-monthly", "https://shop.example/account", "signup-1")
checkout, err := driver.CreateSubscriptionCheckout(ctx, request)
if err != nil { return err }
_ = checkout.SubscriptionID

func (*Driver) GetCheckout

func (driver *Driver) GetCheckout(ctx context.Context, id payment.CheckoutID) (payment.Checkout, error)

GetCheckout validates the context and identity, then returns a detached snapshot. Missing IDs return payment.ErrNotFound without changing state.

Example:

checkout, err := driver.GetCheckout(ctx, id)
if err != nil { return err }
_ = checkout.Status

func (*Driver) GetPayment

func (driver *Driver) GetPayment(ctx context.Context, id payment.ID) (payment.Payment, error)

GetPayment observes settlement without advancing it. A valid missing identity returns payment.ErrNotFound, including checkout IDs converted to payment IDs.

Example:

result, err := driver.GetPayment(ctx, id)
if err != nil { return err }
_ = result.Status

func (*Driver) GetRefund

func (driver *Driver) GetRefund(ctx context.Context, id payment.RefundID) (payment.Refund, error)

GetRefund observes a refund without submitting another return of funds. Valid identities absent from this instance return payment.ErrNotFound.

Example:

refund, err := driver.GetRefund(ctx, id)
if err != nil { return err }
_ = refund.Amount

func (*Driver) GetSubscription

func (driver *Driver) GetSubscription(
	ctx context.Context, id payment.SubscriptionID,
) (payment.Subscription, error)

GetSubscription returns a detached lifecycle snapshot without activation or invoice settlement. Valid missing identities return payment.ErrNotFound.

Example:

subscription, err := driver.GetSubscription(ctx, id)
if err != nil { return err }
_ = subscription.NextBillingAt

func (*Driver) PreparePayment

func (driver *Driver) PreparePayment(
	ctx context.Context, request payment.PreparePaymentRequest,
) (payment.Preparation, error)

PreparePayment creates an unconfirmed pending simulated payment and an inert memory.authorization token. It never approves, confirms, captures, or creates a hosted checkout. ResolvePayment is the explicit test control for subsequent outcomes. Same-payload key reuse replays the original handoff; changed payloads fail with ErrInvalidRequest. The token is not usable with a real SDK.

Example:

request := payment.NewPreparePaymentRequest(payment.Money{Amount: 1200, Currency: "USD"}, "order-1")
prepared, err := driver.PreparePayment(ctx, request)
if err != nil { return err }
if err := driver.ResolvePayment(ctx, prepared.PaymentID, payment.StatusSucceeded); err != nil { return err }

func (*Driver) RefundPayment

func (driver *Driver) RefundPayment(
	ctx context.Context, request payment.RefundRequest,
) (payment.Refund, error)

RefundPayment immediately succeeds for a positive amount of a succeeded payment in its original currency and within its remaining balance. Balance checks and idempotency recording are atomic, including concurrent retries. Refunds never change the original payment's succeeded status.

Example:

request := payment.NewRefundRequest(id, payment.Money{Amount: 100, Currency: "USD"}, "refund-1")
refund, err := driver.RefundPayment(ctx, request)
if err != nil { return err }
_ = refund.Status

func (*Driver) Reset

func (driver *Driver) Reset()

Reset forgets records, balances, and idempotency keys atomically. The identity sequence is retained so stale IDs cannot address resources created afterwards.

Example:

driver := memorypayment.New()
driver.Reset()

func (*Driver) ResolveCheckout

func (driver *Driver) ResolveCheckout(
	ctx context.Context, id payment.CheckoutID, status payment.CheckoutStatus,
) error

ResolveCheckout simulates expiration or cancellation before completion. Only open or approved checkouts can change; repeating the same outcome is harmless. It never cancels a subscription or changes a payment implicitly.

Example:

if err := driver.ResolveCheckout(ctx, id, payment.CheckoutStatusExpired); err != nil { return err }

func (*Driver) ResolvePayment

func (driver *Driver) ResolvePayment(ctx context.Context, id payment.ID, status payment.Status) error

ResolvePayment settles a pending payment as succeeded, failed, or canceled. Terminal outcomes cannot be replaced, though replaying the same outcome is harmless. Related checkout observations are updated without changing approval.

Example:

if err := driver.ResolvePayment(ctx, id, payment.StatusSucceeded); err != nil { return err }

func (*Driver) ResolveSubscription

func (driver *Driver) ResolveSubscription(
	ctx context.Context, id payment.SubscriptionID, status payment.SubscriptionStatus, nextBillingAt *time.Time,
) error

ResolveSubscription explicitly supplies a lifecycle outcome and optional next billing instant, which is copied. No invoice or payment is created. Canceled subscriptions cannot reactivate; use a new checkout for a new subscription. Nil nextBillingAt means unknown, not an unlimited paid-through period.

Example:

err := driver.ResolveSubscription(ctx, id, payment.SubscriptionStatusActive, nil)
if err != nil { return err }

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL