swift

README

swift

Package code.pfad.fr/swift provides methods to check offline the validity of an IBAN (and to retrieve some BIC codes). Example and documentation are available on https://code.pfad.fr/swift/ and on pkg.go.dev.

Updating the registry data

To update the BBAN registry and BIC data, run make generate, commit the changes and push a new tag.

License

European Union Public License 1.2 or later (EUPL-1.2+).

I consider that importing this library (unmodified) within a larger work (as long as it does more than just validation and IBAN or BIC codes manipulation) not to be a "Derivative Work" (so you don't need to release your work under a EUPL-1.2 compatible license in such a case).

Documentation

Overview

package swift provides methods to check the validity of an IBAN (and retrieve the BIC for some countries). Play with the demo in the browser, powered by JS+Wasm.

Example

// SPDX-FileCopyrightText: 2023 Olivier Charvin <git@olivier.pfad.fr>
//
// SPDX-License-Identifier: CC0-1.0

package main

import (
	"fmt"

	"code.pfad.fr/swift"
	"code.pfad.fr/swift/bic"
)

var germanTestIBAN = "DE75512108001245126199"

func main() {
	iban, err := swift.NewIBAN(germanTestIBAN, swift.CountryBelongsToSEPA())
	if err != nil {
		panic(err)
	}
	fmt.Println("IBAN:", iban.MaskedAndSpaced())
	fmt.Println("BIC: ", bic.FromIBAN(iban).String())
}

Output:

IBAN: DE75 512* **** **** ***1 99
BIC:  SOGEDEFFXXX

Index

• Variables
• type BIC
  • func NewBIC(s string) (BIC, error)
  • func (b BIC) String() string
• type CheckDigitsError
  • func (e CheckDigitsError) Error() string
• type CountryCode
  • func (cc CountryCode) BelongsToIBANRegistry() bool
  • func (cc CountryCode) BelongsToSEPA() bool
• type ExpectedCharType
• type FormatError
  • func (e FormatError) Error() string
• type IBAN
  • func NewIBAN(s string, additionalRules ...IBANValidator) (IBAN, error)
  • func (iban IBAN) MaskedAndSpaced() string
  • func (iban IBAN) Spaced() string
  • func (iban IBAN) String() string
• type IBANValidator
  • func CountryBelongsToIBANRegistry() IBANValidator
  • func CountryBelongsToSEPA() IBANValidator
  • func NationalFormatCheck() IBANValidator
• type TooShortError
  • func (e TooShortError) Error() string

Examples

• Package

Variables

var ErrCountryNotInRegistry = errors.New("country is not listed in the IBAN registry")

ErrCountryNotInRegistry is returned when a country is not listed in the iban registry.

var ErrCountryOutsideSEPA = errors.New("country is outside the Single Euro Payments Area (SEPA)")

ErrCountryOutsideSEPA is returned when a country does not belong to the Single Euro Payments Area.

Types

type BIC

type BIC struct {
	Institution string      // 4 letters
	CountryCode CountryCode // 2 letters (ISO 3166-1 alpha-2 code)
	Location    string      // 2 letters or digits
	Branch      string      // 3 letters or digits (optional)
}

BIC represents the routing information as specified by ISO 9362 (also known as Business Identifier Codes (BIC), SWIFT ID or SWIFT code, and SWIFT-BIC).

func NewBIC

func NewBIC(s string) (BIC, error)

NewBIC uppercases a BIC and perform some basic checks (format and length). If the country code is unknown the BIC will be accepted, call CountryCode.BelongsToIBANRegistry or CountryCode.BelongsToSEPA to perform additional validation.

func (BIC) String

func (b BIC) String() string

String returns the BIC.

type CheckDigitsError

type CheckDigitsError struct {
	Expected      int
	Actual        int
	NationalCheck bool // true if the check failed at the country level (within the BBAN)
}

CheckDigitsError indicates that the checksum did not match the expected check digits.

func (CheckDigitsError) Error

func (e CheckDigitsError) Error() string

type CountryCode

type CountryCode string

CountryCode is the ISO 3166-1 alpha-2 code of the country (uppercase)

func (CountryCode) BelongsToIBANRegistry

func (cc CountryCode) BelongsToIBANRegistry() bool

BelongsToIBANRegistry returns true if the country is listed in the iban registry https://www.swift.com/resource/iban-registry-pdf

func (CountryCode) BelongsToSEPA

func (cc CountryCode) BelongsToSEPA() bool

BelongsToSEPA indicates if a country belongs to the Single Euro Payments Area according to https://www.swift.com/resource/iban-registry-pdf

type ExpectedCharType

type ExpectedCharType = format.ExpectedCharType

const (
	ExpectedNoMoreChar         ExpectedCharType = format.NoMoreChar
	ExpectedUppercaseAlphaChar ExpectedCharType = format.UppercaseAlphaChar       // (A-Z)
	ExpectedAlphaChar          ExpectedCharType = format.AlphaChar                // (a-z, A-Z)
	ExpectedNumericChar        ExpectedCharType = format.ExpectedNumericChar      // (0-9)
	ExpectedAlphaNumericChar   ExpectedCharType = format.ExpectedAlphaNumericChar // (a-z, A-Z, 0-9)
)

type FormatError

type FormatError struct {
	Position int              // index in the submitted string where the error occurred
	Expected ExpectedCharType // expected type of character
	Got      string           // submitted character

	Part         string // part of the submitted string considered (all chars should conform to the expected type)
	PartPosition int    // start index of the part above
}

FormatError indicates that an unexpected character type was encountered.

func (FormatError) Error

func (e FormatError) Error() string

type IBAN

type IBAN struct {
	CountryCode CountryCode
	CheckDigits int
	BBAN        string
}

IBAN represents an International Bank Account Number

func NewIBAN

func NewIBAN(s string, additionalRules ...IBANValidator) (IBAN, error)

NewIBAN sanitizes, parses and checks an IBAN (length, format, check digit sum). See CountryBelongsToIBANRegistry and CountryBelongsToSEPA to perform country code validation. See NationalFormatCheck to additionnally verify the national format.

func (IBAN) MaskedAndSpaced

func (iban IBAN) MaskedAndSpaced() string

MaskedAndSpaced returns the spaced IBAN with only the first and last 3 characters of the BBAN visible (other chars are replaced with "*").

IBANs are not secret, but it shouldn't hurt to hide parts of them. Since BBANs are longer than 11 characters, at least 5 chars will be hidden (still partially recoverable using the leading check digits). Example:

DE75 512* **** **** ***1 99

func (IBAN) Spaced

func (iban IBAN) Spaced() string

Spaced returns the IBAN with spaces between every 4 characters.

func (IBAN) String

func (iban IBAN) String() string

String returns the IBAN, without spaces

type IBANValidator

type IBANValidator func(IBAN) error

IBANValidator makes additional checks on a given IBAN.

func CountryBelongsToIBANRegistry

func CountryBelongsToIBANRegistry() IBANValidator

CountryBelongsToIBANRegistry ensures that the country is listed in the iban registry https://www.swift.com/resource/iban-registry-pdf

func CountryBelongsToSEPA

func CountryBelongsToSEPA() IBANValidator

CountryBelongsToSEPA ensures that the country belongs to the Single Euro Payments Area according to https://www.swift.com/resource/iban-registry-pdf

func NationalFormatCheck

func NationalFormatCheck() IBANValidator

NationalFormatCheck checks the national rules (format and check digits), if there is a registered BBANChecker for this country code.

type TooShortError

type TooShortError struct {
	ActualLen   int
	ExpectedLen int
}

TooShortError indicates that the provided string is shorter than expected.

func (TooShortError) Error

func (e TooShortError) Error() string