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

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"

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

• func AmountToDecimalString(amount *Amount) string
• func AmountToString(amount *Amount) string
• func DefaultIfEmpty(primary string, fallback string) string
• func TruncateString(str string, truncateLength int) 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 CreditCard
• type CreditCardNetwork
• type Currency
• type Level3Data
• type LineItem
• type ProcessingInitiatorType
• type RTAUResponse
• type RTAUStatus
• type RefundRequest
• type RefundResponse
• type VoidRequest
• type VoidResponse

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 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 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
	Cryptogram                 string  // for Network Tokenization methods
	ECI                        string  // E-Commerce Indicator (can be used for Network Tokenization as well)
	MerchantOrderReference     string  // Similar to ClientTransactionReference but specifically if we want to store the shopping cart order id

	// For Card on File transactions we want to store the various different types (initial cof, initial recurring, etc)
	// If we are in a recurring situation, then we can use the PreviousExternalTransactionID as part of the auth request
	ProcessingInitiator           *ProcessingInitiatorType
	PreviousExternalTransactionID *string
	Options                       map[string]interface{}
	ShopperReference              string // shopperReference used to get adyen recurring info
}

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
	RTAUResult           *RTAUResponse
	AdyenAdditionalData  map[string]string // store additional Adyen recurring info
}

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