paymos

package module
v2.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 17 Imported by: 0

README

Paymos Go SDK

Official dependency-free Go client for the Paymos Merchant API. All network methods accept context.Context; signing, retries, cursor traversal and webhook verification follow the shared Paymos SDK conformance contract.

go get github.com/Paymos-labs/go-sdk/v2@latest

import paymos "github.com/Paymos-labs/go-sdk/v2"

client, _ := paymos.NewClient("pk_test_...", "sk_test_...")
invoice, err := client.Invoices.Create(ctx, paymos.CreateInvoiceParams{
	ProjectID: "prj_...", Amount: "10.00", Currency: "USD",
	ExternalOrderID: "order_123",
})

Use NewInvoiceIterator and NewWithdrawalIterator for bounded cursor traversal. Non-success responses return *paymos.APIError, which preserves the status, response body, problem details, error kind, field, and Retry-After.

verifier, _ := paymos.NewWebhookVerifier(os.Getenv("PAYMOS_WEBHOOK_SECRET"), 5*time.Minute)
if err := verifier.Verify(signatureHeader, rawBody, time.Now()); err != nil {
    // Return 401 without parsing or processing the payload.
}

Never place the API secret in a browser or mobile application. Full documentation: https://paymos.io/docs/server-sdks

Documentation

Overview

Package paymos provides the official server-side Go client for the Paymos Merchant API. It includes canonical HMAC signing, typed API errors, bounded cursor traversal, safe retries, and raw-body webhook verification.

Index

Constants

View Source 
const Version = "2.1.1"

Variables

View Source 
var ErrWebhookSignature = errors.New("Paymos webhook signature mismatch")
View Source 
var ErrWebhookTimestamp = errors.New("Paymos webhook timestamp outside tolerance")

Functions

func AuthorizationHeader 

func AuthorizationHeader(apiKey, apiSecret, timestamp, method, path, query string, body []byte) string

func BuildQuery 

func BuildQuery(filters any) (string, error)

func EncodePathSegment 

func EncodePathSegment(value string) string

func Sign 

func Sign(secret, value string) string

func StringToSign 

func StringToSign(timestamp, method, path, query string, body []byte) string

Types

type APIError 

type APIError struct {
	Status  int
	Body    []byte
	Header  http.Header
	Problem Problem
}

func (*APIError) Code 

func (e *APIError) Code() string

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Field 

func (e *APIError) Field() *string

func (*APIError) Kind 

func (e *APIError) Kind() string

func (*APIError) RetryAfter 

func (e *APIError) RetryAfter() (time.Duration, bool)

type Balance 

type Balance struct {
	Currency  string `json:"currency"`
	Available string `json:"available"`
}

type BalancesService 

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

func (*BalancesService) Get 

func (s *BalancesService) Get(ctx context.Context) ([]Balance, error)

type Client 

