Skip to content
Fixedmark

Payments and India APIs · 11 min read

Updated

Bank API Onboarding in India: IPs and Certificates

Indian corporate banking APIs usually ask for your public server IPs for UAT and production, a client SSL certificate for two-way TLS, a public certificate for payload encryption, and signed account paperwork. The IP step stalls go-live when you cannot name a fixed address, so settle your egress IPs before you open the onboarding form.

On this page

What the bank asks for

Every bank has its own forms, and they change by product. Payouts, collections, statements, and trade APIs at the same bank can each have a different checklist. Still, the published material from ICICI, Axis, HDFC, and YES Bank shows the same core items. The Bank and UPI APIs page covers why banks filter by source IP at all. This post covers the full onboarding pack and the order it happens in.

Items Indian bank API onboarding commonly asks for
ItemWhat it isPublished example
Public source IPsThe IPv4 addresses your servers call the bank from, for UAT and for production.Axis's BBPS pre-requisite form has a row for Client Public IP to be whitelisted. HDFC's app form makes the IP field mandatory.
Ports and URLsYour callback or back-end URL, and the IP and port behind it, for both environments.An ICICI eCollection spec asks for an HTTPS back-end URL and the IP and port for LIVE and UAT.
Client SSL certificateThe certificate your client presents in two-way TLS.Axis asks for a Client SSL certificate for handshaking. HDFC asks for the leaf certificate in the app and the chain by email.
Encryption certificateA public key the bank uses to encrypt responses to you.The ICICI eCollection spec takes a 2048 or 4096 bit public certificate, CA-signed in production.
Certificate signing requestA CSR the bank signs, instead of you buying a certificate.Axis's portal lets developers key in the UAT IP and a CSR.
Commercial paperworkAgreement, technical setup sheet, board resolution.ICICI's setup sheet (CAS form), YES Bank's API setup sheet and board resolution.
Test sign-offA record that UAT passed, before production keys are issued.ICICI's UAT sign-off sheet, then live API keys.

The sources for each row are linked below. Axis's pre-requisite form is a good example of how blunt these forms are. Its questions include the client public IP to whitelist, whether there are separate UAT and PROD environments, and which HTTPS port the API uses. HDFC's app creation guide states that the app name, API products, IP, scope, and certificate sections are all mandatory.

The order onboarding usually runs in

Self-serve portals let you try a sandbox on day one. Real money movement waits for the paperwork. HDFC's portal lets you test in a sandbox, create an app, and then request access to move to production once UAT is done. ICICI describes its Trade APIs the same way, with testing in sandbox and UAT before going live. A third-party guide to ICICI connected banking gives the fuller sequence.

  1. 1
    SandboxSign up on the developer portal and try the APIs in a sandbox.
  2. 2
    Agreement and setup sheetYour relationship manager collects the signed agreement, account details, and the technical setup sheet. This is where the bank first asks for your IPs and certificates.
  3. 3
    UAT credentialsThe bank whitelists your UAT IPs, installs your certificates, and issues UAT keys.
  4. 4
    UAT testing and sign-offYou run the agreed test cases and record the results. ICICI's flow uses a UAT sign-off sheet.
  5. 5
    Production setupThe bank whitelists your production IPs, moves the configuration to production, and issues live keys.
  6. 6
    Go-liveYou switch to live keys and production URLs and run the first real transactions.

None of the banks checked here publish a turnaround time for each step. Plan for the IP and certificate steps to go through a ticket each time, at UAT and again at production. Any change you make later goes through the same ticket.

Why the IP step stalls go-live

Most of the form is paperwork your business team can fill in. The IP row is the one an engineer has to answer, and it fails in a few predictable ways.

  • You run on serverless or a PaaS and have no fixed outbound address. Lambda, Vercel Functions, Railway, and Render share and rotate egress IPs. See why serverless egress IPs change.
  • You send a cloud provider's published range. HDFC's form accepts ranges like 10.10.10.1-10.10.10.100, but a range that covers a whole cloud region admits every other tenant in it. A bank reviewer may refuse it, and they should. See cloud IP ranges are not an allowlist.
  • Your production IP does not exist yet. The bank wants it at the setup sheet stage, often weeks before your production infrastructure is built.
  • Your app calls out over IPv6. HDFC's form says only IPv4 is allowed. If your host prefers IPv6, the bank sees an address you never registered. See IPv6 egress and IPv4-only allowlists.
  • You list one IP. When that host goes down or is replaced, every bank call fails until a new whitelist ticket closes. See static IP pairs and failover.
  • Only some of your code goes out through the fixed IP. A worker or cron job that calls the bank directly fails while the main app works.

