sleet

README

Sleet

Payment abstraction library - interact with different Payment Service Providers (PsP) with one unified interface.

Installation

go get github.com/BoltApp/sleet

Methodology

Wherever possible, we try to use native Golang implementations of the PsP's API. We also assume that the caller can pass along raw credit card information (i.e. are PCI compliant)

Supported API Calls

1. Authorize
2. Capture
3. Void
4. Refund

To run tests

The following environment variables are needed in order to run tests

$ export ADYEN_USERNAME="YOUR_ADYEN_WEBSERVICE_USERNAME"
$ export ADYEN_ACCOUNT="YOUR_ADYEN_MERCHANT_ACCOUNT"
$ export ADYEN_PASSWORD="YOUR_ADYEN_WEBSERVICE_PASSWORD"
$ export STRIPE_TEST_KEY="YOUR_STRIPE_API_KEY"
$ export AUTH_NET_LOGIN_ID="YOUR_AUTHNET_LOGIN"
$ export AUTH_NET_TXN_KEY="YOUR_AUTHNET_TXN_KEY"
$ export BRAINTREE_MERCHANT_ID="YOUR_BRAINTREE_MERCHANT_ACCOUNT"
$ export BRAINTREE_PUBLIC_KEY="YOUR_BRAINTREE_PUBLIC_KEY"
$ export BRAINTREE_PRIVATE_ID="YOUR_BRAINTREE_PRIVATE_KEY"
$ export CYBERSOURCE_ACCOUNT="YOUR_CYBS_ACCOUNT"
$ export CYBERSOURCE_API_KEY="YOUR_CYBS_KEY"
$ export CYBERSOURCE_SHARED_SECRET="YOUR_CYBS_SECRET"
$ export NMI_SECURITY_KEY="YOUR_NMI_PRIVATE_KEY"

Then run tests with: go test ./integration-tests/

Code Example for Auth + Capture

import (
  "github.com/BoltApp/sleet"
  "github.com/BoltApp/sleet/gateways/authorize_net"
)
// Generate a client using your own credentials
client := authorize_net.NewClient("AUTH_NET_LOGIN_ID", "AUTH_NET_TXN_KEY")

amount := sleet.Amount{
  Amount: 100,
  Currency: "USD",
}
card := sleet.CreditCard{
  FirstName: "Bolt",
  LastName: "Checkout",
  Number: "4111111111111111",
  ExpMonth: 8,
  EpxYear: 2010,
  CVV: "000",
}
streetAddress := "22 Linda St."
locality := "Hoboken"
regionCode := "NJ"
postalCode := "07030"
countryCode := "US"
address := sleet.BillingAddress{
  StreetAddress1: &streetAddress,
  Locality:       &locality,
  RegionCode:     &regionCode,
  PostalCode:     &postalCode,
  CountryCode:    &countryCode,
}
authorizeRequest := sleet.AuthorizationRequest{
  Amount: &amount,
  CreditCard: &card,
  BillingAddress: &address,
}
authorizeResponse, _ := client.Authorize(&authorizeRequest)

captureRequest := sleet.CaptureRequest{
  Amount:               &amount,
  TransactionReference: authorizeResponse.TransactionReference,
}
client.Capture(&captureRequest)

Supported Gateways

• Authorize.Net
• CyberSource
• Stripe
• Adyen
• Braintree
• NMI

Documentation

Index

• Variables
• func AmountToString(amount *Amount) string
• type AVSResponse
  • func (code AVSResponse) String() string
• type Amount
• type AuthorizationRequest
• type AuthorizationResponse
• type BillingAddress
• type CVVResponse
  • func (code CVVResponse) String() string
• type CaptureRequest
• type CaptureResponse
• type Client
• type Code
  • func GetCode(code string) (Code, error)
  • func (c Code) String() string
• type CreditCard
• type Currency
• type Level3Data
• type LineItem
• type RefundRequest
• type RefundResponse
• type VoidRequest
• type VoidResponse

Variables

var CURRENCIES = map[Code]Currency{}/* 166 elements not displayed */

CURRENCIES maps the precision to the currency symbol used for lookups for some PsP providers that rely on these values for amount calculation One example is Braintree which uses its own amount structure requiring the precision of a currency

Functions

func AmountToString

func AmountToString(amount *Amount) string

AmountToString converts string with floating point eg 12.34.

Types

type AVSResponse

type AVSResponse int

AVSResponse represents a possible Address Verification System response.

