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 ¶
- type Driver
- func (driver *Driver) ApproveCheckout(ctx context.Context, id payment.CheckoutID) error
- func (driver *Driver) CancelSubscription(ctx context.Context, request payment.CancelSubscriptionRequest) error
- func (driver *Driver) CompleteCheckout(ctx context.Context, request payment.CompleteCheckoutRequest) (payment.Checkout, error)
- func (driver *Driver) CreateCheckout(ctx context.Context, request payment.CheckoutRequest) (payment.Checkout, error)
- func (driver *Driver) CreateSubscriptionCheckout(ctx context.Context, request payment.SubscriptionCheckoutRequest) (payment.Checkout, error)
- func (driver *Driver) GetCheckout(ctx context.Context, id payment.CheckoutID) (payment.Checkout, error)
- func (driver *Driver) GetPayment(ctx context.Context, id payment.ID) (payment.Payment, error)
- func (driver *Driver) GetRefund(ctx context.Context, id payment.RefundID) (payment.Refund, error)
- func (driver *Driver) GetSubscription(ctx context.Context, id payment.SubscriptionID) (payment.Subscription, error)
- func (driver *Driver) PreparePayment(ctx context.Context, request payment.PreparePaymentRequest) (payment.Preparation, error)
- func (driver *Driver) RefundPayment(ctx context.Context, request payment.RefundRequest) (payment.Refund, error)
- func (driver *Driver) Reset()
- func (driver *Driver) ResolveCheckout(ctx context.Context, id payment.CheckoutID, status payment.CheckoutStatus) error
- func (driver *Driver) ResolvePayment(ctx context.Context, id payment.ID, status payment.Status) error
- func (driver *Driver) ResolveSubscription(ctx context.Context, id payment.SubscriptionID, ...) error
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 ¶
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 ¶
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 ¶
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 }