payment

README

togo-framework/payment

Part of the togo framework.

Install

togo install togo-framework/payment

payment

togo's payment subsystem — a provider-agnostic PaymentProvider contract with a safe dev log driver. Real gateways ship as driver plugins that call payment.RegisterDriver; pick one with PAYMENT_DRIVER.

togo install togo-framework/payment            # the base
togo install togo-framework/payment-stripe     # a gateway driver

Drivers available: payment-stripe, payment-paymob, payment-fawry, payment-tap, payment-moyasar, payment-paytabs, payment-payfort, payment-lemonsqueezy.

Configure

PAYMENT_DRIVER=stripe        # or paymob | fawry | tap | moyasar | … | log (default)
# + the selected driver's env (e.g. STRIPE_SECRET_KEY)

Use

import "github.com/togo-framework/payment"

svc, _ := payment.FromKernel(k)
ch, err := svc.CreateCharge(ctx, payment.ChargeRequest{
    Amount:   payment.Money{Amount: 5000, Currency: "USD"}, // 50.00
    Customer: payment.Customer{Email: "a@b.com"},
    Token:    "tok_visa",
})

cs, _ := svc.CreateCheckoutSession(ctx, payment.CheckoutRequest{
    Amount: payment.Money{Amount: 5000, Currency: "EGP"},
    SuccessURL: "https://app/success", CancelURL: "https://app/cancel",
})
// redirect the customer to cs.URL

Money is in the smallest currency unit (cents/piasters/halalas). The PaymentProvider interface covers charges, refunds, hosted checkout, customers, subscriptions, and normalized webhooks — drivers return a clear error for operations a gateway doesn't support.

MIT

---

Premium sponsors

ID8 Media  ·  One Studio

_{Support togo — become a sponsor.}

Documentation

Overview

Package payment is togo's payment subsystem: a PaymentProvider contract with a safe dev "log" driver. Real gateways (Stripe, Paymob, Fawry, Tap, Moyasar, PayTabs, PayFort, Lemon Squeezy, …) ship as driver plugins that call payment.RegisterDriver and depend on this package. Select one with PAYMENT_DRIVER.

Install: `togo install togo-framework/payment` (blank-import registers it), then a driver, e.g. `togo install togo-framework/payment-stripe`.

Index

• func RegisterDriver(name string, f DriverFactory)
• type Charge
• type ChargeRequest
• type CheckoutRequest
• type CheckoutSession
• type Customer
• type DriverFactory
• type LineItem
• type Money
• type PaymentProvider
• type RefundRequest
• type Service
  • func FromKernel(k *togo.Kernel) (*Service, bool)
  • func (s *Service) CreateCharge(ctx context.Context, req ChargeRequest) (*Charge, error)
  • func (s *Service) CreateCheckoutSession(ctx context.Context, req CheckoutRequest) (*CheckoutSession, error)
  • func (s *Service) CreateCustomer(ctx context.Context, c Customer) (string, error)
  • func (s *Service) CreateSubscription(ctx context.Context, req SubscriptionRequest) (*Subscription, error)
  • func (s *Service) Driver() string
  • func (s *Service) HandleWebhook(ctx context.Context, headers map[string]string, body []byte) (*WebhookEvent, error)
  • func (s *Service) Provider() PaymentProvider
  • func (s *Service) Refund(ctx context.Context, req RefundRequest) error
• type Subscription
• type SubscriptionRequest
• type WebhookEvent

Functions

func RegisterDriver

func RegisterDriver(name string, f DriverFactory)