const (
	AVSResponseUnknown     AVSResponse = iota
	AVSResponseError                   // The AVS is unavailable due to a system error.
	AVSResponseUnsupported             // The issuing bank does not support AVS.
	AVSResponseSkipped                 // Verification was not performed for this transaction.

	AVSResponseZip9MatchAddressMatch     // 9-digit ZIP matches, street address matches.
	AVSResponseZip9MatchAddressNoMatch   // 9-digit ZIP matches, street address doesn't match.
	AVSResponseZip5MatchAddressMatch     // 5-digit ZIP matches, street address matches.
	AVSResponseZip5MatchAddressNoMatch   // 5-digit ZIP matches, street address doesn't match.
	AVSresponseZipMatchAddressMatch      // 5 or 9 digit ZIP matches, street address matches.
	AVSResponseZipNoMatchAddressMatch    // ZIP doesn't match, street address matches.
	AVSResponseZipMatchAddressUnverified // ZIP matches, street address not verified.
	AVSResponseZipUnverifiedAddressMatch // ZIP not verified, street address matches.
	AVSResponseMatch                     // Generic "everything matches"
	AVSResponseNoMatch                   // Generic "nothing matches"

	AVSResponseNonUsZipMatchAddressMatch      // (Non U.S. cards) ZIP matches, street address matches.
	AVSResponseNonUsZipNoMatchAddressNoMatch  // (Non U.S. cards) ZIP and street address don't match.
	AVSResponseNonUsZipUnverifiedAddressMatch // (Non U.S. cards) ZIP unverified, street address matches.

	AVSResponseNameNoMatch                       // Cardholder's name doesn't match.
	AVSResponseNameNoMatchAddressMatch           // Cardholder's name doesn't match, street address matches.
	AVSResponseNameNoMatchZipMatch               // Cardholder's name doesn't match but ZIP code matches
	AVSResponseNameNoMatchZipMatchAddressMatch   // Cardholder's name doesn't match but both zip/address do match
	AVSResponseNameMatchZipMatchAddressNoMatch   // Cardholder's name and ZIP match, street address doesn't match.
	AVSResponseNameMatchZipNoMatchAddressMatch   // Cardholder's name and street address match, ZIP doesn't match.
	AVSResponseNameMatchZipNoMatchAddressNoMatch // Cardholder's name matches, ZIP and street address don't match.
	AVSResponseNameMatchZipMatchAddressMatch     // Cardholder's name, zip, and address all match
)

Consts representing the various AVSResponses we can get We keep this pretty general to translate into any of our PsPs we support

func (AVSResponse) String

func (code AVSResponse) String() string

String returns a string representation of a AVS response code

type Amount

type Amount struct {
	Amount   int64
	Currency string
}

Amount specifies both quantity and currency

type AuthorizationRequest

type AuthorizationRequest struct {
	Amount                     Amount
	CreditCard                 *CreditCard
	BillingAddress             *BillingAddress
	Level3Data                 *Level3Data
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
	Channel                    string  // for Psps that track the sales channel
	Options                    map[string]interface{}
}

AuthorizationRequest specifies needed information for request to authorize by PsPs Note: Only credit cards are supported Note: Options is a generic key-value pair that can be used to provide additional information to PsP

type AuthorizationResponse

type AuthorizationResponse struct {
	// Raw fields contain the untranslated responses from processors, while
	// the non-raw fields are the best parsings to a single standard, with
	// loss of granularity minimized. The latter should be preferred when
	// treating Sleet as a black box.
	Success              bool
	TransactionReference string
	AvsResult            AVSResponse
	CvvResult            CVVResponse
	Response             string
	ErrorCode            string
	AvsResultRaw         string
	CvvResultRaw         string
}

AuthorizationResponse is a generic response returned back to client after data massaging from PsP Response The raw AVS and CVV are included if applicable Success is true if Auth went through successfully

type BillingAddress

type BillingAddress struct {
	StreetAddress1 *string
	StreetAddress2 *string
	Locality       *string
	RegionCode     *string
	PostalCode     *string
	CountryCode    *string // ISO 2-digit code
	Company        *string
	Email          *string
}

BillingAddress used for AVS checks for auth calls

type CVVResponse

type CVVResponse int

CVVResponse represents a possible CVV/CVN verification response.

const (
	CVVResponseUnknown            CVVResponse = iota // Unknown CVV code returned by processor
	CVVResponseNoResponse                            // No verification response was given
	CVVResponseError                                 // An error prevented verification (e.g. data validation check failed)
	CVVResponseUnsupported                           // CVV verification is not supported
	CVVResponseMatch                                 // CVV matches
	CVVResponseNoMatch                               // CVV doesn't match
	CVVResponseNotProcessed                          // Verification didn't happen (e.g. auth already declined by bank before checking CVV)
	CVVResponseRequiredButMissing                    // CVV should be present, but it was reported as not
	CVVResponseSuspicious                            // The issuing bank determined this transaction to be suspicious
	CVVResponseSkipped                               // Verification was not performed for this transaction
)

