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 Gateway API Calls

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

Webhooks Support

We support abstracting PsP Webhook notifications into a common interface.

PsP Support Matrix

PsP	Gateway APIs	Webhooks
Adyen	✅	❌
Authorize.Net	✅	❌
Braintree	✅	❌
CyberSource	✅	❌
Checkout.com	✅	❌
FirstData	✅	❌
NMI	✅	❌
Orbital	✅	❌
RocketGate	✅	❌
Stripe	✅	❌

To run tests

Unit test

go test -v -tags=unit $(go list ./... | grep -v integration-tests)

Integration test

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"
$ export CHECKOUTCOM_TEST_KEY="YOUR_CHECKOUTCOM_PRIVATE_KEY"
$ export CHECKOUTCOM_TEST_KEY_WITH_PCID="YOUR_CHECKOUTCOM_PRIVATE_KEY_WITH_PROCESSING_CHANNEL_ID"
$ export CHECKOUTCOM_TEST_PCID="YOUR_CHECKOUTCOM_PROCESSING_CHANNEL_ID"

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,
}
// To get specific response headers, add them to the request options.
// They will be attached to the AuthorizationResponse
options := make(map[string]interface{})
options["ResponseHeader"] = []string{"x-test-header"}
authorizeRequest := sleet.AuthorizationRequest{
  Amount: &amount,
  CreditCard: &card,
  BillingAddress: &address,
  Options: options,
}
authorizeResponse, _ := client.Authorize(&authorizeRequest)

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

Documentation

Index

• Constants
• func AmountToDecimalString(amount *Amount) string
• func AmountToString(amount *Amount) string
• func DefaultIfEmpty(primary string, fallback string) string
• func GetHTTPResponseHeader(options map[string]interface{}, httpResp http.Response) http.Header
• func TruncateString(str string, truncateLength int) string
• type AVSResponse
  • func (code AVSResponse) String() string
• type Address
• type Amount
• type AuthorizationRequest
• type AuthorizationResponse
• type BillingAddress
• type CVVResponse
  • func (code CVVResponse) String() string
• type CaptureRequest
• type CaptureResponse
• type Client
• type CreditCard
• type CreditCardNetwork
• type Currency
• type Level3Data
• type LineItem
• type ProcessingInitiatorType
• type RTAUResponse
• type RTAUStatus
• type RefundRequest
• type RefundResponse
• type ThreeDS
• type VoidRequest
• type VoidResponse

Constants

const (
	ResponseHeaderOption string = "ResponseHeader"
)

const (
	ThreedsStatusRejected = "R"
)

3DS response codes.

Functions

func AmountToDecimalString

func AmountToDecimalString(amount *Amount) string

AmountToDecimalString converts an int64 amount in cents to a 2 decimal formatted string Note this function assumes 1 dollar = 100 cents (which is true for USD, CAD, etc but not true for some other currencies).

func AmountToString

func AmountToString(amount *Amount) string

AmountToString converts an integer amount to a string with no formatting

func DefaultIfEmpty

func DefaultIfEmpty(primary string, fallback string) string

DefaultIfEmpty returns the fallback string if str is an empty string.

func GetHTTPResponseHeader

func GetHTTPResponseHeader(options map[string]interface{}, httpResp http.Response) http.Header

GetHTTPResponseHeader returns the http response headers specified in the given options.

func TruncateString

func TruncateString(str string, truncateLength int) string

TruncateString returns a prefix of str of length truncateLength or all of str if truncateLength is greater than len(str)

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 Address

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

Address generic address to represent billing address, shipping address, etc. used for AVS checks for auth calls

type Amount

type Amount struct {
	Amount   int64
	Currency string
}

Amount specifies both quantity and currency

type AuthorizationRequest

type AuthorizationRequest struct {
	Amount                        Amount
	BillingAddress                *Address
	Channel                       string  // for PSPs that track the sales channel
	ClientTransactionReference    *string // Custom transaction reference metadata that will be associated with this request
	CreditCard                    *CreditCard
	Cryptogram                    string // for Network Tokenization methods
	ECI                           string // E-Commerce Indicator (can be used for Network Tokenization as well)
	Level3Data                    *Level3Data
	MerchantOrderReference        string                   // Similar to ClientTransactionReference but specifically if we want to store the shopping cart order id
	PreviousExternalTransactionID *string                  // If we are in a recurring situation, then we can use the PreviousExternalTransactionID as part of the auth request
	ProcessingInitiator           *ProcessingInitiatorType // For Card on File transactions we want to store the various different types (initial cof, initial recurring, etc)
	ShippingAddress               *Address
	ShopperReference              string // ShopperReference Unique reference to a shopper (shopperId, etc.)
	ThreeDS                       *ThreeDS

	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
	ExternalTransactionID string
	AvsResult             AVSResponse
	CvvResult             CVVResponse
	Response              string
	ErrorCode             string
	AvsResultRaw          string
	CvvResultRaw          string
	RTAUResult            *RTAUResponse
	AdyenAdditionalData   map[string]string // store additional recurring info (will be refactored to general naming on next major version upgrade)
	StatusCode            int               // the status code from raw PSP http response.
	Header                http.Header       // the http response header
}

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 = Address

