Go library for the Stripe API.
Go Other
Clone or download
brandur-stripe Merge pull request #631 from umpc/patch-1
Fix broken changelog link in readme
Latest commit caa0c20 Jul 21, 2018
Permalink
Failed to load latest commit information.
.github Added a template for GitHub issues Nov 3, 2016
account Fix decline_charge_on on the Account ressource Jul 6, 2018
applepaydomain Improve Iter documentation Jul 3, 2018
balance Improve Iter documentation Jul 3, 2018
bankaccount Improve Iter documentation Jul 3, 2018
bitcoinreceiver Improve Iter documentation Jul 3, 2018
bitcointransaction Improve Iter documentation Jul 3, 2018
card Improve Iter documentation Jul 3, 2018
charge Add support for Level III data on charge creation Jun 24, 2018
client Add support for the PaymentIntent resource Jul 9, 2018
countryspec Improve Iter documentation Jul 3, 2018
coupon Improve Iter documentation Jul 3, 2018
customer Improve Iter documentation Jul 3, 2018
discount Lint a few more packages Jul 3, 2018
dispute Improve Iter documentation Jul 3, 2018
ephemeralkey More packages properly linted Jul 3, 2018
event More packages properly linted Jul 3, 2018
exchangerate More packages properly linted Jul 3, 2018
fee More packages properly linted Jul 3, 2018
feerefund More packages properly linted Jul 3, 2018
fileupload More packages properly linted Jul 3, 2018
form Add methods to manage parameter types as pointers Jun 6, 2018
invoice More packages properly linted Jul 3, 2018
invoiceitem More packages properly linted Jul 3, 2018
issuerfraudrecord More packages properly linted Jul 3, 2018
loginlink Added more packages to the linter Jul 4, 2018
order Added more packages to the linter Jul 4, 2018
orderreturn Added more packages to the linter Jul 4, 2018
paymentintent Add support for the PaymentIntent resource Jul 9, 2018
paymentsource Added more packages to the linter Jul 4, 2018
payout Added more packages to the linter Jul 4, 2018
plan Added more packages to the linter Jul 4, 2018
product Added more packages to the linter Jul 4, 2018
recipient Added more packages to the linter Jul 4, 2018
recipienttransfer Use custom types for resources and string on params Jun 6, 2018
refund Added more packages to the linter Jul 4, 2018
reversal Added more packages to the linter Jul 4, 2018
scripts implement new flexible billing primitives Apr 2, 2018
sku Added more packages to the linter Jul 4, 2018
source Added more packages to the linter Jul 4, 2018
sourcetransaction Added more packages to the linter Jul 4, 2018
sub Added more packages to the linter Jul 4, 2018
subitem Added more packages to the linter Jul 4, 2018
testing Switch to port 12112 as default stripe-mock port for HTTPS Jul 19, 2018
threedsecure Move the description at the package level. Jul 4, 2018
token Added more packages to the linter Jul 4, 2018
topup Added missing getter for the topup iterator Jul 4, 2018
transfer Added more packages to the linter Jul 4, 2018
usagerecord Added more packages to the linter Jul 4, 2018
webhook doc(webhook): cleanup example Jun 6, 2018
.gitignore Add support for coveralls.io Dec 14, 2017
.travis.yml Switch to port 12112 as default stripe-mock port for HTTPS Jul 19, 2018
CHANGELOG Reformat CHANGELOG to CHANGELOG.md Oct 20, 2017
CHANGELOG.md Bump version to 36.1.1 Jul 17, 2018
LICENSE update license to Stripe Aug 30, 2014
Makefile Add support for the PaymentIntent resource Jul 9, 2018
README.md Fix broken changelog link in readme Jul 21, 2018
VERSION Bump version to 36.1.1 Jul 17, 2018
account.go Fix decline_charge_on on the Account ressource Jul 6, 2018
account_test.go Add support for decline_charge_on on Account Jul 5, 2018
address.go Rework most of the library naming and structure Jun 6, 2018
applepaydomain.go Rework most of the library naming and structure Jun 6, 2018
application.go Convert the rest of expansion functions to safer style Jun 11, 2018
application_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
balance.go Adds ExchangeRate field Jun 21, 2018
balance_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
bankaccount.go Convert the rest of expansion functions to safer style Jun 11, 2018
bankaccount_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
bitcoinreceiver.go Convert the rest of expansion functions to safer style Jun 11, 2018
bitcoinreceiver_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
bitcointransaction.go Convert the rest of expansion functions to safer style Jun 11, 2018
bitcointransaction_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
card.go Convert the rest of expansion functions to safer style Jun 11, 2018
card_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
charge.go Add extra params/properties for Level III on Charge Jun 26, 2018
charge_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
countryspec.go Add extra params to Get for exchangerate and countryspec Jun 14, 2018
coupon.go Add name to the Coupon resource Jun 16, 2018
coupon_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
currency.go Remove the currency package Jun 6, 2018
customer.go Convert the rest of expansion functions to safer style Jun 11, 2018
customer_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
discount.go Rename all properties in the library to match the API reference Jun 6, 2018
dispute.go Remove File in favor of FileUpload Jun 12, 2018
dispute_test.go Move File to FileUpload to make its location more intuitive Jun 11, 2018
ephemeralkey.go Rework most of the library naming and structure Jun 6, 2018
ephemeralkey_test.go Power test suite with stripe-mock + rework parameters with form Sep 15, 2017
error.go Use custom types for resources and string on params Jun 6, 2018
error_test.go Introduce `GetBackendWithConfig` and make logging configurable per ba… Jul 3, 2018
event.go Event should have an EventParams instead of relying on Params. Jun 14, 2018
event_test.go Rename all properties in the library to match the API reference Jun 6, 2018
example_test.go Remove the currency package Jun 6, 2018
exchangerate.go Add extra params to Get for exchangerate and countryspec Jun 14, 2018
exchangerate_test.go Add support for /v1/exchange_rates API requests Oct 31, 2017
fee.go Convert the rest of expansion functions to safer style Jun 11, 2018
fee_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
feerefund.go Convert the rest of expansion functions to safer style Jun 11, 2018
feerefund_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
fileupload.go Remove File in favor of FileUpload Jun 12, 2018
fileupload_test.go Remove File in favor of FileUpload Jun 12, 2018
invoice.go Add support for auto_advance on the Invoice resource Jul 11, 2018
invoice_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
invoiceitem.go Add `Quantity` and `UnitAmount` to `InvoiceItemParams` Jul 5, 2018
invoiceitem_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
issuerfraudrecord.go IssuerFraudRecord should have extra params for Get Jun 14, 2018
iter.go Organize core files alphabetically and into sections Jun 15, 2018
iter_test.go Rename Call2 -> Call, GetIter2 -> GetIter, Query2 -> Query Jun 14, 2018
loginlink.go Properly use params on loginlink creation and add `Params` to it. Jun 14, 2018
order.go Convert the rest of expansion functions to safer style Jun 11, 2018
order_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
orderreturn.go Convert the rest of expansion functions to safer style Jun 11, 2018
orderreturn_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
params.go Organize core files alphabetically and into sections Jun 15, 2018
params_test.go Add ListParams.SetStripeAccount and use it in tests Jun 6, 2018
paymentintent.go Add support for the PaymentIntent resource Jul 9, 2018
paymentintent_test.go Add support for the PaymentIntent resource Jul 9, 2018
paymentsource.go Convert the rest of expansion functions to safer style Jun 11, 2018
paymentsource_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
payout.go Changed the type of Payout.Destination from string to *PayoutDestination Jul 9, 2018
payout_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
plan.go Add support for listing plans by product Jun 19, 2018
plan_test.go Fix bucket_size -> divide_by Jun 7, 2018
product.go Add support for listing products by type Jun 19, 2018
product_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
recipient.go Convert the rest of expansion functions to safer style Jun 11, 2018
recipient_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
recipienttransfer.go Convert the rest of expansion functions to safer style Jun 11, 2018
recipienttransfer_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
refund.go Convert the rest of expansion functions to safer style Jun 11, 2018
refund_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
reversal.go Convert the rest of expansion functions to safer style Jun 11, 2018
reversal_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
review.go Convert the rest of expansion functions to safer style Jun 11, 2018
review_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
sku.go Convert the rest of expansion functions to safer style Jun 11, 2018
sku_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
source.go Convert the rest of expansion functions to safer style Jun 11, 2018
source_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
sourcetransaction.go Convert the rest of expansion functions to safer style Jun 11, 2018
sourcetransaction_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
stripe.go Bump version to 36.1.1 Jul 17, 2018
stripe_test.go Wire an `http.Client` from `NewBackends` through to backends Jul 17, 2018
sub.go Convert the rest of expansion functions to safer style Jun 11, 2018
sub_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
subitem.go Moving all int/uint to int64 for consistency Jun 6, 2018
threedsecure.go Moving all int/uint to int64 for consistency Jun 6, 2018
token.go Use custom types for resources and string on params Jun 6, 2018
topup.go Review fixes Jun 6, 2018
transfer.go Convert the rest of expansion functions to safer style Jun 11, 2018
transfer_test.go Convert the rest of expansion functions to safer style Jun 11, 2018
usage_record.go Use custom types for resources and string on params Jun 6, 2018
usage_record_test.go Moving all int/uint to int64 for consistency Jun 6, 2018
v32_migration_guide.md Fix typo in v32 migration guide Jun 6, 2018