Enum representing general CVV responses that we have

func (CVVResponse) String

func (code CVVResponse) String() string

String returns a string representation of a CVV response code

type CaptureRequest

type CaptureRequest struct {
	Amount                     *Amount
	TransactionReference       string
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
}

CaptureRequest specifies the authorized transaction to capture and also an amount for partial capture use cases

type CaptureResponse

type CaptureResponse struct {
	Success              bool
	TransactionReference string
	ErrorCode            *string
}

CaptureResponse will have Success be true if transaction is captured and also a reference to be used for subsequent operations

type Client

type Client interface {
	Authorize(request *AuthorizationRequest) (*AuthorizationResponse, error)
	Capture(request *CaptureRequest) (*CaptureResponse, error)
	Void(request *VoidRequest) (*VoidResponse, error)
	Refund(request *RefundRequest) (*RefundResponse, error)
}

Client defines the Sleet interface which takes in a generic request and returns a generic response The translations for each specific PsP takes place in the corresponding gateways/<PsP> folders The four supported methods are Auth, Capture, Void, Refund

type Code

type Code string

Code represents ISO 4217 Currency Codes

const (
	AED Code = "AED"
	AFN Code = "AFN"
	ALL Code = "ALL"
	AMD Code = "AMD"
	ANG Code = "ANG"
	AOA Code = "AOA"
	ARS Code = "ARS"
	AUD Code = "AUD"
	AWG Code = "AWG"
	AZN Code = "AZN"
	BAM Code = "BAM"
	BBD Code = "BBD"
	BDT Code = "BDT"
	BGN Code = "BGN"
	BHD Code = "BHD"
	BIF Code = "BIF"
	BMD Code = "BMD"
	BND Code = "BND"
	BOB Code = "BOB"
	BOV Code = "BOV"
	BRL Code = "BRL"
	BSD Code = "BSD"
	BTN Code = "BTN"
	BWP Code = "BWP"
	BYN Code = "BYN"
	BZD Code = "BZD"
	CAD Code = "CAD"
	CDF Code = "CDF"
	CHE Code = "CHE"
	CHF Code = "CHF"
	CHW Code = "CHW"
	CLF Code = "CLF"
	CLP Code = "CLP"
	CNY Code = "CNY"
	COP Code = "COP"
	COU Code = "COU"
	CRC Code = "CRC"
	CUC Code = "CUC"
	CUP Code = "CUP"
	CVE Code = "CVE"
	CZK Code = "CZK"
	DJF Code = "DJF"
	DKK Code = "DKK"
	DOP Code = "DOP"
	DZD Code = "DZD"
	EGP Code = "EGP"
	ERN Code = "ERN"
	ETB Code = "ETB"
	EUR Code = "EUR"
	FJD Code = "FJD"
	FKP Code = "FKP"
	GBP Code = "GBP"
	GEL Code = "GEL"
	GHS Code = "GHS"
	GIP Code = "GIP"
	GMD Code = "GMD"
	GNF Code = "GNF"
	GTQ Code = "GTQ"
	GYD Code = "GYD"
	HKD Code = "HKD"
	HNL Code = "HNL"
	HRK Code = "HRK"
	HTG Code = "HTG"
	HUF Code = "HUF"
	IDR Code = "IDR"
	ILS Code = "ILS"
	INR Code = "INR"
	IQD Code = "IQD"
	IRR Code = "IRR"
	ISK Code = "ISK"
	JMD Code = "JMD"
	JOD Code = "JOD"
	JPY Code = "JPY"
	KES Code = "KES"
	KGS Code = "KGS"
	KHR Code = "KHR"
	KMF Code = "KMF"
	KPW Code = "KPW"
	KRW Code = "KRW"
	KWD Code = "KWD"
	KYD Code = "KYD"
	KZT Code = "KZT"
	LAK Code = "LAK"
	LBP Code = "LBP"
	LKR Code = "LKR"
	LRD Code = "LRD"
	LSL Code = "LSL"
	LYD Code = "LYD"
	MAD Code = "MAD"
	MDL Code = "MDL"
	MGA Code = "MGA"
	MKD Code = "MKD"
	MMK Code = "MMK"
	MNT Code = "MNT"
	MOP Code = "MOP"
	MRU Code = "MRU"
	MUR Code = "MUR"
	MVR Code = "MVR"
	MWK Code = "MWK"
	MXN Code = "MXN"
	MXV Code = "MXV"
	MYR Code = "MYR"
	MZN Code = "MZN"
	NAD Code = "NAD"
	NGN Code = "NGN"
	NIO Code = "NIO"
	NOK Code = "NOK"
	NPR Code = "NPR"
	NZD Code = "NZD"
	OMR Code = "OMR"
	PAB Code = "PAB"
	PEN Code = "PEN"
	PGK Code = "PGK"
	PHP Code = "PHP"
	PKR Code = "PKR"
	PLN Code = "PLN"
	PYG Code = "PYG"
	QAR Code = "QAR"
	RON Code = "RON"
	RSD Code = "RSD"
	RUB Code = "RUB"
	RWF Code = "RWF"
	SAR Code = "SAR"
	SBD Code = "SBD"
	SCR Code = "SCR"
	SDG Code = "SDG"
	SEK Code = "SEK"
	SGD Code = "SGD"
	SHP Code = "SHP"
	SLL Code = "SLL"
	SOS Code = "SOS"
	SRD Code = "SRD"
	SSP Code = "SSP"
	STN Code = "STN"
	SVC Code = "SVC"
	SYP Code = "SYP"
	SZL Code = "SZL"
	THB Code = "THB"
	TJS Code = "TJS"
	TMT Code = "TMT"
	TND Code = "TND"
	TOP Code = "TOP"
	TRY Code = "TRY"
	TTD Code = "TTD"
	TWD Code = "TWD"
	TZS Code = "TZS"
	UAH Code = "UAH"
	UGX Code = "UGX"
	USD Code = "USD"
	USN Code = "USN"
	UYI Code = "UYI"
	UYU Code = "UYU"
	UYW Code = "UYW"
	UZS Code = "UZS"
	VES Code = "VES"
	VND Code = "VND"
	VUV Code = "VUV"
	WST Code = "WST"
	XAF Code = "XAF"
	XAG Code = "XAG"
	XAU Code = "XAU"
	XBA Code = "XBA"
	XBB Code = "XBB"
	XBC Code = "XBC"
	XBD Code = "XBD"
	XCD Code = "XCD"
	XDR Code = "XDR"
	XOF Code = "XOF"
	XPD Code = "XPD"
	XPF Code = "XPF"
	XPT Code = "XPT"
	XSU Code = "XSU"
	XTS Code = "XTS"
	XUA Code = "XUA"
	XXX Code = "XXX"
	YER Code = "YER"
	ZAR Code = "ZAR"
	ZMW Code = "ZMW"
	ZWL Code = "ZWL"
)