A call from an address the bank has not whitelisted rarely returns a helpful message. If the bank filters at its network firewall, the connection simply times out. If it filters at the API gateway, you may get a generic error. Either way, confirm the IP before you chase anything else.

Settle your egress IPs before the form

Decide where bank traffic leaves your network before the setup sheet arrives. The bank does not care how you get a fixed address, only that it stays fixed and belongs to you.

Ways to give bank calls a fixed outbound IPv4 address
OptionFits whenWatch out for
VM with a static or elastic IPYour backend already runs on VMs in one place.One VM is one IP and one point of failure. You patch and monitor it.
Cloud NAT gatewayYour workloads run in a VPC on AWS, GCP, or Azure.Hourly and per-GB charges per zone. See NAT gateway hidden costs.
Platform static IP add-onYour host offers one and you stay on that host.Some are shared with other customers. The IP stays behind if you move hosts.
Static IP proxyYou run on serverless or several hosts, or may move.Only calls you route through the proxy use the fixed IP.

Whatever you choose, follow four rules. Give the bank two addresses, so one can fail without a ticket. Use addresses that only your company uses. Keep them in an Indian region if the bank's API is in India, which also keeps latency low. And plan to use the same addresses for UAT and production, listed in both rows of the form. You still keep separate credentials and certificates for each environment.

Prove the address from the real code path

Check the address the bank will see, from the same runtime and the same HTTP client your bank calls will use. A check from your laptop proves nothing. Force IPv4 so you see the address the bank will see.

Terminal
# From the server or container that will call the bank.
curl -4 https://api.ipify.org; echo

# Through the proxy your bank client will use, if you use one.
curl -4 --proxy "$HTTPS_PROXY" https://api.ipify.org; echo

# Repeat a few times. Every answer must be an address on the form.
for i in 1 2 3 4 5; do curl -s -4 --proxy "$HTTPS_PROXY" https://api.ipify.org; echo; done

Certificates and the CSR

Two different certificates often appear in the same form. One is the TLS client certificate for two-way SSL, which the bank checks during the handshake. The other is a public key the bank uses to encrypt payloads it sends back to you. The ICICI eCollection spec notes that only the public certificate is needed for that product and SSL is not, so read which one each product wants.

Some banks sign a CSR you send. Axis said in its 2021 portal launch that developers key in the UAT IP and a standard CSR on the portal. Others want a certificate signed by a public CA. HDFC's FAQ says a partner's SSL public certificate needs at least one year of validity. Generate the key on a machine you control and never send the private key to anyone.

Terminal
# Key and CSR in one step (OpenSSL 3.x; -noenc leaves the key unencrypted on disk).
openssl req -new -newkey rsa:2048 -noenc \
  -keyout bank-client.key -out bank-client.csr \
  -subj "/C=IN/ST=Maharashtra/L=Mumbai/O=Example Payments Pvt Ltd/CN=api.example.in"

# Check the CSR before you send it.
openssl req -in bank-client.csr -noout -text -verify

# When the signed certificate comes back, check subject, issuer, and expiry.
openssl x509 -in bank-client.crt -noout -subject -issuer -enddate

Use whatever key size, subject fields, and CN the bank's document asks for. The ICICI spec accepts 2048 or 4096 bit keys. Put the expiry date in a calendar with a month of notice. Renewal repeats the upload and often the ticket, and an expired client certificate stops every call as surely as a wrong IP. The OpenSSL req manual documents every flag above.

Payload encryption on top of TLS

Some Indian bank APIs, such as ICICI's eCollection, encrypt the JSON body as well as using TLS. The common pattern is hybrid encryption. You generate a one-time AES key, encrypt the payload with it, and encrypt the AES key with the bank's RSA public certificate. The bank answers the same way with your public certificate.

A copy of an ICICI eCollection integration spec shows one concrete version. Its envelope carries encryptedKey, oaepHashingAlgorithm, iv, and encryptedData. NONE in the hashing field means RSA with PKCS#1 v1.5 padding, and SHA1 means OAEP with SHA-1. The payload uses AES in CBC mode with PKCS5 padding. On responses, the IV is the first 16 bytes of the decoded encryptedData. That copy is hosted by a third party, so treat it as an example and code against the spec your bank sends you.

bank_crypto.py
# pip install cryptography
# The shape of one ICICI-style hybrid scheme. Match padding, key length,
# and IV placement to your bank's own spec before you use it.
import base64
import json
import os
import secrets
import string

from cryptography import x509
from cryptography.hazmat.primitives import padding as sym_padding
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

ALPHABET = string.ascii_letters + string.digits


def encrypt_request(payload: dict, bank_cert_pem: bytes) -> dict:
    bank_key = x509.load_pem_x509_certificate(bank_cert_pem).public_key()
    # The spec asks for a random 16-character string as the AES-128 key.
    session_key = "".join(secrets.choice(ALPHABET) for _ in range(16)).encode()
    iv = os.urandom(16)

    padder = sym_padding.PKCS7(128).padder()
    plain = padder.update(json.dumps(payload).encode()) + padder.finalize()
    encryptor = Cipher(algorithms.AES(session_key), modes.CBC(iv)).encryptor()
    cipher_text = encryptor.update(plain) + encryptor.finalize()

    return {
        "encryptedKey": base64.b64encode(
            bank_key.encrypt(session_key, padding.PKCS1v15())
        ).decode(),
        "oaepHashingAlgorithm": "NONE",
        "iv": base64.b64encode(iv).decode(),
        "encryptedData": base64.b64encode(cipher_text).decode(),
    }


def decrypt_response(body: dict, client_key_pem: bytes) -> dict:
    key = serialization.load_pem_private_key(client_key_pem, password=None)
    session_key = key.decrypt(
        base64.b64decode(body["encryptedKey"]), padding.PKCS1v15()
    )
    raw = base64.b64decode(body["encryptedData"])
    iv, cipher_text = raw[:16], raw[16:]

    decryptor = Cipher(algorithms.AES(session_key), modes.CBC(iv)).decryptor()
    padded = decryptor.update(cipher_text) + decryptor.finalize()
    unpadder = sym_padding.PKCS7(128).unpadder()
    return json.loads(unpadder.update(padded) + unpadder.finalize())

PKCS5 padding in Java's naming is PKCS#7 padding with a 16-byte block for AES, which is what the code uses. The envelope also has fields such as requestId and service that come from the bank's spec. Test against the sample request in the bank's document first. A wrong padding mode gives you a decryption error that looks like a bad key.

Two-way TLS through a fixed IP

If you route bank calls through an HTTP CONNECT proxy for the fixed IP, two-way TLS still works. The proxy opens a TCP tunnel, and your client runs the TLS handshake with the bank inside it. Your client certificate goes to the bank, not to the proxy, and the encrypted payload stays encrypted end to end. TLS passthrough and zero-knowledge proxies explains what a proxy can and cannot see.

In Node, undici's ProxyAgent takes requestTls for the connection to the destination and proxyTls for the connection to the proxy. The client certificate belongs in requestTls. In Python requests, cert= works the same with or without proxies=. Load the PEM data from secrets, not from files baked into an image.

// npm install undici
import { fetch, ProxyAgent } from "undici";

// One agent, used only for bank calls. Other traffic stays direct.
const bankAgent = new ProxyAgent({
  uri: process.env.FIXEDMARK_PROXY_URL,
  requestTls: {
    cert: process.env.BANK_CLIENT_CERT, // PEM, sent to the bank
    key: process.env.BANK_CLIENT_KEY,
  },
});

const res = await fetch("https://apigw-uat.bank.example/v1/payments", {
  method: "POST",
  dispatcher: bankAgent,
  // Add the auth headers your bank's spec names.
  headers: { "content-type": "application/json" },
  body: JSON.stringify(envelope), // the encrypted envelope from your bank's scheme
});
console.log(res.status, await res.text());

When UAT calls fail, curl -v tells you which layer broke. If the tunnel never opens, the connection to the bank failed at TCP, which points at the IP whitelist. Proxy error codes covers what the proxy reports. A handshake alert after Client hello points at the certificate. An HTTP status with a body means you reached the API and the problem is in the request.

Terminal
curl -v --proxy "$HTTPS_PROXY" \
  --cert bank-client.crt --key bank-client.key \
  https://apigw-uat.bank.example/

Callbacks, file transfer, and aggregators

The bank calls you too

Collection and payout products send notifications to a URL you host. The ICICI eCollection spec asks for an HTTPS back-end URL for LIVE and UAT, plus the IP and port when the URL is IP-based. Your server should accept those calls only from the source IPs the bank gives you, and still verify or decrypt the payload. Payment webhook source IP allowlisting and webhook receivers on private networks cover the inbound side.

Host-to-host file transfer

Bulk payment and statement files often move host-to-host instead of over a REST API. Atlar's overview calls SFTP with IP whitelisting a common type of H2H connection. Axis lists an SFTP integration kit for its host-to-host product. The same fixed-IP rule applies to the SFTP client. See SFTP allowlisting. Some banks offer a site-to-site VPN for these links instead. In that case the bank wants your VPN peer address, which has to be a real gateway you run, not a proxy.

Going through an aggregator

Connected banking platforms sit between you and the bank. Then the IPs on the bank's whitelist are the platform's, not yours. The HDFC flow from Open lists Open's own addresses to enter during app creation. The YES Bank flow needs an API setup sheet and a board resolution. You trade one bank integration for the platform's API, and the platform may whitelist your IPs in turn. The RazorpayX and Cashfree posts cover those platforms. GST e-invoicing has a similar split between direct access and a GSP, covered in e-invoice IRP API whitelisting.

Doing this with Fixedmark

Fixedmark gives your app a dedicated pair of static IPv4 addresses in its Mumbai region, and you route bank calls through one proxy URL. You put both addresses in the UAT and production rows of the setup sheet before your production stack exists. After that you can move hosts or split services without another whitelist ticket. Fixedmark is in early access. The planned launch price for a dedicated pair is $29 a month on Pro, as listed on pricing.

  • TLS passes through and is never decrypted, so your client certificate and the encrypted envelope go straight to the bank. See security.
  • Each new connection leaves from one of the two addresses, so register both. Verify your egress IP from the real runtime before you submit the form.
  • Connection logs show destination, egress IP, and result for each connection, which helps when a UAT call times out.
  • Destination allowlists can restrict a credential to the bank's API host and port, on plans that include them.
  • The trial runs on a shared IP pair. Do not register shared addresses with a bank.
  • For callbacks, tunnels give your service a hostname through fixedmarkd and admit only the source addresses you list. Tunnels are on Pro and up. If the bank must call one fixed IP of yours, the dedicated inbound IP add-on is $9 per IP-month.
Bank requirements differ by bank, product, and year. The examples here come from each bank's public pages and from third-party guides, as linked. The bank's own onboarding document and your relationship manager have the final word.

Sources

Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.

Blog

Frequently asked questions

Do UAT and production need different IPs?

None of the published forms checked here require it. Banks whitelist each environment separately, so the form has a row for each. You can list the same fixed addresses in both rows and keep separate credentials and certificates per environment.

Can I give the bank an IP range?

Some portals accept ranges. HDFC's app form takes the format `10.10.10.1-10.10.10.100`. A small range you own is fine. A cloud provider's shared range lets every other tenant through, and a careful bank will refuse it.

Should I give the bank two IPs?

Yes, if the form allows it. With one address, a failed or replaced host stops every bank call until a new whitelist ticket closes. Two addresses on separate hosts let traffic move between them with no change at the bank.

Does a proxy break two-way SSL with the bank?

An HTTP CONNECT or SOCKS5 proxy does not. It forwards the TCP stream, and your client completes the TLS handshake with the bank, client certificate included. A proxy that terminates TLS would break it, which is why bank traffic should use a passthrough proxy.

How long does bank API onboarding take?

None of the banks checked here publish a timeline. The paperwork, UAT sign-off, and each whitelist ticket run in sequence. Having fixed IPs and certificates ready when the setup sheet arrives removes the steps an engineer can delay.

Make it fixed.

Fixedmark is in early access. Join the list to get dedicated static IPs when your region opens.