Overview

Everything you need to call BankPay's Provider APIs from your own systems.

All Provider APIs are reached under a common base URL and share the same authentication scheme (see Authentication below). Each API is documented as its own section further down this page - start with BIN Checker, the first API available on this platform.

Response envelope

Every endpoint returns JSON with at least a success/Success boolean and a message field. Field names are returned exactly as documented per endpoint below - note that some fields use PascalCase and some use lowerCamelCase depending on the endpoint; match the casing shown in each response example rather than assuming one convention throughout.

Authentication

Shared by every Provider API on this platform - API Key + HMAC-SHA256 request signing.

Each request must include three headers. There is no session/cookie auth and no OAuth flow - every single request is independently signed.

How to compute the signature

Build this exact string (four parts joined by newline characters), then HMAC-SHA256 it with your API secret:

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY}

Sample code

Each sample signs and sends a BIN Checker request. Replace the placeholder key/secret with your own.

API_KEY="pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
API_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

METHOD="POST"
PATH="/api/ProviderAPI/bincheck"
TIMESTAMP=$(date +%s)
BODY='{"bin":"411111","latitude":"12.9716","longitude":"77.5946"}'

MESSAGE="${METHOD}
${PATH}
${TIMESTAMP}
${BODY}"

SIGNATURE=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')

curl -X POST "https://bank-pay.in${PATH}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ${API_KEY}" \
  -H "X-Timestamp: ${TIMESTAMP}" \
  -H "X-Signature: ${SIGNATURE}" \
  --data-raw "$BODY"

// Node.js (server-side only - never run signing code like this in a browser,
// it would expose your API secret to anyone viewing the page).
const crypto = require("crypto");
const https = require("https");

const apiKey = "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const apiSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

const method = "POST";
const path = "/api/ProviderAPI/bincheck";
const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ bin: "411111", latitude: "12.9716", longitude: "77.5946" });

const message = `${method}\n${path}\n${timestamp}\n${body}`;
const signature = crypto.createHmac("sha256", apiSecret).update(message).digest("hex");

const options = {
    hostname: "bank-pay.in",
    path,
    method,
    headers: {
        "Content-Type": "application/json",
        "Content-Length": Buffer.byteLength(body),
        "X-Api-Key": apiKey,
        "X-Timestamp": timestamp,
        "X-Signature": signature,
    },
};

const req = https.request(options, (res) => {
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => console.log(res.statusCode, data));
});
req.write(body); // same "body" string used for signing above
req.end();

import hmac, hashlib, time, json, requests

api_key = "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
api_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

method = "POST"
path = "/api/ProviderAPI/bincheck"
timestamp = str(int(time.time()))
body = json.dumps({"bin": "411111", "latitude": "12.9716", "longitude": "77.5946"})

message = f"{method}\n{path}\n{timestamp}\n{body}"
signature = hmac.new(api_secret.encode(), message.encode(), hashlib.sha256).hexdigest()

headers = {
    "Content-Type": "application/json",
    "X-Api-Key": api_key,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
}

# Use data=body (the exact signed string), NOT json=... - "json=" would let
# requests re-serialize the dict itself, which may not match what you signed.
resp = requests.post("https://bank-pay.in" + path, data=body, headers=headers)
print(resp.status_code, resp.json())

using System;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string apiKey = "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
        string apiSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

        string method = "POST";
        string path = "/api/ProviderAPI/bincheck";
        string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
        string body = "{\"bin\":\"411111\",\"latitude\":\"12.9716\",\"longitude\":\"77.5946\"}";

        string message = $"{method}\n{path}\n{timestamp}\n{body}";
        string signature;
        using (var hmacsha = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))
        {
            byte[] hash = hmacsha.ComputeHash(Encoding.UTF8.GetBytes(message));
            signature = BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
        }

        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
            client.DefaultRequestHeaders.Add("X-Timestamp", timestamp);
            client.DefaultRequestHeaders.Add("X-Signature", signature);

            // Same "body" string used for signing above - not rebuilt here.
            var content = new StringContent(body, Encoding.UTF8, "application/json");
            var response = await client.PostAsync("https://bank-pay.in" + path, content);
            string responseBody = await response.Content.ReadAsStringAsync();
            Console.WriteLine((int)response.StatusCode + " " + responseBody);
        }
    }
}

Error Handling

How failures are reported, and why some "failures" come back as HTTP 200.

Business-level outcomes (like "this BIN could not be identified") are not the same as request errors (like "this signature is invalid"). BankPay's Provider APIs distinguish the two on purpose:

IP Allowlisting Required

Every key must have at least one server IP registered before it can be used.

Your API key does not work from any IP until at least one of your server IP address(es) is registered against your account - single IPs or CIDR ranges (e.g. 203.0.113.0/24) are both supported, up to a maximum of 2 active entries per account. Add your own IP(s) from "API Credentials" in your retailer portal at the same time you generate your key (or ask your BankPay contact to add them for you, if you'd rather). Any request from an IP that isn't on your account's list is rejected with 403 Forbidden, even with a valid key and signature.

Test Mode

Integrate and test error handling before you ever touch the live upstream provider.

Every API key is issued as either Live (prefixed pk_live_) or Test (prefixed pk_test_). Generate a test key the same way you'd generate a live one, from "API Credentials" in your retailer portal - a test key still requires an existing retailer account; there is no anonymous or self-serve sandbox access without one. Live and Test access are enabled independently per API product - the Test key button only appears once you've been enabled for Test mode on at least one product, same for Live.

A test key goes through the exact same authentication and IP allowlist checks as a live key - the same request signing described in Authentication, and the same registered IP(s) from IP Allowlisting (the allowlist is keyed to your account, not to a specific key, so one registered IP covers both your live and test keys). Field validation (e.g. bin format, latitude/longitude range) is enforced identically too.

What's different: a test-key call never reaches the real upstream provider and is never charged - it returns a canned response based on the bin you send, so you can exercise both the success and the "not found" paths deterministically:

BIN Checker Live

Look up issuer and card details for a card BIN.

POST/api/ProviderAPI/bincheck

Request body

{
  "bin": "411111",
  "latitude": "12.9716",
  "longitude": "77.5946"
}

Response fields

Field names below are returned exactly as shown - note the mix of PascalCase and lowerCamelCase.

{
  "Success": true,
  "Message": null,
  "RequestId": "PBC0000000123",
  "BankName": "HDFC Bank",
  "CardNetwork": "VISA",
  "ChargeAmount": 0.50,
  "bin": "411111",
  "cardType": "Credit",
  "cardLevel": "Platinum",
  "isoCountryName": "India",
  "isoCountryA2": "IN",
  "issuerBank": "HDFC Bank",
  "issuerWebsite": "https://www.hdfcbank.com",
  "issuerPhone": "1800-xxx-xxxx",
  "cardTransfer": "..."
}

{
  "Success": false,
  "Message": "BIN not found or could not be verified.",
  "RequestId": "PBC0000000124",
  "BankName": null,
  "CardNetwork": null,
  "ChargeAmount": null
}

{
  "Success": false,
  "Message": "\"bin\" must be exactly 6 numeric digits."
}

More APIs Coming soon

Additional provider APIs will be documented here as they become available, using the same authentication, error handling, and billing model described above.