ISO 4217 Code List

func GetCode

func GetCode(code string) (Code, error)

GetCode converts a symbol string into the strongly typed Code

func (Code) String

func (c Code) String() string

type CreditCard

type CreditCard struct {
	FirstName       string
	LastName        string
	Number          string
	ExpirationMonth int
	ExpirationYear  int
	CVV             string
}

CreditCard represents raw credit card information

type Currency

type Currency struct {
	Precision int
	Symbol    string
}

Currency maps to the CURRENCIES list in currency.go specifying the symbol and precision for the currency

type Level3Data

type Level3Data struct {
	CustomerReference      string
	TaxAmount              Amount
	DiscountAmount         Amount
	ShippingAmount         Amount
	DutyAmount             Amount
	DestinationPostalCode  string
	DestinationCountryCode string
	DestinationAdminArea   string
	LineItems              []LineItem
}

Level3Data contains all of the information needed for Level3 processing including LineItems

type LineItem

type LineItem struct {
	Description        string
	ProductCode        string
	UnitPrice          Amount
	Quantity           int64
	TotalAmount        Amount
	ItemTaxAmount      Amount
	ItemDiscountAmount Amount
	UnitOfMeasure      string
	CommodityCode      string
}

LineItem is used for Level3 Processing if enabled (not default). Specifies information per item in the order

type RefundRequest

type RefundRequest struct {
	Amount                     *Amount
	TransactionReference       string
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
	Options                    map[string]interface{}
}

RefundRequest for refunding a captured transaction with generic Options and amount to be refunded

type RefundResponse

type RefundResponse struct {
	Success              bool
	TransactionReference string
	ErrorCode            *string
}

RefundResponse indicating if request went through successfully

type VoidRequest

type VoidRequest struct {
	TransactionReference       string
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
}

VoidRequest cancels an authorized transaction

type VoidResponse

type VoidResponse struct {
	Success              bool
	TransactionReference string
	ErrorCode            *string
}

VoidResponse also specifies a transaction reference if PsP uses different transaction references for different states