Module: Ibandit::IBANBuilder

Defined in:
lib/ibandit/iban_builder.rb

Constant Summary collapse

SUPPORTED_COUNTRY_CODES = 
%w(AT BE CY DE EE ES FI FR GB IE IT LU LV MC NL PT
SI SK SM).freeze

Class Method Summary collapse

Class Method Details

.build(opts) ⇒ Object 



6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
# File 'lib/ibandit/iban_builder.rb', line 6

def self.build(opts)
  country_code = opts.delete(:country_code)

  if country_code.nil?
    raise ArgumentError, 'You must provide a country_code'
  elsif !SUPPORTED_COUNTRY_CODES.include?(country_code)
    msg = "Don't know how to build an IBAN for country code #{country_code}"
    raise UnsupportedCountryError, msg
  else
    require_fields(country_code, opts)
    bban = send(:"build_#{country_code.downcase}_bban", opts)
    build_iban(country_code, bban)
  end
end

.build_at_bban(opts) ⇒ Object

Country-specific BBAN creation #



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/ibandit/iban_builder.rb', line 25

def self.build_at_bban(opts)
  # Local account details format:
  #   aaaaaaaaaaa bbbbb
  #   Account number may be 4-11 digits long
  #
  # Local account details name(s):
  #   Bank code: 'Bankleitzahl' or 'BLZ'
  #   Account number: 'Kontonummer' or 'Kto.-Nr'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   Austrian account numbers have built-in check digits. The checking
  #   rules are not public.
  #
  # Padding:
  #   Add leading zeros to account number if < 11 digits.
  [
    opts[:bank_code],
    opts[:account_number].rjust(11, '0')
  ].join
end

.build_be_bban(opts) ⇒ Object 



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/ibandit/iban_builder.rb', line 48

def self.build_be_bban(opts)
  # Local account details format: bbb-aaaaaaa-cc
  #
  # Local account details name(s):
  #   Single name for all fields: "Rekeningnummer / Numéro de compte"
  #   All fields are entered in one block, separated by hyphens for clarity
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The last two digits of the account number are check digits, but these
  #   are considered integral to the account number itself. See
  #   CheckDigit#belgian for details of their calculation.
  #
  # Additional info:
  #   The first three digits of Belgian account numbers are the bank_code,
  #   but the account number is not considered complete without these three
  #   numbers and the IBAN structure file includes them in its definition of
  #   the account number. As a result, this method ignores all arguments
  #   other than the account number.
  opts[:account_number].tr('-', '')
end

.build_cy_bban(opts) ⇒ Object 



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/ibandit/iban_builder.rb', line 71

def self.build_cy_bban(opts)
  # Local account details format:
  #   bbb-sssss aaaaaaaaaaaaaaaa
  #   Account number may be 7-16 digits long
  #
  # Local account details name(s):
  #   Bank code: 'Kodikos Trapezas'
  #   Branch code: 'Kodikos Katastimatos'
  #   Account number: 'Arithmos Logariasmou'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   Some Cypriot banks may be using check digits in their account numbers,
  #   but there's no central source of them.
  #
  # Padding:
  #   Add leading zeros to account number if < 16 digits.
  #
  # Additional info:
  #   Cypriot bank and branch codes are often communicated as a single code,
  #   so this method handles being passed them together or separately.
  combined_bank_code = opts[:bank_code]
  combined_bank_code += opts[:branch_code] || ''

  [
    combined_bank_code,
    opts[:account_number].rjust(16, '0')
  ].join
end

.build_de_bban(opts) ⇒ Object 



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/ibandit/iban_builder.rb', line 102

def self.build_de_bban(opts)
  # Local account details format:
  #   bbbbbbbb aaaaaaaaaa
  #   Account number may be 1-10 digits long
  #
  # Local account details name(s):
  #   Bank code: 'Bankleitzahl' or 'BLZ'
  #   Account number: 'Kontonummer' or 'Kto.-Nr'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   Local bank validation is carried out by matching the bank code with
  #   the right algorithm key, then applying that bank-specific algorithm.
  #
  # Padding:
  #   Add leading zeros to account number if < 10 digits.
  #
  # Additional info:
  #   There are many exceptions to the way German bank details translate
  #   into an IBAN, detailed into a 200 page document compiled by the
  #   Bundesbank, and handled by the GermanDetailsConverter class.
  converted_details = GermanDetailsConverter.convert(opts)

  [
    converted_details[:bank_code],
    converted_details[:account_number].rjust(10, '0')
  ].join
end

.build_ee_bban(opts) ⇒ Object 



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/ibandit/iban_builder.rb', line 132

