README
¶
Pago Go SDK
Go client for the Pago API.
This SDK is generated from the Pago OpenAPI specification. Do not edit it by hand.
Installation
go get github.com/pago-sh/pago-go
Usage
package main
import (
"context"
"fmt"
"os"
"github.com/pago-sh/pago-go"
"github.com/pago-sh/pago-go/v2026_04"
)
func main() {
client := v2026_04.New(pago.WithAccessToken(os.Getenv("PAGO_ACCESS_TOKEN")))
product, err := client.Products.Get(context.Background(), "PRODUCT_ID")
if err != nil {
panic(err)
}
fmt.Println(product.Name)
}
Each API version lives in its own package:
github.com/pago-sh/pago-go/v2026_04— API version2026-04
Configuration
New accepts the options of the runtime package:
client := v2026_04.New(
pago.WithAccessToken("..."),
pago.WithBaseURL("https://api.pago.sh"),
pago.WithHTTPClient(&http.Client{Timeout: 30 * time.Second}),
)
Pagination
Paginated endpoints expose an ...AutoPaging iterator that fetches every page
transparently:
for order, err := range client.Orders.ListAutoPaging(ctx, v2026_04.OrdersListParams{}) {
if err != nil {
return err
}
fmt.Println(order.ID)
}
Errors
Every error returned by the SDK implements pago.Error. Documented error
responses have a generated type carrying the decoded body:
product, err := client.Products.Get(ctx, "unknown")
var notFound *v2026_04.ResourceNotFoundError
switch {
case errors.As(err, ¬Found):
// notFound.Data holds the decoded body.
case errors.As(err, new(*pago.RateLimitError)):
// Retry later.
}
Unions
The API uses polymorphic schemas that Go cannot express directly. They are generated as a struct with one pointer field per variant, with the JSON marshalling wired up for you:
switch {
case benefit.BenefitCustom != nil:
fmt.Println(benefit.BenefitCustom.Description)
case benefit.BenefitDiscord != nil:
fmt.Println(benefit.BenefitDiscord.Description)
}
Webhooks
ValidateEvent verifies the Standard Webhooks
signature of a request and returns the typed event:
func handler(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
event, err := v2026_04.ValidateEvent(body, r.Header, os.Getenv("PAGO_WEBHOOK_SECRET"))
if err != nil {
w.WriteHeader(http.StatusForbidden)
return
}
switch event := event.(type) {
case *v2026_04.WebhookOrderCreatedPayload:
fmt.Println(event.Data.ID)
}
}
License
MIT
Documentation
¶
Overview ¶
Package pago is the runtime shared by every generated Pago API version package. It carries the HTTP client, the error hierarchy and the webhook signature verification.
Use it through a versioned client, for example:
client := v2026_04.New(pago.WithAccessToken(os.Getenv("PAGO_ACCESS_TOKEN")))
Index ¶
- Constants
- func AddQueryValue(query url.Values, key string, value any)
- func Stringify(value any) string
- func ValidateWebhook(body []byte, headers http.Header, secret string, ...) (string, error)
- func VerifyWebhookSignature(body []byte, headers http.Header, secret string) error
- type APIError
- type ClientBase
- type EncodingError
- type Error
- type ErrorDecoder
- type NetworkError
- type Option
- type RateLimitError
- type Request
- type ResponseType
- type ServerError
- type WebhookError
- type WebhookUnknownTypeError
- type WebhookVerificationError
Constants ¶
const DefaultBaseURL = "https://api.pago.sh"
DefaultBaseURL is the base URL of the Pago API.
const Version = "1.0.0"
Version is the version of this SDK.
const WebhookSecretPrefix = "whsec_"
WebhookSecretPrefix is the prefix every Pago endpoint secret carries. What follows it is the base64-encoded HMAC signing key.
const WebhookToleranceSeconds = 5 * 60
WebhookToleranceSeconds is how far a webhook timestamp may drift from the current time before the message is rejected.
Variables ¶
This section is empty.
Functions ¶
func AddQueryValue ¶
AddQueryValue appends value to the query string under key.
It is the single encoding point used by every generated parameter struct:
- nil values and nil pointers are skipped, which is how an unset optional parameter stays out of the query string;
- pointers and interfaces are followed;
- slices repeat the key once per element;
- maps use the deepObject form key[subkey]=value, sorted by key so the query string is deterministic;
- anything else is rendered with Stringify.
func ValidateWebhook ¶
func ValidateWebhook( body []byte, headers http.Header, secret string, eventTypes map[string]struct{}, ) (string, error)
ValidateWebhook verifies the signature of a raw webhook request and returns its event type.
It implements the Standard Webhooks specification: the signed content is "<webhook-id>.<webhook-timestamp>.<body>", authenticated with HMAC-SHA256 and encoded as standard base64. The signing key is not the secret string itself — it is the base64 decoding of whatever follows the "whsec_" prefix. Headers are read through http.Header, so passing (*http.Request).Header works directly.
Types ¶
type APIError ¶
type APIError struct {
StatusCode int
Body []byte
// Header holds the response headers, useful for request tracing.
Header http.Header
// contains filtered or unexported fields
}
APIError is returned for any 4xx response that has no generated error type. Every generated error type embeds it, so errors.As with a *APIError target matches those too.
type ClientBase ¶
type ClientBase struct {
// contains filtered or unexported fields
}
ClientBase performs the HTTP requests of a versioned client.
func NewClientBase ¶
func NewClientBase(version string, options ...Option) *ClientBase
NewClientBase builds the runtime client used by a versioned client.
func (*ClientBase) BaseURL ¶
func (c *ClientBase) BaseURL() string
BaseURL returns the base URL requests are sent to.
func (*ClientBase) Do ¶
Do performs the request and decodes a successful response into out, which must be a non-nil pointer unless the response type is ResponseNone.
func (*ClientBase) HTTPClient ¶
func (c *ClientBase) HTTPClient() *http.Client
HTTPClient returns the underlying http.Client.
func (*ClientBase) Version ¶
func (c *ClientBase) Version() string
Version returns the API version sent with every request.
type EncodingError ¶
EncodingError is returned when a request body cannot be encoded, or when a successful response body cannot be decoded into the expected type.
func (*EncodingError) Error ¶
func (e *EncodingError) Error() string
func (*EncodingError) Unwrap ¶
func (e *EncodingError) Unwrap() error
type Error ¶
type Error interface {
error
// contains filtered or unexported methods
}
Error is implemented by every error returned by this SDK, which makes it possible to tell an SDK failure apart from any other error with errors.As.
type ErrorDecoder ¶
ErrorDecoder builds a typed error from an error response.
type NetworkError ¶
type NetworkError struct {
Err error
// contains filtered or unexported fields
}
NetworkError is returned when the request never produced an HTTP response.
func (*NetworkError) Error ¶
func (e *NetworkError) Error() string
func (*NetworkError) Unwrap ¶
func (e *NetworkError) Unwrap() error
type Option ¶
type Option func(*ClientBase)
Option configures a ClientBase.
func WithAccessToken ¶
WithAccessToken sets the bearer token sent with every request.
func WithBaseURL ¶
WithBaseURL overrides the API base URL, which is useful for testing against a local server.
func WithHTTPClient ¶
WithHTTPClient injects the http.Client used to perform requests, which is the hook for custom timeouts, proxies, retries or instrumentation.
func WithHeader ¶
WithHeader adds a header to every request.
func WithVersion ¶
WithVersion overrides the API version header sent with every request.
type RateLimitError ¶
type RateLimitError struct {
APIError
// RetryAfter is the value of the Retry-After header in seconds, or -1 when
// the header is absent or malformed.
RetryAfter int
}
RateLimitError is returned for a 429 response.
func (*RateLimitError) Error ¶
func (e *RateLimitError) Error() string
func (*RateLimitError) Unwrap ¶
func (e *RateLimitError) Unwrap() error
type Request ¶
type Request struct {
Method string
Path string
PathParams map[string]any
Query url.Values
Body any
ResponseType ResponseType
// Errors maps an HTTP status code to the decoder of its documented error
// body.
Errors map[int]ErrorDecoder
}
Request describes a single API call.
type ResponseType ¶
type ResponseType string
ResponseType describes how the body of a successful response is decoded.
const ( // ResponseJSON decodes the response body as JSON. ResponseJSON ResponseType = "json" // ResponseText decodes the response body as plain text. ResponseText ResponseType = "text" // ResponseNone discards the response body. ResponseNone ResponseType = "none" )
type ServerError ¶
ServerError is returned for any 5xx response.
func (*ServerError) Error ¶
func (e *ServerError) Error() string
type WebhookError ¶
WebhookError is the base error raised while processing a Pago webhook.
func NewWebhookError ¶
func NewWebhookError(message string, err error) *WebhookError
NewWebhookError builds a WebhookError.
func (*WebhookError) Error ¶
func (e *WebhookError) Error() string
func (*WebhookError) Unwrap ¶
func (e *WebhookError) Unwrap() error
type WebhookUnknownTypeError ¶
type WebhookUnknownTypeError struct {
WebhookError
EventType string
}
WebhookUnknownTypeError is raised when a verified webhook has a type this SDK version does not know about.
func NewWebhookUnknownTypeError ¶
func NewWebhookUnknownTypeError(eventType string) *WebhookUnknownTypeError
NewWebhookUnknownTypeError builds a WebhookUnknownTypeError.
func (*WebhookUnknownTypeError) Unwrap ¶
func (e *WebhookUnknownTypeError) Unwrap() error
type WebhookVerificationError ¶
type WebhookVerificationError struct {
WebhookError
}
WebhookVerificationError is raised when a webhook signature cannot be verified.
func NewWebhookVerificationError ¶
func NewWebhookVerificationError(message string) *WebhookVerificationError
NewWebhookVerificationError builds a WebhookVerificationError.
func (*WebhookVerificationError) Unwrap ¶
func (e *WebhookVerificationError) Unwrap() error
Source Files
Directories