IBAN-validaties met de Bluem IBAN-validatieservice

Wiki (nl)
,
1

Bluem biedt onder de naam “viamijnbank” API’s aan voor financiele gegevens:

  • CCBRCheck
  • CRUKSCheck
  • EMandate
  • EPayment
  • IBANCheck
  • IDentity

IBAN-validatie

Met de IBANCheck-API kan een IBAN-rekeningnummer gevalideerd worden tegen de naam van (een van de) rekeninghouders. Hieruit kan komen het IBAN-rekeningnummer niet bestaat of ongeldig is, dat de naam vrijwel niet past bij het rekeningnummer, dat de naam niet helemaal correct is, maar wel gelijkend, of dat de naam en rekeningnummer samen behoren bij hetzelfde rekeningnummer.

Met de Bluem-API voor IBAN-controles kan op relatief eenvoudige wijze een controle doorgevoerd worden om fraude en/of administratieve fouten te signaleren.

De onderstaande code laat zien hoe de Bluem IBANCheck-API gebruikt kan worden vanuit Invantive UniversalSQL of Invantive PSQL. Er is hiervoor geen abonnement nodig; het gebruik is ook mogelijk met het Free Plan.

Het gebruik bestaat in dit voorbeeld uit vier onderdelen:

  • verzamel lijst van namen en IBAN-rekeningnummers, plus een kenmerk in een brontabel,
  • zet de brontabel om in data voor de Bluem-API,
  • roep massaal de Bluem-API aan en leg de uitkomsten vast in een resultaattabel,
  • verwerk de uitkomsten verder in een datawarehouse of druk deze af.

Verzamel Namen en IBAN-rekeningnummers in Brontabel

De gegevens kunnen uit meerdere systemen afkomstig zijn. Er worden drie voorbeelden getoond; dit kan met HTMLTABLE, EXCELTABLE, JSONTABLE of XMLTABLE ook uitgebreid worden naar tekstformaten.

Dummy Driver als Bron

Een mogelijke bron is de dummy driver van Invantive:

--
-- Sample using Dummy driver (in-memory sample database).
--
create or replace table IbanAccountsDummyDriver@InMemoryStorage
as
select distinct
       lvr_naam
       name
,      lvr_iban_nummer
       iban
,      lvr_id
       orig_system_reference
from   Organisations
where  lvr_iban_nummer is not null
order
by     name

Invantive Estate als Bron

Een mogelijke bron is een Invantive Estate-omgeving:

--
-- Sample using Invantive Estate as source.
--
create or replace table IbanAccountsInvantiveEstate@InMemoryStorage
as
select distinct
       lvr_naam
       name
,      lvr_iban_nummer
       iban
,      lvr_id
       orig_system_reference
from   bubs_leveranciers_v@ora
where  lvr_iban_nummer is not null
order
by     name

Exact Online als Bron

Een mogelijke bron is een Exact Online-omgeving:

--
-- Sample using Exact Online as source.
--
create or replace table IbanAccountsExactOnline@InMemoryStorage
as
select distinct
       bat.AccountName
       name
,      bat.IBAN
       iban
--
-- Note that Bluem only accepts short numbers as AccountReference.
--
,      act.Code
       orig_system_reference
from   BankAccounts@eol bat
join   AccountsIncremental@eol act
on     act.Id = bat.Account
where  bat.IBAN is not null

Vertaal Brontabel voor de Bluem-API

De onderstaande SQL maakt een tabel met de gegevens voor de Bluem IBAN-API.

Voer testgebruik eerst de volgende drie onderdelen vervangen:

  • IbanAccountsNAME vervangen door de gewenste brontabel,
  • S1234 vervangen door de sender ID die u van Bluem hebt ontvangen,
  • 0f0f0f...0f0f0f vervangen door het token dat u van Bluem hebt ontvangen.
--
-- Prepare calls to Bluem IBAN validation service API.
--
create or replace table IbanValidations@InMemoryStorage
as
select case
       when dayofweek(sysdateutc) = 1 then 'Monday'
       when dayofweek(sysdateutc) = 2 then 'Tuesday'
       when dayofweek(sysdateutc) = 3 then 'Wednesday'
       when dayofweek(sysdateutc) = 4 then 'Thursday'
       when dayofweek(sysdateutc) = 5 then 'Friday'
       when dayofweek(sysdateutc) = 6 then 'Saturday'
       when dayofweek(sysdateutc) = 7 then 'Sunday'
       end
       || ', '
       || day(sysdateutc)
       || ' '
       || case 
          when month(sysdateutc) = 1 then 'January'
          when month(sysdateutc) = 2 then 'February'
          when month(sysdateutc) = 3 then 'March'
          when month(sysdateutc) = 4 then 'April'
          when month(sysdateutc) = 5 then 'May'
          when month(sysdateutc) = 6 then 'June'
          when month(sysdateutc) = 7 then 'July'
          when month(sysdateutc) = 8 then 'August'
          when month(sysdateutc) = 9 then 'September'
          when month(sysdateutc) = 10 then 'October'
          when month(sysdateutc) = 11 then 'November'
          when month(sysdateutc) = 12 then 'December'
          end
       || ' '
       || year(sysdateutc)
       || ' '
       || to_char(sysdateutc, 'HH24:MI:SS')
       || ' '
       || 'GMT'
       header_x_ttrs_date
,      1
       header_x_ttrs_files_count
