IBAN Verification API

Endpoint Overview

POST /api/v1/iban/iban-verify

Description

The IBAN Verification API provides real-time validation and detailed information extraction for International Bank Account Numbers (IBANs). This endpoint validates the structural integrity of an IBAN, extracts banking details, and provides comprehensive account information including bank name, country code, and account components. The API supports IBANs from all participating countries in the IBAN registry and returns standardized, structured data that can be seamlessly integrated into financial applications, compliance systems, and customer onboarding workflows.

Key Benefits

Real-time IBAN validation with instant structural and checksum verification

Comprehensive bank data extraction including bank name, codes, and account details

Global coverage supporting all IBAN-participating countries and territories

Developer-friendly integration with clear JSON responses and robust error handling

Use Cases

Financial Services

E-commerce & Fintech

Enterprise & B2B

Payment processing validation to prevent failed transactions due to invalid IBANs

Customer onboarding with automated bank account verification during registration

Compliance checks for anti-money laundering (AML) and know-your-customer (KYC) procedures

Cross-border payment validation for international wire transfers and remittances

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication (JWT format)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
id_number	string	Yes	The IBAN to be verified and validated (should include country code and complete IBAN structure)

Example Request

{
    "id_number": "ES7921000813610123412345"
}

Process Response

Response Parameters

Parameter	Type	Description
data.client_id	string	Unique identifier for this verification request
data.id_number	string	The original IBAN that was verified
data.bank_name	string	Full name of the bank associated with the IBAN
data.account_number	string	Extracted account number portion from the IBAN
data.bank_code	string	Bank identifier code extracted from the IBAN
data.country	string	ISO 3166-1 alpha-2 country code of the IBAN
data.checksum	string	Check digits used for IBAN validation
data.valid	boolean	Indicates whether the IBAN is structurally valid and passes checksum validation
data.bban	string	Basic Bank Account Number (BBAN) - the domestic account identifier
status_code	integer	HTTP status code of the response
success	boolean	Indicates whether the API call was successful
message	string	Human-readable message describing the result
message_code	string	Machine-readable code for the response status

Example Successful Response

{
    "data": {
        "client_id": "iban_verify_gysYNjNlfikaywbvVebu",
        "id_number": "ES7921000813610123412345",
        "bank_name": "CAIXABANK, S.A.",
        "account_number": "600123499999",
        "bank_code": "2000",
        "country": "ES",
        "checksum": "79",
        "valid": true,
        "bban": "210008132324343456789"
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Server Error

{
  "data": null,
  "status_code": 401,
  "success": false,
  "message": "Invalid or expired token",
  "message_code": "unauthorized"
}

Authentication failed due to invalid or missing JWT token.

Integration Best Practices

Security Recommendations

Secure token storage: Store JWT tokens securely and never expose them in client-side code or logs

Token rotation: Implement regular token refresh cycles and handle token expiration gracefully

HTTPS enforcement: Always use HTTPS for API communications to protect sensitive banking data

Input validation: Validate and sanitize IBAN inputs before sending to the API

Error handling: Implement proper error handling to avoid exposing sensitive information in error messages

User Experience Guidelines

Real-time validation: Provide immediate feedback to users as they enter IBAN information

Clear error messages: Display user-friendly error messages when IBAN validation fails

Progressive disclosure: Show additional bank details only after successful validation

Accessibility: Ensure IBAN input fields are properly labeled and accessible to screen readers

Mobile optimization: Design IBAN input interfaces that work well on mobile devices with appropriate keyboards

Code Samples

cURL

Python

Node.js

Related APIs

PAN Verification API - Verify Indian Permanent Account Numbers for tax compliance and identity verification
Aadhaar Verification API - Validate Indian Aadhaar numbers for comprehensive identity verification
Bank Account Verification API - Verify domestic bank account details and account holder information
GST Verification API - Validate Indian GST registration numbers for business verification
Driving License Verification API - Verify driving license details for identity and address confirmation

Compliance and Legal Considerations

Data Privacy: This API processes sensitive financial information. Ensure compliance with applicable data protection regulations (GDPR, PCI DSS, etc.) when handling IBAN data. Banking Regulations: IBAN verification should be used as part of broader compliance procedures and not as the sole method for account validation. Data Retention: Consider implementing appropriate data retention and deletion policies for verification logs and cached results. Cross-border Compliance: When processing IBANs from different countries, be aware of varying national banking regulations and data localization requirements. Audit Trail: Maintain proper audit logs for verification requests to support compliance reporting and investigations.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/iban/iban-verify' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "ES7921000813610123412345" }'

{ "data": { "client_id": "iban_verify_gysYNjNlfikaywbvVebu", "id_number": "ES7921000813610123412345", "bank_name": "CAIXABANK, S.A.", "account_number": "600123499999", "bank_code": "2000", "country": "ES", "checksum": "79", "valid": true, "bban": "210008132324343456789" }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

IBAN Verify

IBAN Verification API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses