Documentação da Validation API V4 do IBAN

Esta API é parte da nossaIBAN Suite

1. O que há de novo na API de validação do IBAN da V4?


Estamos trabalhando constantemente para melhorar nossos serviços e fornecer melhores soluções de validação de pagamento.
Você pode perceber que a API do IBAN Suite pulou uma versão da iteração de V2 para V4.
Isso foi feito porque unimos as outras APIs, como SortWare v3 em uma única iteração de versionamento, por exemplo v4.

Mudanças (de v2 para v4):


Nova validação adicionada (erro 206) - API V4 agora verifica caracteres ilegais no IBAN de entrada.
O novo código de erro - 206 (Validation Failed) com mensagem: IBAN contém caracteres ilegais.
Esse código de erro fornecerá mais informações caso você envie um IBAN com caracteres não alfanuméricos para o nosso sistema.
O comportamento anterior era retirar todos os caracteres não alfanuméricos e executar a validação

Nova validação adicionada (erro 207) - País não suporta IBAN
Essa camada de validação informará se o código do país do IBAN enviado não faz parte dos países oficiais que oferecem suporte a pagamentos do IBAN.
Por exemplo, uma pessoa pode gerar um IBAN para os Estados Unidos usando um software de terceiros não confiável
Esse IBAN pode se parecer com US64SVBKUS6S3300958879
Você notará que o dígito de verificação está correto e passará pelas validações de módulo, no entanto, não é um IBAN válido, pois os Estados Unidos não usam o IBAN para pagamentos bancários.

2. Recursos


A API de validação do IBAN V4 permite que você faça o seguinte:

  • Valide se um IBAN é válido usando seus dígitos de cheque
  • Valide se um IBAN tem um código de banco doméstico válido e dígitos de verificação do número da conta *
  • Valide o comprimento do IBAN para o país específico
  • Validar a estrutura / formatação do IBAN para um país específico
  • Valide os caracteres IBAN (verifique caracteres não alfanuméricos)
  • Valide se o código do país suporta o padrão IBAN

  • Identifique o banco que emitiu o IBAN
  • Identifique o código do país e do país de um IBAN
  • Identifique o endereço do banco emitido o IBAN
  • Identifique o código BIC dos bancos
  • Identifique os bancos Suporte SEPA: B2B, COR1, SCC, SCT, SDD

* As validações de código de banco e número de conta são realizadas apenas para determinados bancos e países.

3. Solicitações da API V2



O sistema de API permite automatizar a validação do IBAN por meio de uma simples solicitação HTTP GET ou POST.
Os parâmetros aceitos estão listados na tabela abaixo:

Nome do Campo Comprimento Tipo Descrição
IBAN Max 100 String O IBAN que você deseja validar.
api_key 128 String Sua chave de API pessoal.
format 5 String Formato da resposta XML e JSON suportados.

* Para obter uma chave de API, entre em contato conoscocontact@iban.com ou comprar uma assinatura em nossa página de encomenda

EXEMPLO - Valide um IBAN
Sinta-se à vontade para usar o código de exemplo abaixo para testar a API nas linguagens de programação mais comuns.

?
1
2
3
4
5
curl "https://api.iban.com/clients/api/v4/iban/" \
    -X POST \
    -d format=json \
    -d api_key=[YOUR_API_KEY] \
    -d iban=DE46500700100927353010
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?php
$curl = curl_init();
 
$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'iban'   => 'DE46500700100927353010',
];
 
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/iban/',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => $post
));
 
$output = curl_exec($curl);
$result = json_decode($output);
 
print_r($result);
 
curl_close($curl);
?>
?
1
2
3
4
5
6
7
require 'net/http'
 
uri = URI('https://api.iban.com/clients/api/v4/iban/')
 
res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","iban" => "DE46500700100927353010")
 
puts res.body
?
1
2
3
4
5
6
import requests
 
post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','iban':'DE46500700100927353010'}
 
response = requests.post('https://api.iban.com/clients/api/v4/iban/',post_data)
print(response.text)
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
use LWP::UserAgent;
 
my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/v4/iban/";
 
my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $iban = 'DE02100500000024290661';
 
 
my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');
 
my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&iban=' . $iban;
 
$req->content($post_data);
 
my $resp = $ua->request($req);
 
if ( $resp->is_success ) {
    my $message = $resp->decoded_content;
    print $message;
}

JAVA

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;
 
 
public class ibanapi {
 
    private final String USER_AGENT = "API Client/1.0";
 
    public static void main(String[] args) throws Exception {
 
        ibanapi http = new ibanapi();
 
         
        System.out.println("\nTesting API - Send API POST request");
        http.sendPost();
 
    }
 