,      'INX-'
       || stg.sender_id
       || '-BSP1-'
       || to_char(sysdateutc, 'YYYYMMDDHH24MISS') || lpad(to_char(trunc(random()*1E6)), 6, '0')
       || '.xml'
       header_x_ttrs_filename
,      'application/xml'
       || ';'
       || 'type=INX'
       || ';'
       || 'charset=UTF-8'
       header_content_type
       --
       -- Replace 'test' by production API service when ready to process.
       --
,      'https://test.viamijnbank.net/icr/createTransactionWithToken'
       || '?'
       || 'token='
       || token
       url
,      xmlformat
       ( '<IBANCheckInterface'
         || ' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"'
         || ' type="TransactionRequest"'
         || ' mode="direct"'
         || ' senderID="' || sender_id || '"'
         || ' version="1.0"'
         || ' createDateTime="2019-06-27T12:00:12.000Z"'
         || ' messageCount="1"'
         || ' xsi:noNamespaceSchemaLocation="../IBANCheckInterface.xsd"'
         || '>'
         || '  <IBANCheckTransactionRequest>'
         || '    ' || xmlelement('IBAN', bankact.iban)
         || '    ' || xmlelement('AssumedName', bankact.name)
         || '    ' || xmlelement('DebtorReference', bankact.orig_system_reference)
         || '  </IBANCheckTransactionRequest>'
         || '</IBANCheckInterface>'
       ) 
       xml
,      bankact.iban CacheKey
from   ( select 'S1234' sender_id /* Caller identification. */
         ,      '0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f' token /* Caller password. */
       ) stg
join   IbanAccountsNAME@InMemoryStorage bankact

Registreer Bluem-API Resultaten in Resultaattabel

De volgende code neemt de invoer voor de IBAN-check API’s en voert die massaal uit tegen de Bluem API-server. In het algemeen worden er 10 tot 20 API-calls per seconde serieel verwerkt.

De resultaten van de IBAN-check landen in de tabel IbanValidationResults@InMemoryStorage, inclusief een aantal auditvelden zoals DateRetrievalUtc.

--
-- Results of IBAN validation service calls to Bluem-server.
--
create or replace table IbanValidationResults@InMemoryStorage
as
select xte.*
--
-- Audit.
--
,      htp.DATE_RETRIEVAL_UTC DateRetrievalUtc
,      htp.HTTP_STATUS_CODE HttpStatusCode
,      htp.BYTES_RETRIEVED BytesRetrieved
,      htp.RETRIEVAL_DURATION_MS RetrievalDurationMs
,      htp.CERTIFICATE_SUBJECT CertificateSubject
,      htp.CERTIFICATE_ISSUER CertificateIssuer
,      htp.CERTIFICATE_SERIAL_NUMBER CertificateSerialNumber
from   IbanValidations@InMemoryStorage ivn
join   HTTPDOWNLOAD@DataDictionary
       ( url => ivn.url
       , contentType => ivn.header_content_type
       , method => 'POST'
       , headers 
         => 
         'x-ttrs-date=' 
         || ivn.header_x_ttrs_date 
         || '&' 
         || 'x-ttrs-files-count=' 
         || header_x_ttrs_files_count 
         || '&x-ttrs-filename=' 
         || header_x_ttrs_filename
       , diskCache => true
       , diskCacheMaxAgeSec => 86400 /* One day. */
       , textPayload => ivn.xml
       , cacheKey => ivn.CacheKey
       , ignoreWebError => true
       ) htp
on     htp.RETRIEVAL_SUCCESSFUL = true
join   xmltable
       ( '/IBANCheckInterface/IBANCheckTransactionResponse'
         passing htp.contents_char
         --
         -- Input data.
         --
         columns IBAN                   varchar2(128) path 'IBAN'
         ,       AssumedName            varchar2(256) path 'AssumedName'
         ,       DebtorReference        varchar2      path 'DebtorReference'
         --
         -- Output data.
         --
         -- Can be: UNKNOWN, INVALID, KNOWN, VALID.
         --
         ,       IBANResult             varchar2      path 'IBANCheckResult/IBANResult'
         --
         -- Can be: null, MISTYPED, NON_MATCHING, MATCHING.
         --
         ,       NameResult             varchar2      path 'IBANCheckResult/NameResult'
         --
         -- Can be: null, ACTIVE, INACTIVE, UNKNOWN.
         --
         ,       AccountStatus          varchar2      path 'IBANCheckResult/AccountStatus'
         ,       SuggestedName          varchar2(256) path 'IBANCheckResult/SuggestedName'
         --
         -- AccountType can be ORGANISATION, NATURAL_PERSON, UNKNOWN.
         --
         ,       AccountType            varchar2      path 'AccountDetails/AccountType'
         ,       IsJointAccount         boolean       path 'AccountDetails/IsJointAccount'
         ,       NumberOfAccountHolders int           path 'AccountDetails/NumberOfAccountHolders'
         ,       CountryName            varchar2(64)  path 'AccountDetails/CountryName'
         ,       Municipality           varchar2(128) path 'AccountDetails/Municipality'
       ) xte

Verwerk Uitkomsten

De IBAN-validaties zijn nu klaar. U kunt de resultaten bijvoorbeeld blijven wegschrijven naar een Excel-werkboek of een Azure SQL Server-tabel voor verder gebruik. In dit geval wordt het beperkt tot het opvragen:

select *
from   IbanValidationResults@InMemoryStorage