This page permanently redirects to gemini://code.pfad.fr/swift/.

swift package - code.pfad.fr/swift

import "code.pfad.fr/swift"

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.

=> demo in the browser

Example

// SPDX-FileCopyrightText: 2023 Olivier Charvin 
//
// 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())
}

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      uint8
	Actual        uint8
	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]

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

=> 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 (from the start of the submitted string)
}

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

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

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

Files

=> bban.go | bban_registry.go | bic.go | columns.go | country.go | iban.go

Directories

=> bic

package bic computes the BIC from an IBAN (for supported countries).

=> cmd/iban

iban analyses an International Bank Account Number (IBAN).

=> internal/format

package format is used internally to describe the format of an IBAN.

Forge

=> https://codeberg.org/pfad.fr/swift

git clone

https://codeberg.org/pfad.fr/swift.git
git@codeberg.org:pfad.fr/swift.git