adyen

README

adyen

Encrypt secrets for the Adyen payment platform.

This library uses crypto/rand to generate cryptographically secure AES keys and nonces, and re-uses the same key and nonce for each client. Other publicly available libraries typically use math/rand which is insecure for generating secret keys and nonces.

Example

package main

import (
	"encoding/hex"
	"fmt"
	"github.com/CrimsonAIO/adyen"
)

func main() {
	// create a public key from the public key bytes
	//
	// if you have a key that looks like "10001|...", then you need to
	// hex decode the part after "|".
	// an example of this is shown here, minus removing the front part.
	const plaintextKey = "..."
	b, err := hex.DecodeString(plaintextKey)
	if err != nil {
		panic(err)
	}

	// create new encrypter
	enc, err := adyen.NewEncrypter("0_1_18", adyen.PubKeyFromBytes(b))
	if err != nil {
		panic(err)
	}

	// encrypt card information
	//
	// the number and month are automatically formatted with FormatCardNumber and
	// FormatMonthYear, so formatting doesn't matter.
	payload, err := enc.Encrypt(
		"4871049999999910",
		"737",
		3,
		2030,
	)
	if err != nil {
		panic(err)
	}

	// print the payload to send to the server
	fmt.Println(payload)
}

Check it out on The Go Playground.

Contributing

Pull requests are welcome to add new version constants or other improvements. Note that you don't need to use one of our version constants; you can use any string you like.

If you open a pull request, please use our MIT copyright header. If you're using GoLand (or any JetBrains IDE) you can do this by going in Settings -> Editor -> Copyright and selecting the copyright profile found in .idea/copyright/MIT_Crimson_Technologies_LLC.xml. You are welcome to add your own name for your contributions.

Documentation

Index

• Constants
• func Bool(value bool) *bool
• func DetectCardType(formattedCardNumber string) string
• func FormatCardNumber(number string) string
• func FormatMonthYear[T time.Month | int](month T, year int) (string, string)
• func PubKeyFromBytes(b []byte, publicExponent ...int) *rsa.PublicKey
• type BrowserInfo
• type Encrypter
  • func NewEncrypter(version string, pubKey *rsa.PublicKey) (enc *Encrypter, err error)
  • func (enc *Encrypter) Encrypt(number, securityCode string, month, year int) (string, error)
  • func (enc *Encrypter) EncryptField(key, value string) (string, error)
  • func (enc *Encrypter) EncryptFields(fields map[string]string) (string, error)
  • func (enc *Encrypter) EncryptPlaintext(plaintext []byte) (string, error)
  • func (enc *Encrypter) Reset() (err error)
• type GenerationTimeFunc

Constants

const (
	// GenerationTimeKey is the JSON key for the generated time.
	GenerationTimeKey = "generationtime"

	// GenerationTimeFormat is the time format.
	// This is identical to time.RFC3339Nano except there is only three trailing zeros.
	GenerationTimeFormat = "2006-01-02T15:04:05.000Z07:00"

	// KeyNumber is the card number field key.
	KeyNumber = "number"

	// KeyExpiryMonth is the expiry month field key.
	KeyExpiryMonth = "expiryMonth"

	// KeyExpiryYear is the expiry year field key.
	KeyExpiryYear = "expiryYear"

	// KeySecurityCode is the security code field key.
	KeySecurityCode = "cvc"
)

Functions

func Bool

func Bool(value bool) *bool

Bool returns a pointer to value.

func DetectCardType

func DetectCardType(formattedCardNumber string) string

DetectCardType detects the type of the given card number. The card number must have no whitespace characters.

If the card's type cannot be detected, then "noBrand" is returned which is also what Adyen uses if it cannot detect the card type.

func FormatCardNumber

func FormatCardNumber(number string) string

FormatCardNumber formats the given card number into the Adyen format. Numbers less than 15 digits (excluding white space) are ignored.

Examples:

0123456789012345 -> 0123 4567 8901 2345

0123 4567 8901 2345 -> (no change)

0123 456789012345 -> 0123 4567 8901 2345

