0
# Financial Validation
1

2
Validators for financial instruments including credit cards, banking codes, and securities identifiers. These validators implement industry-standard algorithms like Luhn checksum and provide comprehensive coverage of major financial data formats.
3

4
## Capabilities
5

6
### Credit Card Validation
7

8
Validates credit card numbers using the Luhn algorithm and card-specific format rules.
9

10
```python { .api }
11
def card_number(value: str, /) -> Union[Literal[True], ValidationError]:
12
    """
13
    Validate generic credit card numbers using Luhn algorithm.
14
    
15
    Parameters:
16
    - value: Credit card number string (digits only or with spaces/dashes)
17
    
18
    Returns:
19
    True if valid card number, ValidationError otherwise
20
    
21
    Uses Luhn checksum algorithm for validation.
22
    Accepts numbers with or without separators.
23
    """
24

25
def visa(value: str, /) -> Union[Literal[True], ValidationError]:
26
    """
27
    Validate Visa credit card numbers.
28
    
29
    Parameters:
30
    - value: Visa card number string
31
    
32
    Returns:
33
    True if valid Visa number, ValidationError otherwise
34
    
35
    Validates length (13, 16, or 19 digits) and prefix (4).
36
    Includes Luhn checksum validation.
37
    """
38

39
def mastercard(value: str, /) -> Union[Literal[True], ValidationError]:
40
    """
41
    Validate Mastercard credit card numbers.
42
    
43
    Parameters:
44
    - value: Mastercard number string
45
    
46
    Returns:
47
    True if valid Mastercard number, ValidationError otherwise
48
    
49
    Validates length (16 digits) and prefix ranges.
50
    Includes Luhn checksum validation.
51
    """
52

53
def amex(value: str, /) -> Union[Literal[True], ValidationError]:
54
    """
55
    Validate American Express credit card numbers.
56
    
57
    Parameters:
58
    - value: American Express card number string
59
    
60
    Returns:
61
    True if valid Amex number, ValidationError otherwise
62
    
63
    Validates length (15 digits) and prefix (34 or 37).
64
    Includes Luhn checksum validation.
65
    """
66

67
def unionpay(value: str, /) -> Union[Literal[True], ValidationError]:
68
    """
69
    Validate UnionPay credit card numbers.
70
    
71
    Parameters:
72
    - value: UnionPay card number string
73
    
74
    Returns:
75
    True if valid UnionPay number, ValidationError otherwise
76
    """
77

78
def diners(value: str, /) -> Union[Literal[True], ValidationError]:
79
    """
80
    Validate Diners Club credit card numbers.
81
    
82
    Parameters:
83
    - value: Diners Club card number string
84
    
85
    Returns:
86
    True if valid Diners number, ValidationError otherwise
87
    
88
    Validates length (14 digits) and prefix ranges.
89
    Includes Luhn checksum validation.
90
    """
91

92
def jcb(value: str, /) -> Union[Literal[True], ValidationError]:
93
    """
94
    Validate JCB credit card numbers.
95
    
96
    Parameters:
97
    - value: JCB card number string
98
    
99
    Returns:
100
    True if valid JCB number, ValidationError otherwise
101
    
102
    Validates length (16 digits) and prefix ranges.
103
    Includes Luhn checksum validation.
104
    """
105

106
def discover(value: str, /) -> Union[Literal[True], ValidationError]:
107
    """
108
    Validate Discover credit card numbers.
109
    
110
    Parameters:
111
    - value: Discover card number string
112
    
113
    Returns:
114
    True if valid Discover number, ValidationError otherwise
115
    
116
    Validates length (16 digits) and prefix ranges.
117
    Includes Luhn checksum validation.
118
    """
119

120
def mir(value: str, /) -> Union[Literal[True], ValidationError]:
121
    """
122
    Validate Mir payment system card numbers.
123
    
124
    Parameters:
125
    - value: Mir card number string
126
    
127
    Returns:
128
    True if valid Mir number, ValidationError otherwise
129
    
130
    Russian payment system card validation.
131
    Includes Luhn checksum validation.
132
    """
133
```
134

135
### Banking Codes
136

137
Validates international banking and account identifiers.
138

