mimir

README

Mimir  

What is Mimir ?

Mimir is a lightweight library that exposes some functions to validate banking informations.
It does not store any of your personal data, you can use it freely.

Disclaimer

This library is still in development, so it might be possible that some methods change over time.

Methods available

If you experienced troubles with one of our methods, don't hesitate telling us by submitting an issue.

Bank account numbers

IBAN Methods

Method Name	Short Description
IsIBANValid	Validate an IBAN
GetIBANCheckDigits	Compute or fix check digits from an IBAN
FormatIBAN	Format IBAN based on its structure
PrintFormatIBAN	Format IBAN as it would be printed
GetCountryConfiguration	Get country configuration and informations
SplitIBAN	Split the IBAN based on its structure

ABA Routing Number Methods

Method Name	Short Description
IsABARTNValid	Validate an ABA
GetABARTNCheckDigit	Compute or fix check digits for an ABA
SplitABARTN	Split the ABA based on its structure

Supported countries

Please visit SUPPORTED_COUNTRIES.md

Payment card numbers

All cards in the examples has been generated randomly

Methods

Method Name	Short Description
MatchPaymentCard	Validate a payment card number from a specific card issuer or not
GetPaymentCardCheckDigits	Compute or fix check digits from a payment card
GetPaymentCardConfiguration	Get payment cards information from an issuer
FormatPaymentCard	Format payment card based on its structure

Supported cards

Please visit SUPPORTED_CARDS.md

Use

Get

$ go get -u github.com/vdlbk/mimir

Examples

Validate an IBAN

package main

import (
	"fmt"
	"github.com/vdlbk/mimir"
)

func main(){
	IBAN := "FR1420041010050500013M02606"
	
	err := mimir.IsIBANValid(IBAN)
	fmt.Println(err) // nil
	
	badIBAN := "FR1420041010050500013M02605"
	
	err = mimir.IsIBANValid(badIBAN)
	fmt.Println(err) // IBAN invalid checksum
}

Validate a payment card number

package main

import (
	"fmt"
	"github.com/vdlbk/mimir"
)

func main(){
	number := "345752218692713"
	
	r, err := mimir.MatchPaymentCard(number, mimir.AmericanExpress)
	fmt.Println(r, err) // [American Express], nil
	
	badNumber := "foobar"
	
	r, err = mimir.MatchPaymentCard(badNumber, mimir.AmericanExpress)
	fmt.Println(r, err) // nil, Payment card does not match any issuer
}

Documentation

Index

• Constants
• func FormatIBAN(iban string) (string, error)
• func FormatPaymentCard(number, issuer string) (string, error)
• func GetABARTNCheckDigit(aba string) (string, string, error)
• func GetCountryConfiguration(countryCode string) (*configuration, error)
• func GetIBANCheckDigits(iban string) (string, string, error)
• func GetPaymentCardCheckDigits(number string) (string, string, error)
• func GetPaymentCardConfiguration(issuer string) (*paymentCardConfiguration, error)
• func IsABARTNValid(aba string) error
• func IsIBANValid(iban string) error
• func MatchPaymentCard(number string, issuers ...string) ([]string, error)
• func PrintFormatIBAN(iban string) (string, error)
• func SplitABARTN(aba string) ([]string, []string, error)
• func SplitIBAN(iban string) ([]string, []string, error)

Examples

• GetABARTNCheckDigit
• GetIBANCheckDigits
• GetPaymentCardCheckDigits
• IsIBANValid
• MatchPaymentCard

Constants

const (
	// ErrIBANTooshort is the error when an IBAN is too short for the validation process
	ErrIBANTooshort = mimirError("IBAN is too short")

	// ErrIBANIncorrectLength is the error when a IBAN does not have the required length
	ErrIBANIncorrectLength = mimirError("IBAN incorrect length")

	// ErrIBANInvalidChecksum is the error when a IBAN is invalid
	ErrIBANInvalidChecksum = mimirError("IBAN invalid checksum")

	// ErrCountryCodeDoesNotExist is the error when you lookup for a country code that does not exists
	ErrCountryCodeDoesNotExist = mimirError("Country Code does not exist")

	// ErrABARTNInvalidLength is the error when an ABA Routing Number is too short the the validation process
	ErrABARTNInvalidLength = mimirError("ABA is too short. 9 digits is expected")

	// ErrABAInvalidChecksum is the error when a ABA Routing Number is invalid
	ErrABAInvalidChecksum = mimirError("ABA Routing Number invalid checksum")

	// ErrPaymentCardInvalidChecksum is the error when a Payment card number is invalid
	ErrPaymentCardDoesNotMatchAnyIssuer = mimirError("Payment card does not match any issuer")

	// ErrPaymentCardTooShort is the error when a Payment card number is too short for the validation process
	ErrPaymentCardTooShort = mimirError("Payment card number is too short")

	// ErrIssuerDoesNotExist is the error when you lookup for an issuer that does not exists
	ErrIssuerDoesNotExist = mimirError("Issuer does not exist")

	// ErrStructureNotFound is the error when you try to format a payment card which does not have supported structure
	ErrStructureNotFound = mimirError("Structure not found")
)

Errors

const (
	AccountNumberIBANDigitKey                = "a" // alphanumeric
	NationalBankCodeIBANDigitKey             = "b" // numeric
	CountryCodeIBANDigitKey                  = "c" // alphabetic
	CheckIBANDigitKey                        = "k" // checksum
	NationalIdentificationNumberIBANDigitKey = "i"
	CurrencyIBANDigitKey                     = "m" // alphanumeric
	AccountHolderIBANDigitKey                = "n"
	ReserveNumberIBANDigitKey                = "o" // always 0
	BranchCodeIBANDigitKey                   = "s" // counter code
	AccountTypeIBANDigitKey                  = "t"
	SWIFTBICCodeIBANDigitKey                 = "w" // alphanumeric
	NationalCheckIBANDigitKey                = "x" // numeric
)