def self.build_ee_bban(opts)
  # Local account details format:
  #   bbaaaaaaaaaaax
  #   Account number may be up to 14 characters long
  #   Bank code can be found by extracted from the first two digits of the
  #   account number and converted using the rules at
  #   http://www.pangaliit.ee/en/settlements-and-standards/bank-codes-of-estonian-banks
  #
  # Local account details name(s):
  #   Account number: 'Kontonumber'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The last digit of the account number is a check digit, but this is
  #   built-in. An implementation of the check digit algorithm is available
  #   in CheckDigit#estonian.
  #
  # Padding:
  #   Add leading zeros to account number if < 14 digits.
  #
  # Additional info:
  #   Estonian national bank details were replaced with IBANs in Feb 2014.
  #   All Estonian payers should therefore know their IBAN.
  domestic_bank_code = opts[:account_number].gsub(/\A0+/, '').slice(0, 2)

  case domestic_bank_code
  when '11' then iban_bank_code = '22'
  when '93' then iban_bank_code = '00'
  else iban_bank_code = domestic_bank_code
  end

  iban_bank_code + opts[:account_number].rjust(14, '0')
end

.build_es_bban(opts) ⇒ Object 



167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/ibandit/iban_builder.rb', line 167

def self.build_es_bban(opts)
  # Local account details format:
  #   bbbb-ssss-xx-aaaaaaaaaa
  #   Usually not separated, except by spaces or dashes
  #
  # Local account details name(s):
  #   Full details (20 digits): Código Cuenta Cliente
  #   Bank code (first 4 digits): Código de entidad
  #   Branch code (next 4 digits): Código de oficina
  #   Check digits (next 2 ditigs): Dígitos de control
  #   Account number (final 10 digits): Número de cuenta
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The 2 check digits described above are part of the "account number" as
  #   defined by SWIFT. See CheckDigit#spanish for their generation.
  #
  # Padding: None
  #
  # Additional info:
  #   This method supports being passed the component IBAN parts, as defined
  #   by SWIFT, or a single 20 digit string.
  if opts.include?(:bank_code) && opts.include?(:branch_code)
    [
      opts[:bank_code],
      opts[:branch_code],
      opts[:account_number]
    ].join
  else
    opts[:account_number].tr('-', '')
  end
end

.build_fi_bban(opts) ⇒ Object 



201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/ibandit/iban_builder.rb', line 201

def self.build_fi_bban(opts)
  # Local account details format:
  #   bbbbbb-aaaaaaax
  #   Usually two joined fields separated by a hyphen
  #
  # Local account details name(s):
  #   Full details: 'Tilinumeron rakenne'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The last digit of the account number is a check digit. The check digit
  #   algorithm is available in CheckDigit#lund.
  #
  # Padding:
  #   Finnish account numbers need to be expanded into "electronic format"
  #   by adding zero-padding. The expansion method depends on the first
  #   character of the bank code.
  if %w(4 5 6).include?(opts[:bank_code][0])
    [
      opts[:bank_code],
      opts[:account_number][0],
      opts[:account_number][1..-1].rjust(7, '0')
    ].join
  else
    opts[:bank_code] + opts[:account_number].rjust(8, '0')
  end
end

.build_fr_bban(opts) ⇒ Object 



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/ibandit/iban_builder.rb', line 230

def self.build_fr_bban(opts)
  # Local account details format:
  #   bbbbb-sssss-aaaaaaaaaaa-xx
  #   4 separated fields
  #
  # Local account details name(s):
  #   Bank code (5 digits): 'Code banque'
  #   Branch code (5 digits): 'Code guichet'
  #   Account number (max 11 digits): 'Numéro de compte'
  #   Check digits (2 digits): 'Clé RIB'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   French BBANs include two "RIB key" check digits. In the SWIFT IBAN
  #   structure definition these check digits are part of the account
  #   number, although customers expect to see them as a separate field.
  #   You should concatenate the account number with the entered check
  #   digits when using this method.
  #
  # Padding: None
  [
    opts[:bank_code],
    opts[:branch_code],
    opts[:account_number]
  ].join
end

.build_gb_bban(opts) ⇒ Object 



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/ibandit/iban_builder.rb', line 258