type Client struct {
	Invoices    *InvoicesService
	Withdrawals *WithdrawalsService
	Balances    *BalancesService
	System      *SystemService
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(apiKey, apiSecret string, options ...Option) (*Client, error)

type CreateInvoiceParams 

type CreateInvoiceParams struct {
	ProjectID             string  `json:"project_id"`
	Amount                string  `json:"amount"`
	Currency              string  `json:"currency"`
	ExternalOrderID       string  `json:"external_order_id"`
	Network               *string `json:"network,omitempty"`
	AllowMultiplePayments *bool   `json:"allow_multiple_payments,omitempty"`
	CustomerFeePercent    *int    `json:"customer_fee_percent,omitempty"`
	ClientID              *string `json:"client_id,omitempty"`
}

type CreateWithdrawalParams 

type CreateWithdrawalParams struct {
	DestinationAddress string `json:"destination_address"`
	Network            string `json:"network"`
	Currency           string `json:"currency"`
	Amount             string `json:"amount"`
	ExternalOrderID    string `json:"external_order_id"`
}

type HTTPDoer 

type HTTPDoer interface {
	Do(*http.Request) (*http.Response, error)
}

type Invoice 

type Invoice struct {
	InvoiceID   string        `json:"invoice_id"`
	ProjectID   string        `json:"project_id"`
	Status      InvoiceStatus `json:"status"`
	IsFinal     bool          `json:"is_final"`
	IsTest      bool          `json:"is_test"`
	PaymentURL  string        `json:"payment_url"`
	Order       Order         `json:"order"`
	Payment     *Payment      `json:"payment,omitempty"`
	CreatedAt   int64         `json:"created_at"`
	UpdatedAt   int64         `json:"updated_at"`
	ExpiresAt   *int64        `json:"expires_at,omitempty"`
	CompletedAt *int64        `json:"completed_at,omitempty"`
}

type InvoiceListItem 

type InvoiceListItem struct {
	InvoiceID       string        `json:"invoice_id"`
	ProjectID       string        `json:"project_id"`
	ExternalOrderID string        `json:"external_order_id"`
	ClientID        *string       `json:"client_id,omitempty"`
	Status          InvoiceStatus `json:"status"`
	IsFinal         bool          `json:"is_final"`
	IsTest          bool          `json:"is_test"`
	Amount          string        `json:"amount"`
	Currency        string        `json:"currency"`
	Network         *string       `json:"network,omitempty"`
	CreatedAt       int64         `json:"created_at"`
	ExpiresAt       *int64        `json:"expires_at,omitempty"`
	CompletedAt     *int64        `json:"completed_at,omitempty"`
}

type InvoiceListParams 

type InvoiceListParams struct {
	Limit           int             `json:"limit,omitempty"`
	Cursor          *string         `json:"cursor,omitempty"`
	Status          []InvoiceStatus `json:"status,omitempty"`
	ExternalOrderID *string         `json:"external_order_id,omitempty"`
	ProjectID       *string         `json:"project_id,omitempty"`
	CreatedFrom     *int64          `json:"created_from,omitempty"`
	CreatedTo       *int64          `json:"created_to,omitempty"`
}

type InvoiceStatus 

type InvoiceStatus string
const (
	InvoiceAwaitingClient   InvoiceStatus = "awaiting_client"
	InvoiceAwaitingPayment  InvoiceStatus = "awaiting_payment"
	InvoiceConfirming       InvoiceStatus = "confirming"
	InvoiceUnderpaidWaiting InvoiceStatus = "underpaid_waiting"
	InvoicePaid             InvoiceStatus = "paid"
	InvoicePaidOver         InvoiceStatus = "paid_over"
	InvoiceUnderpaid        InvoiceStatus = "underpaid"
	InvoiceExpired          InvoiceStatus = "expired"
	InvoiceCancelled        InvoiceStatus = "cancelled"
)

type InvoicesService 

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

func (*InvoicesService) Cancel 

func (s *InvoicesService) Cancel(ctx context.Context, id, reason string) (Invoice, error)

func (*InvoicesService) ConfirmPayment 

func (s *InvoicesService) ConfirmPayment(ctx context.Context, id, currency, network string) (Invoice, error)

func (*InvoicesService) Create 

func (s *InvoicesService) Create(ctx context.Context, payload CreateInvoiceParams) (Invoice, error)

func (*InvoicesService) Get 

func (s *InvoicesService) Get(ctx context.Context, id string) (Invoice, error)

func (*InvoicesService) List 

func (s *InvoicesService) List(ctx context.Context, filters InvoiceListParams) (Page[InvoiceListItem], error)

func (*InvoicesService) SimulatePayment 

func (s *InvoicesService) SimulatePayment(ctx context.Context, id, stage string) (Invoice, error)

type Iterator 

type Iterator[T any, F any] struct {
	// contains filtered or unexported fields
}

func NewInvoiceIterator 

func NewInvoiceIterator(service *InvoicesService, filters InvoiceListParams, maxPages int) *Iterator[InvoiceListItem, InvoiceListParams]

func NewWithdrawalIterator 

func NewWithdrawalIterator(service *WithdrawalsService, filters WithdrawalListParams, maxPages int) *Iterator[Withdrawal, WithdrawalListParams]

func (*Iterator[T, F]) Next 

func (i *Iterator[T, F]) Next(ctx context.Context) (T, bool, error)

type Option 

type Option func(*Client) error

func WithBaseURL 

func WithBaseURL(value string) Option

func WithClock 

func WithClock(value func() time.Time) Option

func WithHTTPClient 

func WithHTTPClient(value HTTPDoer) Option

func WithRetry 

func WithRetry(max int, baseDelay time.Duration) Option

type Order 

type Order struct {
	ExternalID string  `json:"external_id"`
	ClientID   *string `json:"client_id,omitempty"`
	Amount     string  `json:"amount"`
	Currency   string  `json:"currency"`
	Network    *string `json:"network,omitempty"`
}

type Page 

type Page[T any] struct {
	Items      []T     `json:"items"`
	NextCursor *string `json:"next_cursor"`
}

type Payment 

type Payment struct {
	Currency        string     `json:"currency"`
	Network         string     `json:"network"`
	ChainID         int64      `json:"chain_id"`
	ContractAddress *string    `json:"contract_address,omitempty"`
	Expected        string     `json:"expected"`
	Address         *string    `json:"address,omitempty"`
	ExchangeRate    *string    `json:"exchange_rate,omitempty"`
	Paid            *string    `json:"paid,omitempty"`
	Remaining       *string    `json:"remaining,omitempty"`
	Fee             *string    `json:"fee,omitempty"`
	Net             *string    `json:"net,omitempty"`
	Transfers       []Transfer `json:"transfers,omitempty"`
}

type Problem 

type Problem struct {
	Type   string         `json:"type"`
	Title  string         `json:"title"`
	Status int            `json:"status"`
	Detail string         `json:"detail"`
	Code   string         `json:"code"`
	Field  *string        `json:"field"`
	Errors []ProblemError `json:"errors"`
}

type ProblemError 

type ProblemError struct {
	Code    string  `json:"code"`
	Field   *string `json:"field"`
	Message string  `json:"message"`
}

type ServerTime 

type ServerTime struct {
	ServerTime int64 `json:"server_time"`
}

type SystemService 

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

func (*SystemService) Time 

func (s *SystemService) Time(ctx context.Context) (ServerTime, error)

type Transfer 

type Transfer struct {
	TxHash                  string  `json:"tx_hash"`
	Amount                  string  `json:"amount"`
	Status                  string  `json:"status"`
	CreatedAt               int64   `json:"created_at"`
	ConfirmedAt             *int64  `json:"confirmed_at,omitempty"`
	RequiredConfirmations   *int    `json:"required_confirmations,omitempty"`
	EstimatedConfirmationAt *int64  `json:"estimated_confirmation_at,omitempty"`
	ExplorerURL             *string `json:"explorer_url,omitempty"`
}

type WebhookEvent 

type WebhookEvent[T any] struct {
	EventID    string `json:"event_id"`
	EventType  string `json:"event_type"`
	Version    int    `json:"version"`
	OccurredAt int64  `json:"occurred_at"`
	Data       T      `json:"data"`
}

type WebhookVerifier 

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

func NewWebhookVerifier 

func NewWebhookVerifier(secret string, tolerance time.Duration) (*WebhookVerifier, error)

func (*WebhookVerifier) ConstructEvent 

func (v *WebhookVerifier) ConstructEvent(header string, body []byte, now time.Time, target any) error

func (*WebhookVerifier) Verify 

func (v *WebhookVerifier) Verify(header string, body []byte, now time.Time) error

type Withdrawal 

type Withdrawal struct {
	WithdrawalID       string           `json:"withdrawal_id"`
	ExternalOrderID    string           `json:"external_order_id"`
	Status             WithdrawalStatus `json:"status"`
	IsFinal            bool             `json:"is_final"`
	IsTest             bool             `json:"is_test"`
	Amount             string           `json:"amount"`
	Fee                *string          `json:"fee,omitempty"`
	Currency           string           `json:"currency"`
	Network            string           `json:"network"`
	DestinationAddress string           `json:"destination_address"`
	TxHash             *string          `json:"tx_hash,omitempty"`
	ExplorerURL        *string          `json:"explorer_url,omitempty"`
	CreatedAt          int64            `json:"created_at"`
	CompletedAt        *int64           `json:"completed_at,omitempty"`
	FailedAt           *int64           `json:"failed_at,omitempty"`
	CancelledAt        *int64           `json:"cancelled_at,omitempty"`
}

type WithdrawalListParams 

type WithdrawalListParams struct {
	Limit           int                `json:"limit,omitempty"`
	Cursor          *string            `json:"cursor,omitempty"`
	Status          []WithdrawalStatus `json:"status,omitempty"`
	ExternalOrderID *string            `json:"external_order_id,omitempty"`
	CreatedFrom     *int64             `json:"created_from,omitempty"`
	CreatedTo       *int64             `json:"created_to,omitempty"`
}

type WithdrawalStatus 

type WithdrawalStatus string
const (
	WithdrawalCreated       WithdrawalStatus = "created"
	WithdrawalPendingReview WithdrawalStatus = "pending_review"
	WithdrawalSigned        WithdrawalStatus = "signed"
	WithdrawalCancelling    WithdrawalStatus = "cancelling"
	WithdrawalCompleted     WithdrawalStatus = "completed"
	WithdrawalFailed        WithdrawalStatus = "failed"
	WithdrawalCancelled     WithdrawalStatus = "cancelled"
)

type WithdrawalsService 

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

func (*WithdrawalsService) Cancel 

func (s *WithdrawalsService) Cancel(ctx context.Context, id, reason string) (Withdrawal, error)

func (*WithdrawalsService) Create 

func (s *WithdrawalsService) Create(ctx context.Context, payload CreateWithdrawalParams) (Withdrawal, error)

func (*WithdrawalsService) Get 

func (s *WithdrawalsService) Get(ctx context.Context, id string) (Withdrawal, error)

func (*WithdrawalsService) List 

func (s *WithdrawalsService) List(ctx context.Context, filters WithdrawalListParams) (Page[Withdrawal], error)

func (*WithdrawalsService) SimulateCompletion 

func (s *WithdrawalsService) SimulateCompletion(ctx context.Context, id string) (Withdrawal, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.