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.
| Item | What it is | Published example |
|---|---|---|
| Public source IPs | The 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 URLs | Your 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 certificate | The 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 certificate | A 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 request | A CSR the bank signs, instead of you buying a certificate. | Axis's portal lets developers key in the UAT IP and a CSR. |
| Commercial paperwork | Agreement, technical setup sheet, board resolution. | ICICI's setup sheet (CAS form), YES Bank's API setup sheet and board resolution. |
| Test sign-off | A 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.
- 1SandboxSign up on the developer portal and try the APIs in a sandbox.
- 2Agreement 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.
- 3UAT credentialsThe bank whitelists your UAT IPs, installs your certificates, and issues UAT keys.
- 4UAT testing and sign-offYou run the agreed test cases and record the results. ICICI's flow uses a UAT sign-off sheet.
- 5Production setupThe bank whitelists your production IPs, moves the configuration to production, and issues live keys.
- 6Go-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.
| Option | Fits when | Watch out for |
|---|---|---|
| VM with a static or elastic IP | Your 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 gateway | Your 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-on | Your 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 proxy | You 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.
# 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; doneCertificates 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.
# 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 -enddateUse 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.
# 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());# pip install requests (urllib3 1.26+ for an https:// proxy URL)
import os
import requests
proxy = os.environ["FIXEDMARK_PROXY_URL"]
res = requests.post(
"https://apigw-uat.bank.example/v1/payments",
json=envelope,
# The client certificate is presented to the bank inside the tunnel.
cert=("/run/secrets/bank-client.crt", "/run/secrets/bank-client.key"),
proxies={"https": proxy},
timeout=30,
)
print(res.status_code, 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.
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
fixedmarkdand 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.
Sources
Checked November 2026. Confirm current details on the vendor's site before you decide. Prices and limits change.
- Axis Bank: BBPS agent institution pre-requisite form (PDF)
- Axis Bank: API banking solutions launch, October 2021
- HDFC Bank API Portal: How do I create an application
- HDFC Bank API Portal: FAQs
- HDFC Bank API Portal: Get started
- ICICI Bank: Trade APIs
- ICICI eCollection integration spec (third-party hosted copy, PDF)
- Open: ICICI account linking flow
- Open: HDFC account linking flow
- Open: YES Bank account linking flow
- OpenSSL: openssl-req manual
- undici: ProxyAgent
- Atlar: Host-to-host connectivity
- Axis Bank: Host to Host Integration

