Bank Verification

Endpoint Overview

POST /api/v1/bank-verification/

Description

The Bank Verification API enables you to validate bank account details by providing an account number and IFSC code. This API verifies the existence of a bank account and returns comprehensive information about the account holder and bank branch. It helps prevent fraud, reduce payment failures, and ensure accurate financial transactions by confirming that the recipient's bank details are valid before initiating transfers.

Key Benefits

Instantly verify bank account existence and validity

Reduce failed transactions and associated costs

Prevent fraud by confirming account holder details

Access comprehensive bank branch information including IFSC, MICR, and supported payment methods

Use Cases

Financial Services

E-commerce

HR & Payroll

Verify customer bank accounts during onboarding

Validate payee details before processing payments

Confirm account details for recurring payment setup

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.io

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

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for authentication (JWT)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
id_number	String	Yes	ID Number (account number) to verify
ifsc	String	Yes	IFSC code of the bank branch
ifsc_details	Boolean	No	Set to true to receive detailed IFSC information

Example Request

{
  "id_number": "219101000000000",
  "ifsc": "BARB0DAMOHA",
  "ifsc_details": true
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the verification results
data.client_id	String	Unique identifier for the verification request
data.account_exists	Boolean	Indicates if the account exists (true/false)
data.upi_id	String	UPI ID associated with the account (if available)
data.full_name	String	Full name of the account holder
data.imps_ref_no	String	IMPS reference number for the verification
data.remarks	String	Additional remarks about the account
data.status	String	Verification status (see status codes below)
data.ifsc_details	Object	Detailed information about the bank branch (if requested)
status_code	Integer	HTTP status code
success	Boolean	Overall API call success indicator
message	String	Additional message (if any)
message_code	String	Message code for the response

Status Codes

success: Verification completed successfully

invalid_ifsc: The provided IFSC code is invalid

invalid_account: The provided account number is invalid

nre_account: The account is an NRE (Non-Resident External) account

account_closed: The account has been closed

account_blocked_frozen: The account is blocked or frozen

imps_not_enabled: IMPS is not enabled for this account

backend_down: The banking backend system is currently unavailable

transaction_failed: The verification transaction failed

Example Successful Response

{
  "data": {
    "client_id": "bank_validation_pjTDReiGjNBputtmJIGC",
    "account_exists": true,
    "upi_id": null,
    "full_name": "A YADAV",
    "imps_ref_no": "506026134771",
    "remarks": "",
    "status": "success",
    "ifsc_details": {
      "id": 0,
      "ifsc": "CNRB0000000",
      "micr": "123456789",
      "iso3166": "IN-UP",
      "swift": null,
      "bank": "C Bank",
      "bank_code": "CNRB",
      "bank_name": "C Bank",
      "branch": "AGRA",
      "centre": "AGRA",
      "district": "AGRA",
      "state": "UTTAR PRADESH",
      "city": "AGRA",
      "address": "AAGRA (UP",
      "contact": "+911234567890",
      "imps": true,
      "rtgs": true,
      "neft": true,
      "upi": true,
      "micr_check": true
    }
  },
  "status_code": 200,
  "success": true,
  "message": null,
  "message_code": "success"
}

Possible Error Responses

Invalid IFSC

Backend Down

{
    "status_code": 422,
    "success": false,
    "message": "Invalid IFSC Code.",
    "message_code": "invalid_ifsc"
}

The IFSC code provided does not exist or is incorrectly formatted.

Integration Best Practices

Security Recommendations

Store API keys securely and never expose them in client-side code

Implement proper error handling to avoid exposing sensitive information

Use HTTPS for all API communications

Rotate JWT tokens periodically and implement token expiration

User Experience Guidelines

Implement proper validation for account numbers and IFSC codes before making API calls

Display clear error messages to users when verification fails

Implement retry logic with exponential backoff for temporary failures

Cache IFSC details to reduce redundant API calls for the same bank branch

Code Samples

cURL

Python

Node.js

Related APIs

KYC Verification API: Verify identity documents and perform KYC checks

PAN Verification API: Verify PAN card details and status

Aadhaar Verification API: Verify Aadhaar card details with OTP authentication

Compliance and Legal Considerations

This API handles sensitive financial information and must be used in compliance with RBI guidelines and data protection regulations. Ensure you have proper consent from users before verifying their bank account details. The data received should be handled securely and in accordance with privacy laws.

Sandbox Testing

For testing in the sandbox environment, use the following predefined account numbers and IFSC codes:

Status	Account Number	IFSC Code	Name
Success	919010015323374	UTIB0002381	MAYANK KUMAR
	003493618712	KKBK0000146	GANESH SINGH
	520121240890827	CNRB0002481	AJAY YADAV
	063213001042243	IBKL0000297	ANKIT
Invalid IFSC	520191028757481	CORO0001746
Backend Down	31944251744	SBIN1000513

These test credentials allow you to simulate different response scenarios without interacting with actual bank systems.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/bank-verification/' \ --header 'Content-Type: application/json' \ --data-raw '{ "id_number": "219101000000000", "ifsc": "BARB0DAMOHA", "ifsc_details": true }'

{ "data": { "client_id": "bank_validation_pjTDReiGjNBputtmJIGC", "account_exists": true, "upi_id": null, "full_name": "A YADAV", "imps_ref_no": "506026134771", "remarks": "", "status": "success", "ifsc_details": { "id": 0, "ifsc": "CNRB0000000", "micr": "123456789", "iso3166": "IN-UP", "swift": null, "bank": "C Bank", "bank_code": "CNRB", "bank_name": "C Bank", "branch": "AGRA", "centre": "AGRA", "district": "AGRA", "state": "UTTAR PRADESH", "city": "AGRA", "address": "AAGRA (UP", "contact": "+911234567890", "imps": true, "rtgs": true, "neft": true, "upi": true, "micr_check": true } }, "status_code": 200, "success": true, "message": null, "message_code": "success" }

Bank Verification

Bank Verification#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Status Codes#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Sandbox Testing#

Request

Responses

Bank Verification

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Status Codes

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples

Sandbox Testing