Documentación del API de validación de IBAN V4

Este API es parte de nuestro servicio IBAN Suite

1. ¿Qué hay de nuevo en el API de validación de IBAN V4?


Trabajamos constantemente para mejorar nuestros servicios y proporcionar mejores soluciones de validación de pagos.
Tal vez haya notado que el API de IBAN Suite saltó una versión pasando de V2 a V4.
Esto ocurre porque unimos los demás API como el de SortWare v3 en una sola iteración de versiones, la v4.

Registro de cambios (de v2 a v4):


Se añadió una nueva validación (error 206). El API V4 ahora comprueba la presencia de caracteres ilegales en la entrada de IBAN.
El nuevo código de error 206 (validación fallida) con el mensaje: el IBAN contiene caracteres ilegales.
Este código de error le dará más información en el caso de que envíe a nuestro sistema un IBAN con caracteres no alfanuméricos..
El comportamiento anterior era eliminar todos los caracteres no alfanuméricos y realizar la validación

Se añadió una nueva validación (error 207). El país no admite el uso de IBAN
Esta capa de validación informará si el código de país del IBAN enviado no es parte de los países que oficialmente admiten los pagos con IBAN.
Por ejemplo, una persona puede generar un IBAN para los Estados Unidos usando un software de terceros de poca fiabilidad.
Dicho IBAN puede verse así US64SVBKUS6S3300958879
Notará que el dígito de verificación es correcto y que pasará las validaciones de módulo, pero no es un IBAN válido ya que en Estados Unidos no se usa IBAN para pagos bancarios.


2. Características


El API de validación de IBAN V4 le permite hacer lo siguiente:

  • Validar si un IBAN es válido utilizando sus dígitos de verificación
  • Validar si un IBAN tiene dígitos de verificación válidos para el código bancario y el número de cuenta*
  • Validar la longitud de un IBAN para un país específico
  • Validar la estructura y el formato de un IBAN para un país específico
  • Validar IBAN characters ( check for non-alphanumeric characters )
  • Validar si el país admite el estándar IBAN

  • Identificar el banco que emitió el IBAN
  • Identificar el país y el código de país de un IBAN
  • Identificar la dirección del banco que emitió el IBAN
  • Identificar el código BIC del banco
  • Identificar la compatibilidad del banco con la SEPA: B2B, COR1, SCC, SCT, SDD

* Validaciones de número de cuenta y código bancario solo para ciertos bancos y países.

3. Solicitudes de API V2



El sistema API le permite automatizar la validación de IBAN mediante una simple solicitud HTTP GET o POST.
En la siguiente tabla se enumeran los parámetros aceptados:

Nombre del campo Longitud Tipo Descripción
IBAN Max 100 Cadena El IBAN que desea validar.
api_key 128 Cadena Su llave API personal.
format 5 Cadena Formato de la respuesta XML y JSON admitida.

*Para obtener una llave API, póngase en contacto con nosotros mediante contact@iban.com o compre una suscripción en nuestra página de pedidos

EJEMPLO: validación de un IBAN
No dude en usar el código de muestra a continuación para probar el API en los lenguajes de programación más comunes.

curl "https://api.iban.com/clients/api/v4/iban/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d iban=DE46500700100927353010
<?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);
?>
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
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)
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

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

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

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);
		
    }
})


A continuación puede encontrar un ejemplo de uso del API de validación de IBAN con una solicitud GET:

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

En donde:
  • key es su llave API
  • IBAN enviado para su validación por el módulo API.
  • xml es el formato de respuesta. También se puede especificar una palabra clave json para obtener una respuesta formateada en json.

Una vez que se realiza una petición HTTP GET o POST con la clave API correcta, el sistema devolverá los resultados en el formato especificado. Puede encontrar una respuesta de ejemplo en la siguiente sección "Estructura de respuesta del API".

4. Respuesta del API V2