BillingAddress for backwards compatibility

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
	MerchantOrderReference     *string                // Custom merchant order reference that will be associated with this request
	Options                    map[string]interface{} // For additional options that need to be passed in
}

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 CreditCard

type CreditCard struct {
	FirstName       string
	LastName        string
	Number          string
	ExpirationMonth int
	ExpirationYear  int
	CVV             string
	Network         CreditCardNetwork
	Save            bool // indicates if customer wants to save their credit card details
}

CreditCard represents raw credit card information

type CreditCardNetwork

type CreditCardNetwork int

CreditCardNetwork card network (eg visa)

const (
	// CreditCardNetworkUnknown unknown network
	CreditCardNetworkUnknown CreditCardNetwork = iota
	// CreditCardNetworkVisa visa
	CreditCardNetworkVisa
	// CreditCardNetworkMastercard mastercard
	CreditCardNetworkMastercard
	// CreditCardNetworkAmex amex
	CreditCardNetworkAmex
	// CreditCardNetworkDiscover discover
	CreditCardNetworkDiscover
	// CreditCardNetworkJcb JCBP
	CreditCardNetworkJcb
	// CreditCardNetworkUnionpay UnionPay
	CreditCardNetworkUnionpay
	// CreditCardNetworkCitiPLCC citiplcc
	CreditCardNetworkCitiPLCC
)

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 ProcessingInitiatorType

type ProcessingInitiatorType string

ProcessingInitiatorType type of processing initiator

const (
	// ProcessingInitiatorTypeInitialCardOnFile initial non-recurring payment
	ProcessingInitiatorTypeInitialCardOnFile ProcessingInitiatorType = "initial_card_on_file"
	// ProcessingInitiatorTypeInitialRecurring initiating recurring payment
	ProcessingInitiatorTypeInitialRecurring ProcessingInitiatorType = "initial_recurring"
	// ProcessingInitiatorTypeStoredCardholderInitiated initiated by cardholder using stored card
	ProcessingInitiatorTypeStoredCardholderInitiated ProcessingInitiatorType = "stored_cardholder_initiated"
	// ProcessingInitiatorTypeStoredMerchantInitiated initiated by merchant using stored card
	ProcessingInitiatorTypeStoredMerchantInitiated ProcessingInitiatorType = "stored_merchant_initiated"
	// ProcessingInitiatorTypeFollowingRecurring recurring payment
	ProcessingInitiatorTypeFollowingRecurring ProcessingInitiatorType = "following_recurring"
)

type RTAUResponse

type RTAUResponse struct {
	RealTimeAccountUpdateStatus RTAUStatus
	UpdatedExpiry               *time.Time
	UpdatedBIN                  string
	UpdatedLast4                string
}

type RTAUStatus

type RTAUStatus string

RTAUStatus represents the Real Time Account Updater response from a processor, if applicable

const (
	RTAUStatusUnknown                  RTAUStatus = "Unknown"    // when a processor has RTAU capability, but returns an unexpected status
	RTAUStatusNoResponse               RTAUStatus = "NoResponse" // when a processor has RTAU capability, but doesn't return any additional info
	RTAUStatusCardChanged              RTAUStatus = "CardChanged"
	RTAUStatusCardExpired              RTAUStatus = "CardExpiryChanged"
	RTAUStatusContactCardAccountHolder RTAUStatus = "ContactCardAccountHolder"
	RTAUStatusCloseAccount             RTAUStatus = "CloseAccount"
)

type RefundRequest

type RefundRequest struct {
	Amount                     *Amount
	TransactionReference       string
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
	MerchantOrderReference     *string // Custom merchant order reference that will be associated with this request
	Last4                      string
	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 ThreeDS

type ThreeDS struct {
	Frictionless     bool   // Whether the 3DS flow for this transaction was frictionless
	ACSTransactionID string // Transaction ID assigned by ACS
	CAVV             string // Cardholder Authentication Value
	CAVVAlgorithm    string // Algorithm used to calculate CAVV
	DSTransactionID  string // Directory Server (DS) Transaction ID (for 3DS2)
	PAResStatus      string // Transaction status result
	UCAFIndicator    string // Universal Cardholder Authentication Field Indicator value provided by issuer
	Version          string // 3DS Version
	XID              string // Transaction ID from authentication processing (for 3DS1)
}

ThreeDS holds results from a 3DS verification challenge.

type VoidRequest

type VoidRequest struct {
	TransactionReference       string
	ClientTransactionReference *string // Custom transaction reference metadata that will be associated with this request
	MerchantOrderReference     *string // Custom merchant order reference 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