RegisterDriver registers a payment driver by name (call from a plugin's init()).

Types

type Charge

type Charge struct {
	ID       string
	Status   string // succeeded | pending | failed
	Amount   Money
	Provider string
	Raw      map[string]any
}

Charge is the result of a charge.

type ChargeRequest

type ChargeRequest struct {
	Amount      Money
	Customer    Customer
	Description string
	Token       string
	Metadata    map[string]string
}

ChargeRequest requests a one-off charge. Token is a payment-method / source token obtained from the provider's client SDK.

type CheckoutRequest

type CheckoutRequest struct {
	Amount     Money
	Customer   Customer
	Items      []LineItem
	SuccessURL string
	CancelURL  string
	Metadata   map[string]string
}

CheckoutRequest creates a hosted/redirect checkout session.

type CheckoutSession

type CheckoutSession struct {
	ID  string
	URL string
}

CheckoutSession is a hosted checkout to redirect the customer to.

type Customer

type Customer struct {
	ID    string
	Email string
	Name  string
	Phone string
}

Customer identifies a payer.

type DriverFactory

type DriverFactory func(k *togo.Kernel) (PaymentProvider, error)

DriverFactory builds a PaymentProvider from the kernel (env-configured).

type LineItem

type LineItem struct {
	Name     string
	Amount   Money
	Quantity int64
}

LineItem is one item in a checkout.

type Money

type Money struct {
	Amount   int64  // minor units
	Currency string // ISO 4217, e.g. "USD", "EGP", "SAR"
}

Money is an amount in the smallest currency unit (cents, piasters, halalas…).

type PaymentProvider

type PaymentProvider interface {
	CreateCharge(ctx context.Context, req ChargeRequest) (*Charge, error)
	Refund(ctx context.Context, req RefundRequest) error
	CreateCheckoutSession(ctx context.Context, req CheckoutRequest) (*CheckoutSession, error)
	CreateCustomer(ctx context.Context, c Customer) (string, error)
	CreateSubscription(ctx context.Context, req SubscriptionRequest) (*Subscription, error)
	HandleWebhook(ctx context.Context, headers map[string]string, body []byte) (*WebhookEvent, error)
}

PaymentProvider is implemented by driver plugins. Not every gateway supports every operation — return a clear error for the unsupported ones.

type RefundRequest

type RefundRequest struct {
	ChargeID string
	Amount   *Money
}

RefundRequest refunds a charge (full when Amount is nil, else partial).

type Service

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

Service is the payment runtime stored on the kernel (k.Get("payment")).

func FromKernel

func FromKernel(k *togo.Kernel) (*Service, bool)

FromKernel fetches the payment service from the kernel container.

func (*Service) CreateCharge

func (s *Service) CreateCharge(ctx context.Context, req ChargeRequest) (*Charge, error)

func (*Service) CreateCheckoutSession

func (s *Service) CreateCheckoutSession(ctx context.Context, req CheckoutRequest) (*CheckoutSession, error)

func (*Service) CreateCustomer

func (s *Service) CreateCustomer(ctx context.Context, c Customer) (string, error)

func (*Service) CreateSubscription

func (s *Service) CreateSubscription(ctx context.Context, req SubscriptionRequest) (*Subscription, error)

func (*Service) Driver

func (s *Service) Driver() string

Driver returns the active driver name.

func (*Service) HandleWebhook

func (s *Service) HandleWebhook(ctx context.Context, headers map[string]string, body []byte) (*WebhookEvent, error)

func (*Service) Provider

func (s *Service) Provider() PaymentProvider

Provider returns the active driver implementation.

func (*Service) Refund

func (s *Service) Refund(ctx context.Context, req RefundRequest) error

type Subscription

type Subscription struct {
	ID       string
	Status   string
	PlanID   string
	Provider string
}

Subscription is a recurring subscription.

type SubscriptionRequest

type SubscriptionRequest struct {
	Customer Customer
	PlanID   string
	Metadata map[string]string
}

SubscriptionRequest starts a recurring subscription on a provider plan.

type WebhookEvent

type WebhookEvent struct {
	Type     string // e.g. charge.succeeded, subscription.canceled
	ID       string
	Provider string
	Raw      map[string]any
}

WebhookEvent is a provider webhook normalized to a common shape.