zstripe

README

zstripe is a set of utility functions for working with the Stripe API.

It's not a full "client library"; but just a few functions that make it easy to call api.stripe.com.

Personally, I prefer working with the API "directly", instead of using an elaborate wrapper/client library. YMMV. Check out stripe-go if you want a full client library.

See zstripe_stripe_test.go for usage examples.

Documentation

Overview

Package zstripe is a set of utility functions for working with the Stripe API.

It's not a full "client library"; but just a few functions that make it easy to call api.stripe.com.

Index

• Variables
• func Request(scan interface{}, method, url string, body string) (*http.Response, error)
• type Body
  • func (b Body) Encode() string
• type Error
  • func (e Error) Error() string
• type Event
  • func (e *Event) Read(r *http.Request) error
• type ID
• type StripeError

Variables

var (
	ErrWebhookTooOld           = errors.New("webhook too old")
	ErrWebhookInvalidHeader    = errors.New("invalid Stripe-Signature header")
	ErrWebhookInvalidSignature = errors.New("invalid signature")
)

Possible errors when validating a webhook.

var (
	// Stripe signing secret (whsec_*).
	SignSecret string

	// Reject signatures older than this, to prevent replay attacks.
	MaxAge = 300 * time.Second
)

var (
	SecretKey     = ""                       // Your Stripe secret key (sk_*).
	PublicKey     = ""                       // Publishable key (pk_*).
	StripeVersion = ""                       // Stripe version to use; e.g. "2020-08-27"
	API           = "https://api.stripe.com" // API base URL.
	DebugURL      = false                    // Show URLs as they're requested.
	DebugReqBody  = false                    // Show body of request.
	DebugRespBody = false                    // Show body of response
	MaxRetry      = 30 * time.Second         // Max time to retry requests.
)

var Client = http.Client{Timeout: 10 * time.Second}

Client to use for all API requests.

var ErrRetry = errors.New("retried longer than MaxRetry")

ErrRetry is used when we've retried longer than MaxRetry.

Functions

func Request

func Request(scan interface{}, method, url string, body string) (*http.Response, error)

Request something from the Stripe API.

The response body is unmarshaled to scan as JSON.

Responses with the Stripe-Should-Retry header set will be retried every two seconds. ErrRetry is returned if it still fails after MaxRetry.

A response code higher than 399 will return an Error, but won't affect the behaviour of this function.

The request body is an URL-encoded form (Stripe doesn't accept JSON), usually you will want to do something like this:

f := make(url.Values)
f.Set("name", "Martin Tournoij")
body := strings.NewReader(body.Encode())

There are many libraries to convert a struct or map to an encoded form, but for many simpler application it's not really needed, which is why it's not done automatically.

The Body on the returned http.Response is closed.

This will use the global SecretKey, which must be set.

Types

type Body

type Body map[string]string

Body for requests.

func (Body) Encode

func (b Body) Encode() string

Encode the values with url.Values.Encode().

type Error

type Error struct {
	Method, URL string
	Status      string
	StatusCode  int
	StripeError StripeError `json:"error"`
}

Error is used when the status code is not 200 OK.

func (Error) Error

func (e Error) Error() string

type Event

type Event struct {
	ID              string `json:"id"`
	Type            string `json:"type"`
	Livemode        bool   `json:"livemode"`
	Created         int64  `json:"created"`
	Account         string `json:"account"`          // Account that originated the event (Connect only).
	PendingWebhooks int64  `json:"pending_webhooks"` // Number of webhooks that still need to be delivered.

	Data struct {
		Raw json.RawMessage `json:"object"`

		// Relevant resource, e.g. "invoice.created" will have the full invoice
		// object.
		Object map[string]interface{}

		// Names of changed attributes with their previous values for *.updated
		// events.
		PreviousAttributes map[string]interface{} `json:"previous_attributes"`
	} `json:"data"`

	// Details about the request that created the event; may be empty as not all
	// events are created by a request.
	Request struct {
		ID             string `json:"id"`
		IdempotencyKey string `json:"idempotency_key"`
	} `json:"request"`
}

https://stripe.com/docs/api#events.

func (*Event) Read

func (e *Event) Read(r *http.Request) error

Read the event from the request body and validate the signature.

type ID

type ID struct {
	ID string `json:"id"`
}

ID if you're interested in just retrieving the ID from a response.

type StripeError

type StripeError struct {
	// Error type; always set and one of:
	// api_connection_error, api_error, authentication_error, card_error, idempotency_error, invalid_request_error, rate_limit_error.
	Type string `json:"type"`

	Param        string `json:"param"`         // Parameter related to the error, to display a message near the form field.
	Message      string `json:"message"`       // Human-readable message.
	Code         string `json:"code"`          // Error code; may be blank.
	DocURL       string `json:"doc_url"`       // URL to more information.
	Charge       string `json:"charge"`        // ID of the failed charge for card errors.
	DeclinedCode string `json:"declined_code"` // Card issuer's reason for declining a card, if provided.
}

StripeError is Stripe's response on errors. https://stripe.com/docs/api/errors