README.md

Go Stripe

GoDoc Build Status Coverage Status

Summary

The official Stripe Go client library.

Versioning

Each revision of the binding is tagged and the version is updated accordingly.

Given Go's lack of built-in versioning, it is highly recommended you use a package management tool in order to ensure a newer version of the binding does not affect backwards compatibility.

To see the list of past versions, run git tag. To manually get an older version of the client, clone this repo, checkout the specific tag and build the library:

git clone https://github.com/stripe/stripe-go.git
cd stripe-go
git checkout api_version_tag
make build

For more details on changes between versions, see the binding changelog and API changelog.

Installation

go get github.com/stripe/stripe-go

Documentation

For a comprehensive list of examples, check out the API documentation.

For details on all the functionality in this library, see the GoDoc documentation.

Below are a few simple examples:

Customers

params := &stripe.CustomerParams{
	Balance:     stripe.Int64(-123),
	Description: stripe.String("Stripe Developer"),
	Email:       stripe.String("gostripe@stripe.com"),
}
params.SetSource("tok_1234")

customer, err := customer.New(params)

Charges

params := &stripe.ChargeListParams{Customer: stripe.String(customer.ID)}
params.Filters.AddFilter("include[]", "", "total_count")

// set this so you can easily retry your request in case of a timeout
params.Params.IdempotencyKey = stripe.NewIdempotencyKey()