def self.build_gb_bban(opts)
  # Local account details format:
  #   ssssss aaaaaaaa
  #   2 separated fields
  #
  # Local account details name(s):
  #   Branch code: Sort code
  #   Account number: Account number
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   Local bank validation is carried out on a bank-by-bank basis, and out
  #   of scope for this gem.
  #
  # Padding:
  #   Add leading zeros to account number if < 8 digits.
  #
  # Additional info:
  #   UK BBANs include the first four characters of the BIC. This requires a
  #   BIC finder lambda to be defined, or the bank_code to be supplied.
  branch_code = opts[:branch_code].gsub(/[-\s]/, '')

  if opts[:bank_code]
    bank_code = opts[:bank_code]
  else
    bic = Ibandit.find_bic('GB', branch_code)
    raise BicNotFoundError, 'BIC finder failed to find a BIC.' if bic.nil?
    bank_code = bic.slice(0, 4)
  end

  [
    bank_code,
    branch_code,
    opts[:account_number].gsub(/[-\s]/, '').rjust(8, '0')
  ].join
end

.build_iban(country_code, bban) ⇒ Object 



520
521
522
523
524
525
526
527
528
 
# File 'lib/ibandit/iban_builder.rb', line 520

def self.build_iban(country_code, bban)
  iban = [
    country_code,
    CheckDigit.iban(country_code, bban),
    bban
  ].join

  IBAN.new(iban)
end

.build_ie_bban(opts) ⇒ Object 



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/ibandit/iban_builder.rb', line 314

def self.build_ie_bban(opts)
  # Ireland uses the same BBAN construction method as the United Kingdom
  branch_code = opts[:branch_code].gsub(/[-\s]/, '')

  if opts[:bank_code]
    bank_code = opts[:bank_code]
  else
    bic = Ibandit.find_bic('IE', branch_code)
    raise BicNotFoundError, 'BIC finder failed to find a BIC.' if bic.nil?
    bank_code = bic.slice(0, 4)
  end

  [
    bank_code,
    branch_code,
    opts[:account_number].gsub(/[-\s]/, '').rjust(8, '0')
  ].join
end

.build_it_bban(opts) ⇒ Object 



333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
 
# File 'lib/ibandit/iban_builder.rb', line 333

def self.build_it_bban(opts)
  # Local account details format:
  #   x/bbbbb/sssss/cccccccccccc
  #   4 fields, separated by slashes
  #   The check digit is NOT included in the any of the other SWIFT
  #   elements, so should be passed explicitly or left blank for it to be
  #   calculated implicitly
  #
  # Local bank details name(s):
  #   Check digit: 'CIN'
  #   Bank code: 'Codice ABI'
  #   Branch code: 'CAB'
  #   Account number: 'Numero di conto'
  #
  # BBAN-specific check digits:
  #   Italian BBANs include a single BBAN-specific check digit, calculated
  #   using a bespoke algorithm. See CheckDigit#italian.
  #
  # Padding:
  #   Add leading zeros to account number if < 10 digits.
  combined_code = [
    opts[:bank_code],
    opts[:branch_code],
    opts[:account_number].rjust(12, '0')
  ].join

  check_digit = opts[:check_digit] || CheckDigit.italian(combined_code)

  [check_digit, combined_code].join
end

.build_lu_bban(opts) ⇒ Object 



296
297
298
299
300
301
302
303
 
# File 'lib/ibandit/iban_builder.rb', line 296

def self.build_lu_bban(opts)
  # Additional info:
  #   Luxembourgian national bank details were replaced with IBANs in 2002.
  #   All Luxembourgian payers should therefore know their IBAN, and are
  #   unlikely to know how it breaks down. This method is included for
  #   consistency with the IBAN structure only.
  [opts[:bank_code], opts[:account_number]].join
end

.build_lv_bban(opts) ⇒ Object 



305
306
307
308
309
310
311
312
 
# File 'lib/ibandit/iban_builder.rb', line 305

def self.build_lv_bban(opts)
  # Additional info:
  #   Latvian national bank details were replaced with IBANs in 2004.
  #   All Latvian payers should therefore know their IBAN, and are
  #   unlikely to know how it breaks down. This method is included for
  #   consistency with the IBAN structure only.
  [opts[:bank_code], opts[:account_number]].join
end

.build_mc_bban(opts) ⇒ Object 



364
365
366
367
 
# File 'lib/ibandit/iban_builder.rb', line 364

def self.build_mc_bban(opts)
  # Monaco uses the same BBAN construction method as France
  build_fr_bban(opts)
end

.build_nl_bban(opts) ⇒ Object 



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
 
# File 'lib/ibandit/iban_builder.rb', line 369

def self.build_nl_bban(opts)
  # Local account details format:
  #   aaaaaaaaaa
  #   1 field for account number only
  #   In theory the bank code can be looked up from the account number, but
  #   we don't currently have a way of doing so.
  #
  # Local bank details name(s):
  #   Account number: 'Rekeningnummer'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   A modulus 11 check can be applied to Dutch IBANs. See CheckDigit#dutch
  #   for an implementation.
  #
  # Padding:
  #   Add leading zeros to account number if < 10 digits.
  [
    opts[:bank_code],
    opts[:account_number].rjust(10, '0')
  ].join