IBAN - Structure digit keys

const (
	FederalReserveRoutingSymbolABADigitKey = "f" // numeric
	ABAInstitutionIdentifierDigitKey       = "a" // numeric
	CheckABADigitKey                       = "k" // checksum // numeric
)

ABA Routing Number - Structure digit keys

const (
	AmericanExpress         = "American Express"
	ChinaUnionPay           = "China UnionPay"
	DinnerClubInternational = "Dinner Club International"
	DinnerClubCarteBlanche  = "Dinner Club Carte Blanche"
	DinnerClub              = "Dinner Club"
	Discover                = "Discover"
	Rupay                   = "Rupay"
	InterPayment            = "InterPayment"
	InstaPayment            = "InstaPayment"
	JCB                     = "JCB"
	Maestro                 = "Maestro"
	Dankort                 = "Dankort"
	MIR                     = "MIR"
	Mastercard              = "Mastercard"
	Visa                    = "Visa"
	UATP                    = "UATP"
)

Major industry identifier name / Issuer keys

Functions

func FormatIBAN

func FormatIBAN(iban string) (string, error)

FormatIBAN formats the given IBAN with the different parts that are defined in its structure.

func FormatPaymentCard

func FormatPaymentCard(number, issuer string) (string, error)

FormatPaymentCard formats the given payment card based on the structure of the issuer.

func GetABARTNCheckDigit

func GetABARTNCheckDigit(aba string) (string, string, error)

GetABARTNCheckDigit compute the check digits from a given ABA Routing Number. Returns the computed digit and the ABA updated with the check digits or an error if something goes wrong. The ABA must contains 9 digits but the last one will ignored. It's possible to use this function by adding an extra 0 at the end if the ABA is not a valid one.

Example

fmt.Println(GetABARTNCheckDigit("111000020"))
fmt.Println(GetABARTNCheckDigit("111000025"))

Output:

5 111000025 <nil>
5 111000025 <nil>

func GetCountryConfiguration

func GetCountryConfiguration(countryCode string) (*configuration, error)

GetCountryConfiguration returns ISO 13616-Compliant IBAN Formats from a given country code If the countryCode does not exist in the list, returns an error `ErrCountryCodeDoesNotExist`

func GetIBANCheckDigits

func GetIBANCheckDigits(iban string) (string, string, error)

GetIBANCheckDigits compute the check digits from a given IBAN. Returns the computed digits, the IBAN set with the check digits or an error if something goes wrong.

Example

fmt.Println(GetIBANCheckDigits("FR1420041010050500013M02606"))
fmt.Println(GetIBANCheckDigits("FR0020041010050500013M02606"))

Output:

14 FR1420041010050500013M02606 <nil>
14 FR1420041010050500013M02606 <nil>

func GetPaymentCardCheckDigits

func GetPaymentCardCheckDigits(number string) (string, string, error)

GetPaymentCardCheckDigits compute the check digits from a given payment card number. If you need to compute the check digit for 1234, please add an extra 0 at the end, otherwise, it's going to compute the check digit for 123. The last digit is ignored. Returns the computed digit, the payment card number set with the check digit or an error if something goes wrong.

Example

fmt.Println(GetPaymentCardCheckDigits("12340"))
fmt.Println(GetPaymentCardCheckDigits("1234"))

Output:

4 12344 <nil>
6 1236 <nil>

func GetPaymentCardConfiguration

func GetPaymentCardConfiguration(issuer string) (*paymentCardConfiguration, error)

GetPaymentCardConfiguration returns informations about the payment cards from a given issuer name If the countryCode does not exist in the list, returns an error `ErrCountryCodeDoesNotExist`

func IsABARTNValid

func IsABARTNValid(aba string) error

IsABARTNValid checks if the given ABA Routing Number is valid.

func IsIBANValid

func IsIBANValid(iban string) error

IsIBANValid checks if the given IBAN is valid based on the country its belong to.

Example

fmt.Println(IsIBANValid("FR1420041010050500013M02606"))
fmt.Println(IsIBANValid("FR1420041010050500013M02605"))

Output:

<nil>
IBAN invalid checksum

func MatchPaymentCard

func MatchPaymentCard(number string, issuers ...string) ([]string, error)

MatchPaymentCard returns a list of the issuers that match the given number. If the issuers list has been filled with valid issuer keys, it will only check the number for those ones. So it can be useful when it comes to check if a payment card number belongs to a specific issuer. It can also return an error if something goes wrong or if the number does not match any known issuer.

Example

fmt.Println(MatchPaymentCard("4012888888881881"))
fmt.Println(MatchPaymentCard("4012888888881881", Visa))
fmt.Println(MatchPaymentCard("4012888888881881", Mastercard))
fmt.Println(MatchPaymentCard("30037174022893"))

Output:

[Visa] <nil>
[Visa] <nil>
[] Payment card does not match any issuer
[Dinner Club Carte Blanche Dinner Club International] <nil>

func PrintFormatIBAN

func PrintFormatIBAN(iban string) (string, error)

PrintFormatIBAN formats the given IBAN based on the regular way to print it depending the country. It will use the PrintFormat of the configuration to insure the result.

func SplitABARTN

func SplitABARTN(aba string) ([]string, []string, error)

SplitABARTN splits a given valid ABA Routing Number depending its structure. It returns a list of digit keys and a list that contains each part of the structure or an error if something went wrong.

func SplitIBAN

func SplitIBAN(iban string) ([]string, []string, error)

SplitIBAN splits a given IBAN depending the structure of its country. It returns a list of digit keys, a list that contains each part of the structure or an error if something went wrong.