i := charge.List(params)
for i.Next() {
	charge := i.Charge()
}

if err := i.Err(); err != nil {
	// handle
}

Events

i := event.List(nil)
for i.Next() {
	e := i.Event()

	// access event data via e.GetObjectValue("resource_name_based_on_type", "resource_property_name")
	// alternatively you can access values via e.Data.Object["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]

	// access previous attributes via e.GetPreviousValue("resource_name_based_on_type", "resource_property_name")
	// alternatively you can access values via e.Data.PrevPreviousAttributes["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]
}

Alternatively, you can use the event.Data.Raw property to unmarshal to the appropriate struct.

Authentication with Connect

There are two ways of authenticating requests when performing actions on behalf of a connected account, one that uses the Stripe-Account header containing an account's ID, and one that uses the account's keys. Usually the former is the recommended approach. See the documentation for more information.

To use the Stripe-Account approach, use SetStripeAccount() on a ListParams or Params class. For example:

// For a list request
listParams := &stripe.ChargeListParams{}
listParams.SetStripeAccount("acct_123")
// For any other kind of request
params := &stripe.CustomerParams{}
params.SetStripeAccount("acct_123")

To use a key, pass it to API's Init function:

import (
	"github.com/stripe/stripe-go"
	"github.com/stripe/stripe-go/client"
)

stripe := &client.API{}
stripe.Init("access_token", nil)

Google AppEngine

If you're running the client in a Google AppEngine environment, you'll need to create a per-request Stripe client since the http.DefaultClient is not available. Here's a sample handler:

import (
	"fmt"
	"net/http"

	"google.golang.org/appengine"
	"google.golang.org/appengine/urlfetch"

	"github.com/stripe/stripe-go"
	"github.com/stripe/stripe-go/client"
)

func handler(w http.ResponseWriter, r *http.Request) {
        c := appengine.NewContext(r)
        httpClient := urlfetch.Client(c)

        sc := stripeClient.New("sk_live_key", stripe.NewBackends(httpClient))

        chargeParams := &stripe.ChargeParams{
            Amount:      stripe.Int64(2000),
            Currency:    stripe.String(string(stripe.CurrencyUSD)),
            Description: stripe.String("Charge from Google App Engine"),
        }
        chargeParams.SetSource("tok_amex") // obtained with Stripe.js
        charge, err := sc.Charges.New(chargeParams)
        if err != nil {
            fmt.Fprintf(w, "Could not process payment: %v", err)
        }
        fmt.Fprintf(w, "Completed payment: %v", charge.ID)
}

Usage

While some resources may contain more/less APIs, the following pattern is applied throughout the library for a given $resource$:

Without a Client

If you're only dealing with a single key, you can simply import the packages required for the resources you're interacting with without the need to create a client.

import (
	"github.com/stripe/stripe-go"
	"github.com/stripe/stripe-go/$resource$"
)

// Setup
stripe.Key = "sk_key"

stripe.SetBackend("api", backend) // optional, useful for mocking

// Create
$resource$, err := $resource$.New(stripe.$Resource$Params)

// Get
$resource$, err := $resource$.Get(id, stripe.$Resource$Params)

// Update
$resource$, err := $resource$.Update(stripe.$Resource$Params)

// Delete
resourceDeleted, err := $resource$.Del(id, stripe.$Resource$Params)

// List
i := $resource$.List(stripe.$Resource$ListParams)
for i.Next() {
	$resource$ := i.$Resource$()
}

if err := i.Err(); err != nil {
	// handle
}

With a Client

If you're dealing with multiple keys, it is recommended you use client.API. This allows you to create as many clients as needed, each with their own individual key.

import (
	"github.com/stripe/stripe-go"
	"github.com/stripe/stripe-go/client"
)

// Setup
sc := &client.API{}
sc.Init("sk_key", nil) // the second parameter overrides the backends used if needed for mocking

// Create
$resource$, err := sc.$Resource$s.New(stripe.$Resource$Params)

// Get
$resource$, err := sc.$Resource$s.Get(id, stripe.$Resource$Params)

// Update
$resource$, err := sc.$Resource$s.Update(stripe.$Resource$Params)

// Delete
resourceDeleted, err := sc.$Resource$s.Del(id, stripe.$Resource$Params)

// List
i := sc.$Resource$s.List(stripe.$Resource$ListParams)
for i.Next() {
	resource := i.$Resource$()
}

if err := i.Err(); err != nil {
	// handle
}

Writing a Plugin

If you're writing a plugin that uses the library, we'd appreciate it if you identified using stripe.SetAppInfo:

stripe.SetAppInfo(&stripe.AppInfo{
    Name:    "MyAwesomePlugin",
    URL:     "https://myawesomeplugin.info",
    Version: "1.2.34",
})

This information is passed along when the library makes calls to the Stripe API. Note that while Name is always required, URL and Version are optional.

Development

Pull requests from the community are welcome. If you submit one, please keep the following guidelines in mind:

  1. Code must be go fmt compliant.
  2. All types, structs and funcs should be documented.
  3. Ensure that make test succeeds.

Test

The test suite needs testify's require package to run:

github.com/stretchr/testify/require

It also depends on [stripe-mock], so make sure to fetch and run it from a background terminal ([stripe-mock's README][stripe-mock] also contains instructions for installing via Homebrew and other methods):

go get -u github.com/stripe/stripe-mock
stripe-mock

Run all tests:

go test ./...

Run tests for one package:

go test ./invoice

Run a single test:

go test ./invoice -run TestInvoiceGet

For any requests, bug or comments, please open an issue or submit a pull request.