139
```python { .api }
140
def iban(value: str, /) -> Union[Literal[True], ValidationError]:
141
    """
142
    Validate International Bank Account Numbers (IBAN).
143
    
144
    Parameters:
145
    - value: IBAN string to validate
146
    
147
    Returns:
148
    True if valid IBAN, ValidationError otherwise
149
    
150
    Validates:
151
    - Country code (2 letters)
152
    - Check digits (2 digits)
153
    - Basic Bank Account Number (up to 30 alphanumeric)
154
    - MOD-97 checksum algorithm
155
    
156
    Accepts IBANs with or without spaces.
157
    """
158
```
159

160
### Securities Identifiers
161

162
Validates financial securities identifiers used in trading and reporting.
163

164
```python { .api }
165
def cusip(value: str, /) -> Union[Literal[True], ValidationError]:
166
    """
167
    Validate CUSIP (Committee on Uniform Securities Identification Procedures) identifiers.
168
    
169
    Parameters:
170
    - value: CUSIP identifier string
171
    
172
    Returns:
173
    True if valid CUSIP, ValidationError otherwise
174
    
175
    Validates:
176
    - Length (9 characters)
177
    - Format (6 alphanumeric + 2 alphanumeric + 1 check digit)
178
    - Check digit algorithm
179
    
180
    Used primarily in North American markets.
181
    """
182

183
def isin(value: str, /) -> Union[Literal[True], ValidationError]:
184
    """
185
    Validate ISIN (International Securities Identification Number) codes.
186
    
187
    Parameters:
188
    - value: ISIN code string
189
    
190
    Returns:
191
    True if valid ISIN, ValidationError otherwise
192
    
193
    Validates:
194
    - Length (12 characters)
195
    - Format (2 letter country code + 9 alphanumeric + 1 check digit)
196
    - Luhn algorithm check digit
197
    
198
    International standard for securities identification.
199
    """
200

201
def sedol(value: str, /) -> Union[Literal[True], ValidationError]:
202
    """
203
    Validate SEDOL (Stock Exchange Daily Official List) codes.
204
    
205
    Parameters:
206
    - value: SEDOL code string
207
    
208
    Returns:
209
    True if valid SEDOL, ValidationError otherwise
210
    
211
    Validates:
212
    - Length (7 characters)
213
    - Format (6 alphanumeric + 1 check digit)
214
    - Check digit algorithm
215
    
216
    Used primarily in UK and Irish markets.
217
    """
218
```
219

220
## Usage Examples
221

222
```python
223
import validators
224

225
# Credit card validation
226
validators.card_number('4111111111111111')    # True (generic Luhn check)
227
validators.visa('4111111111111111')           # True (Visa specific)
228
validators.mastercard('5555555555554444')     # True (Mastercard specific)
229
validators.amex('378282246310005')            # True (15-digit Amex)
230

231
# Card numbers with separators
232
validators.visa('4111-1111-1111-1111')        # True
233
validators.visa('4111 1111 1111 1111')        # True
234

235
# Different card types
236
validators.diners('30569309025904')           # True (14-digit Diners)
237
validators.jcb('3530111333300000')            # True (JCB)
238
validators.discover('6011111111111117')       # True (Discover)
239
validators.unionpay('6200000000000005')       # True (UnionPay)
240
validators.mir('2200000000000004')            # True (Mir)
241

242
# IBAN validation
243
validators.iban('GB82 WEST 1234 5698 7654 32')  # True (with spaces)
244
validators.iban('GB82WEST12345698765432')        # True (without spaces)
245
validators.iban('DE89 3704 0044 0532 0130 00')  # True (German IBAN)
246

247
# Securities identifiers
248
validators.cusip('037833100')                  # True (Apple Inc.)
249
validators.isin('US0378331005')                # True (Apple Inc. ISIN)
250
validators.sedol('0263494')                    # True (British Petroleum)
251

252
# Invalid examples
253
validators.visa('4111111111111112')            # ValidationError (bad check digit)
254
validators.iban('GB82WEST12345698765433')      # ValidationError (bad checksum)
255
validators.cusip('037833101')                  # ValidationError (bad check digit)
256
```
257

258
## Error Handling
259

260
Financial validators provide detailed error information:
261

262
```python
263
import validators
264

265
# Get validation details
266
result = validators.visa('1234567890123456')
267
if not result:
268
    print(f"Validation failed: {result}")
269
    print(f"Function: {result.func.__name__}")
270
    print(f"Value: {result.value}")
271

272
# Raise exceptions for invalid data
273
try:
274
    validators.iban('INVALID-IBAN', r_ve=True)
275
except validators.ValidationError as e:
276
    print(f"IBAN validation failed: {e}")
277
```