func FormatMonthYear

func FormatMonthYear[T time.Month | int](month T, year int) (string, string)

FormatMonthYear formats a card expiry month and year into the Adyen format. It is assumed that the given year is the fully-qualified year, like "2020" (instead of "20".)

Examples:

5, 2024 -> "05", "2024"

12, 2024 -> "12", "2024"

func PubKeyFromBytes

func PubKeyFromBytes(b []byte, publicExponent ...int) *rsa.PublicKey

PubKeyFromBytes creates a new RSA public key from b with the optional public exponent.

Types

type BrowserInfo

type BrowserInfo struct {
	// AcceptHeader is the value of the browser's Accept header.
	AcceptHeader string `json:"acceptHeader"`

	// ColorDepth is the browser's color depth in bits per pixel.
	// This is the "screen.colorDepth" value.
	ColorDepth int `json:"colorDepth"`

	// JavaEnabled is if the browser is capable of executing Java.
	JavaEnabled bool `json:"javaEnabled"`

	// JavaScriptEnabled is an optional field indicating if the browser
	// is capable of executing JavaScript. If not specified, the Adyen
	// API assumes this value is true.
	//
	// To use a boolean value, use Bool.
	JavaScriptEnabled *bool `json:"javaScriptEnabled,omitempty"`

	// Language is the name of the language used by the browser.
	// This is the value of "navigator.language".
	Language string `json:"language"`

	// ScreenHeight is the browser's screen height.
	ScreenHeight int `json:"screenHeight"`

	// ScreenWidth is the browser's screen width.
	ScreenWidth int `json:"screenWidth"`

	// TimeZoneOffset is the time difference between UTC time and the browser's
	// local time in minutes.
	TimeZoneOffset int `json:"timeZoneOffset"`

	// UserAgent is the browser's user agent.
	UserAgent string `json:"userAgent"`
}

BrowserInfo represents the "browserInfo" object as defined in the Adyen documentation.

Read more: https://docs.adyen.com/online-payments/3d-secure/api-reference#browserinfo

type Encrypter

type Encrypter struct {

	// Version is the Adyen version that this Encrypter will
	// seal plaintext for.
	Version string

	// GetGenerationTime gets the time.Time to use for the
	// required "generationtime" JSON field. The default is
	// time.Now.
	//
	// This may be modified by the caller to return custom times
	// that differ from the default.
	GetGenerationTime GenerationTimeFunc
	// contains filtered or unexported fields
}

An Encrypter encrypts content into the Adyen format using an RSA public key and AES-256.

func NewEncrypter

func NewEncrypter(version string, pubKey *rsa.PublicKey) (enc *Encrypter, err error)

NewEncrypter creates a new Encrypter with the given version and RSA public key.

Calls to Encrypter.EncryptPlaintext will panic if pubKey == nil.

func (*Encrypter) Encrypt

func (enc *Encrypter) Encrypt(number, securityCode string, month, year int) (string, error)

Encrypt encrypts a card number, security code (CVV/CVC), expiry month and year into a map and correctly formats all values using FormatCardNumber and FormatMonthYear.

func (*Encrypter) EncryptField

func (enc *Encrypter) EncryptField(key, value string) (string, error)

EncryptField encrypts a single key and value.

func (*Encrypter) EncryptFields

func (enc *Encrypter) EncryptFields(fields map[string]string) (string, error)

EncryptFields encrypts a map.

func (*Encrypter) EncryptPlaintext

func (enc *Encrypter) EncryptPlaintext(plaintext []byte) (string, error)

EncryptPlaintext seals the given plaintext and returns the sealed content in the Adyen format.

Most callers should use Encrypt, EncryptField or EncryptFields instead.

func (*Encrypter) Reset

func (enc *Encrypter) Reset() (err error)

Reset resets the AES key and cipher block for the encrypter to use.

If err != nil, the Encrypter is not safe to use.

type GenerationTimeFunc

type GenerationTimeFunc func() time.Time

GenerationTimeFunc is a function responsible for returning the time that a payload was generated at.