A continuación se muestra un esquema XSD de la respuesta del API:


  
    
      
        
          
            
              
              
              
              
              
              
              
              
              
              
              
              
              
              
            
          
        
        
          
            
              
              
              
              
              
            
          
        
        
          
            
              
                
                  
                    
                    
                  
                
              
              
                
                  
                    
                    
                  
                
              
              
                
                  
                    
                    
                  
                
              
              
                
                  
                    
                    
                  
                
              
              
                
                  
                    
                    
                  
                
              
              
                
                  
                    
                    
                  
                
              
            
          
        
        
      
    
  

En la siguiente tabla puede ver una descripción detallada de los campos de objeto bank_data devueltos:

Nombre del campo Longitud Tipo Descripción
BIC Max 11 Cadena Código BIC de la sucursal, el banco o la institución emisora.
BANK Max 256 Cadena Nombre del banco o la institución que emitió el IBAN.
BRANCH Max 256 Cadena Nombre de la sucursal específica del banco si está disponible.
COUNTRY Max 32 Cadena Nombre completo del país de origen. Por ejemplo: "Estados Unidos".
COUNTRY_ISO 2 Cadena Abreviatura de dos letras del código de país. Por ejemplo: US, UK, AU, FR, etc.
CITY Max 128 Cadena Nombre de la ciudad de la ubicación del banco emisor.
STATE Max 128 Cadena Nombre del estado en el que se ubica el banco o la sucursal.
ZIP Max 11 Cadena Código postal de la ciudad.
ADDRESS Max 128 Cadena Dirección del banco emisor.
ACCOUNT Max 128 Cadena Número de cuenta local extraido del IBAN.
En la siguiente tabla puede ver una descripción detallada de los campos de objeto sepa_data devueltos:

Nombre del campo Longitud Tipo Descripción
SCT Max 3 Cadena Compatibilidad de este banco con SEPA Credit Transfer.
SDD Max 3 Cadena Compatibilidad de este banco con SEPA Direct Debit.
COR1 Max 3 Cadena Compatibilidad de este banco con SEPA COR1.
B2B Max 3 Cadena Compatibilidad de este banco con SEPA Business to Business.
SCC Max 3 Cadena Compatibilidad de este banco con SEPA Card Clearing.


A continuación puede ver una respuesta XML de ejemplo para una solicitud realizada al API de validación de IBAN:

	
		BARCGB22
		INTERNATIONAL BANKING 2
		BARCLAYS BANK UK PLC
		
PO Box 69999 1 Churchill Place Canary Wharf
London E14 1QE 020 71147000 GB 73160944
YES YES YES YES NO 006 IBAN does not contain illegal characters 001 IBAN Check digit is correct 002 Account Number check digit is correct 005 IBAN structure is correct 003 IBAN Length is correct 007 Country supports IBAN standard

5. Códigos de estado del API V2

Las validaciones matemáticas de dígitos de verificación se devuelven en el objeto "validations"

Código de estado Tipo Descripción
301 Error de cuenta Llave API inválida
302 Error de cuenta Suscripción expirada
303 Error de cuenta No hay consultas disponibles
304 Error de cuenta No tiene acceso a este API
201 Validación fallida El dígito de verificación del número de cuenta no es correcto
202 Validación fallida El dígito de verificación del IBAN no es correcto
203 Validación fallida La longitud del IBAN no es correcta
205 Validación fallida La estructura del IBAN no es correcta
206 Validación fallida El IBAN contiene caracteres ilegales
207 Validación fallida El país no es compatible con el estándar IBAN
001 Validación correcta El dígito de verificación del IBAN es correcto
002 Validación correcta El dígito de verificación del número de cuenta es correcto
003 Validación correcta La longitud del IBAN es correcta
004 Validación correcta El número de cuenta no admite los dígitos de verificación
005 Validación correcta La estructura del IBAN es correcta
006 Validación correcta IBAN no contiene caracteres ilegales
007 Validación correcta País admite el estándar IBAN