end

.build_pt_bban(opts) ⇒ Object 



393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/ibandit/iban_builder.rb', line 393

def self.build_pt_bban(opts)
  # Local account details format:
  #   bbbb.ssss.ccccccccccc.xx
  #   Usually presented in one block
  #
  # Local account details name(s):
  #   Full details: Número de Identificaçao Bancária (NIB)
  #   Bank code: Código de Banco
  #   Branch code: Código de Balcao
  #   Account number: Número de conta
  #   Local check digits: Dígitos de controlo
  #
  # BBAN-specific check digits:
  #   Technically none, but see below
  #
  # Other check digits:
  #   The last two digits of Portuguese account numbers, as defined by
  #   SWIFT, are check digits, calculated using the same algorithm as the
  #   overall IBAN check digits (i.e., mod_97_10). However, customers expect
  #   to see these check digits as a separate field. You should concatenate
  #   the account number with the entered check digits when using this
  #   method.
  #
  # Additional info:
  #   A side-effect of Portugal using the same algorithm for its local check
  #   digits as the overall IBAN check digits is that the overall digits are
  #   always 50.
  [
    opts[:bank_code],
    opts[:branch_code],
    opts[:account_number]
  ].join
end

.build_si_bban(opts) ⇒ Object 



427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/ibandit/iban_builder.rb', line 427

def self.build_si_bban(opts)
  # Local account details format:
  #   bbbbb-aaaaaaaaxx
  #   Two fields, separated by a dash
  #
  # Local account details name(s):
  #   Full details: Transakcijski račun
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The last two digits of Slovenian account numbers, as defined by
  #   SWIFT, are check digits, calculated using the same algorithm as the
  #   overall IBAN check digits (i.e., mod_97_10).
  #
  # Additional info:
  #   A side-effect of Slovenia using the same algorithm for its local check
  #   digits as the overall IBAN check digits is that the overall digits are
  #   always 56.
  [
    opts[:bank_code],
    opts[:account_number].rjust(10, '0')
  ].join
end

.build_sk_bban(opts) ⇒ Object 



452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
 
# File 'lib/ibandit/iban_builder.rb', line 452

def self.build_sk_bban(opts)
  # Local account details format:
  #   pppppp-aaaaaaaaaa/bbbb
  #   Three fields (or two, if prefix and account number are merged)
  #
  # Local account details name(s):
  #   Account number prefix: Předčíslí
  #   Account number: číslo účtu
  #   Bank code: 'Kód banky'
  #
  # BBAN-specific check digits: none
  #
  # Other check digits:
  #   The last digits of the account_number_prefix and the account_number
  #   are check digits. See CheckDigit#slovakian_prefix and
  #   CheckDigit#slovakian_basic
  #
  # Additional info:
  #   The SWIFT definition of a Slovakian IBAN includes both the account
  #   number prefix and the account number. This method therefore supports
  #   passing those fields concatenated.
  if opts.include?(:account_number_prefix)
    [
      opts[:bank_code],
      opts[:account_number_prefix].rjust(6, '0'),
      opts[:account_number].rjust(10, '0')
    ].join
  else
    [
      opts[:bank_code],
      opts[:account_number].tr('-', '').rjust(16, '0')
    ].join
  end
end

.build_sm_bban(opts) ⇒ Object 



487
488
489
490
 
# File 'lib/ibandit/iban_builder.rb', line 487

def self.build_sm_bban(opts)
  # San Marino uses the same BBAN construction method as Italy
  build_it_bban(opts)
end

.require_fields(country_code, opts) ⇒ Object

Helper methods #



496
497
498
499
500
501
502
503
 
# File 'lib/ibandit/iban_builder.rb', line 496

def self.require_fields(country_code, opts)
  required_fields(country_code).each do |arg|
    next if opts[arg]

    msg = "#{arg} is a required field when building an #{country_code} IBAN"
    raise ArgumentError, msg
  end
end

.required_fields(country_code) ⇒ Object 



505
506
507
508
509
510
511
512
513
514
515
516
517
518
 
# File 'lib/ibandit/iban_builder.rb', line 505

def self.required_fields(country_code)
  case country_code
  when 'AT', 'CY', 'DE', 'FI', 'LU', 'LV', 'NL', 'SI', 'SK'
    %i(bank_code account_number)
  when 'BE', 'EE', 'ES'
    %i(account_number)
  when 'GB', 'IE'
    if Ibandit.bic_finder.nil? then %i(bank_code branch_code account_number)
    else %i(branch_code account_number)
    end
  else
    %i(bank_code branch_code account_number)
  end
end