    // HTTP POST request
    private void sendPost() throws Exception {
 
        String url = "https://api.iban.com/clients/api/v4/iban/";
        URL obj = new URL(url);
        HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
 
        //add reuqest header
        con.setRequestMethod("POST");
        con.setRequestProperty("User-Agent", USER_AGENT);
        con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");
 
        String urlParameters = "api_key=[YOUR_API_KEY]&format=json&iban=DE02100500000024290661";
 
        // Send post request
        con.setDoOutput(true);
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());
        wr.writeBytes(urlParameters);
        wr.flush();
        wr.close();
 
        int responseCode = con.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Post parameters : " + urlParameters);
        System.out.println("Response Code : " + responseCode);
 
        BufferedReader in = new BufferedReader(
        new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuffer response = new StringBuffer();
 
        while ((inputLine = in.readLine()) != null) {
            response.append(inputLine);
        }
        in.close();
 
        //print result
        System.out.println(response.toString());
 
    }
 
}

.NET

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
public static void Main(string[] args)
        {                      
            var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/v4/iban/");
  
            var postData = "api_key=[YOUR_API_KEY]";
             postData += "&format=json";
             postData += "&iban=DE02100500000024290661";
              
            var data = Encoding.ASCII.GetBytes(postData);
              
            request.Method = "POST";
            request.ContentType = "application/x-www-form-urlencoded";
            request.ContentLength = data.Length;
              
            using (var stream = request.GetRequestStream())
            {
             stream.Write(data, 0, data.Length);
            }
              
            var response = (HttpWebResponse)request.GetResponse();
              
            var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
             
            Console.WriteLine(responseString);
             
            Console.Write("Press any key to continue . . . ");
            Console.ReadKey(true);
        }

NODE

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
var request = require('request');
 
var headers = {
    'User-Agent':       'IBAN API Client/0.0.1',
    'Content-Type':     'application/x-www-form-urlencoded'
}
 
var options = {
    url: 'https://api.iban.com/clients/api/v4/iban/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'iban': 'GB04BARC20474473160944'}
}
 
request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
      
        var data = JSON.parse(body);
 
        console.log(data.errors);
         
        console.log("Bank Name: " + data.bank_data.bank);
        console.log("Bank BIC: " + data.bank_data.bic);
        console.log("Bank City: " + data.bank_data.city);
        console.log("Bank Address: " + data.bank_data.address);
        console.log("Bank Zip: " + data.bank_data.zip);
        console.log("Bank Phone: " + data.bank_data.phone);
        console.log("Bank FAX: " + data.bank_data.fax);
        console.log("Bank www: " + data.bank_data.www);
        console.log("Bank email: " + data.bank_data.email);
        console.log("Bank Country Name: " + data.bank_data.country);
        console.log("Bank Country Code: " + data.bank_data.country_iso);
        console.log("Domestic Account Number: " + data.bank_data.account);
         
    }
})

Um exemplo de uso da API de validação do IBAN com uma solicitação GET pode ser encontrado abaixo:

https://api.iban.com/clients/api/v4/iban/?api_key=key&format=xml&iban=IBAN

Onde:
  • chave é sua chave de API
  • IBAN enviado para validação pelo módulo API.
  • xml é o formato de resposta. Além disso, uma palavra-chave json pode ser especificada para resposta formatada por json.

Quando uma solicitação HTTP GET ou POST é feita com a chave de API correta, o sistema retornará os resultados no formato especificado. Você pode encontrar uma resposta de amostra na próxima seção Estrutura de resposta da API

4. Resposta API V2

Um esquema XSD da resposta da API pode ser encontrado abaixo:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
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
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementformdefault="qualified" attributeformdefault="unqualified">
<xs:element name="result">
<xs:complextype>
     <xs:sequence>
           <xs:element name="bank_data">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="bic" type="xs:string"></xs:element>
                             <xs:element name="branch"></xs:element>
                             <xs:element name="bank" type="xs:string"></xs:element>
                             <xs:element name="address"></xs:element>
                             <xs:element name="city" type="xs:string"></xs:element>
                             <xs:element name="state"></xs:element>
                             <xs:element name="zip" type="xs:int"></xs:element>
                             <xs:element name="phone"></xs:element>
                             <xs:element name="fax"></xs:element>
                             <xs:element name="www"></xs:element>
                             <xs:element name="email"></xs:element>
                             <xs:element name="country" type="xs:string"></xs:element>
                             <xs:element name="country_iso" type="xs:string"></xs:element>
                             <xs:element name="account" type="xs:int"></xs:element>
                             <xs:element name="bank_code" type="xs:int"></xs:element>
                             <xs:element name="branch_code"></xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="sepa_data">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="SCT" type="xs:string"></xs:element>
                             <xs:element name="SDD" type="xs:string"></xs:element>
                             <xs:element name="COR1" type="xs:string"></xs:element>
                             <xs:element name="B2B" type="xs:string"></xs:element>
                             <xs:element name="SCC" type="xs:string"></xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="validations">
                 <xs:complextype>
                       <xs:sequence>
                             <xs:element name="chars">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="iban">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="account">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="structure">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="length">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                             <xs:element name="country_support">
                                   <xs:complextype>
                                         <xs:sequence>
                                               <xs:element name="code" type="xs:int"></xs:element>
                                               <xs:element name="message" type="xs:string"></xs:element>
                                         </xs:sequence>
                                   </xs:complextype>
                             </xs:element>
                       </xs:sequence>
                 </xs:complextype>
           </xs:element>
           <xs:element name="errors"></xs:element>
     </xs:sequence>
</xs:complextype>
</xs:element>
</xs:schema>
Uma descrição dos campos do objeto bank_data retornados pode ser visto na tabela abaixo:

Nome do Campo Comprimento Tipo Descrição
BIC Max 11 String O código BIC do banco emissor / agência ou instituição.
BANK Max 256 String O nome do banco / instituição que emitiu o IBAN
BRANCH Max 256 String Nome da agência bancária específica, se disponível
COUNTRY Max 32 String Nome completo do país de origem, por exemplo “EUA”
COUNTRY_ISO 2 String Abreviação de duas letras do código do país, por exemplo, EUA, Reino Unido, AU, FR, etc.
CITY Max 128 String O nome da cidade do local dos bancos emissores.
STATE Max 128 String O nome do estado no qual o banco / filial está localizado.
ZIP Max 11 String CEP ou código postal da cidade.
ADDRESS Max 128 String O endereço do banco emissor.
ACCOUNT Max 128 String O número da conta bancária interna extraído do IBAN.
Uma descrição detalhada dos campos de objetos sepa_data retornados pode ser vista na tabela abaixo:

Nome do Campo Comprimento Tipo Descrição
SCT Max 3 String Se este banco suporta transferência de crédito SEPA.
SDD Max 3 String Se este banco suporta o Débito Direto SEPA.
COR1 Max 3 String Se este banco suporta o SEPA COR1.
B2B Max 3 String Se este banco apoia o SEPA Business to Business.
SCC Max 3 String Se este banco suporta a compensação de cartões SEPA.


Uma amostra de resposta XML da API para uma consulta de validação do IBAN seria:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<result>
    <bank_data>
        <bic>BARCGB22</bic>
        <branch>INTERNATIONAL BANKING 2</branch>
        <bank>BARCLAYS BANK UK PLC</bank>
        <address>PO Box 69999 1 Churchill Place Canary Wharf </address>
        <city>London</city>
        <state>
        <zip>E14 1QE</zip>
        <phone>020 71147000</phone>
        <fax>
        <www>
        <email>
        <country>
        <country_iso>GB</country_iso>
        <account>73160944</account>
    </country></email></www></fax></state></bank_data>
    <sepa_data>
        <sct>YES</sct>
        <sdd>YES</sdd>
        <cor1>YES</cor1>
        <b2b>YES</b2b>
        <scc>NO</scc>
    </sepa_data>
    <validations>
        <chars>
            <code>006</code>
            <message>IBAN does not contain illegal characters</message>
        </chars>
        <iban>
            <code>001</code>
            <message>IBAN Check digit is correct</message>
        </iban>
        <account>
            <code>002</code>
            <message>Account Number check digit is correct</message>
        </account>
        <structure>
            <code>005</code>
            <message>IBAN structure is correct</message>
        </structure>
        <length>
            <code>003</code>
            <message>IBAN Length is correct</message>
        </length>
        <country_support>
            <code>007</code>
            <message>Country supports IBAN standard</message>
        </country_support>
    </validations>
    <errors>
</errors></result>

5. Códigos de Status da API V2

As validações matemáticas dos dígitos de verificação são retornadas no objeto "validações"

Código de status Tipo Descrição
301 Erro na conta A chave da API é inválida
302 Erro na conta Assinatura expirada
303 Erro na conta Nenhuma consulta disponível
304 Erro na conta Você não tem acesso a esta API
201 Falha na validação O dígito de verificação do número da conta não está correto
202 Falha na validação IBAN Dígito de verificação incorreto
203 Falha na validação IBAN Comprimento is not correct
205 Falha na validação A estrutura do IBAN não está correta
206 Falha na validação IBAN contém caracteres ilegais
207 Falha na validação O país não suporta o padrão IBAN
001 Sucesso de Validação O dígito de verificação do IBAN está correto
002 Sucesso de Validação O dígito de verificação do número da conta está correto
003 Sucesso de Validação IBAN Comprimento está correto
004 Sucesso de Validação O número da conta não suporta o dígito de verificação
005 Sucesso de Validação A estrutura do IBAN está correta
006 Sucesso de Validação O IBAN não contém caracteres ilegais
007 Sucesso de Validação País suporta padrão IBAN