Overview

The Finzep Payout API lets your system send money to a bank account (IMPS / NEFT / RTGS) or a UPI ID from your Finzep wallet, and then check what happened. Two calls do the job: POST /API/Payout (create a payout) and POST /API/Payout/Status (ask for its current status).

Every request and every answer is signed and encrypted. You never send the plain JSON on the wire:

• You create your own RSA key pair. You keep the private key and register the public key in the Finzep portal.
• Your request is encrypted for our public key (only we can read it) and signed with your private key (only you could have sent it).
• Our answer is encrypted for your public key and signed with our private key.
• You also send an API key in a header, which tells us which account you are.

Quick start

1. Log in to the Finzep portal as your API user, open API Access and click Generate key. Copy the fzp_... API key - it is shown only once.
2. Create your RSA key pair (keep the private key secret):
   node fzp-client.js keygen .  or  python fzp_client.py keygen .  or  java FzpClient.java keygen .  or  OpenSSL (see below).
3. Register the public key: in API Access, section "Encryption keys", paste client-public.pem and click Register key. You get a clientKeyId such as ck_1a2b3c4d5e6f.
4. Fetch our public key: GET /API/PublicKey returns serverKeyId and publicKeyPem. Check its fingerprint with the one shown in the portal.
5. (Optional) Whitelist your server's IP in API Access, section "IP whitelist".
6. Send a payout with one of the samples or the Postman collection, then check its status.
7. (Optional) Receive status updates by webhook: register your https URL in API Access → Webhook (see Webhooks) instead of polling.

Getting your credentials

Generate a key pair with OpenSSL if you prefer:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out client-private.pem
openssl rsa -in client-private.pem -pubout -out client-public.pem

Authentication & headers

There is no login, cookie or token exchange. If the key is missing, wrong, revoked or its owner is inactive you get 401; if your server's IP is not on your whitelist you get 403 (see Errors).

The encrypted envelope

The body of every request (and every answer) is one JSON object, the envelope. Your normal JSON is encrypted into payload:

{
  "clientKeyId": "ck_1a2b3c4d5e6f",
  "serverKeyId": "sk_9f8e7d6c5b4a",
  "timestamp": "2026-10-09T12:00:00Z",
  "nonce": "...",
  "encryptedKey": "...",
  "iv": "...",
  "payload": "<aapke plain JSON ka AES encrypted form>",
  "signature": "..."
}

i.e. payload is your plain JSON, AES-encrypted. All binary values are standard Base64.

The answer uses exactly the same envelope shape (encrypted for you, signed by us). The exact algorithm is in Encryption specification; the sample libraries do it for you.

A complete call on the wire

POST /API/Payout HTTP/1.1
Host: your-finzep-host
X-Api-Key: fzp_9d1c...e07a
X-Encrypted: 1
Content-Type: application/json

{"clientKeyId":"ck_1a2b3c4d5e6f","serverKeyId":"sk_9f8e7d6c5b4a","timestamp":"2026-10-09T12:00:00Z",
 "nonce":"c3VwZXItcmFuZG9tLTE2Ynl0ZQ==","encryptedKey":"b6Rk...(512 chars)...","iv":"mZ1xQ0ZrUjRzV1E4",
 "payload":"p0eC...(your JSON, encrypted)...Qw==","signature":"Jf9a...(512 chars)..."}

HTTP/1.1 200 OK
X-Encrypted: 1
Content-Type: application/json

{"clientKeyId":"ck_1a2b3c4d5e6f","serverKeyId":"sk_9f8e7d6c5b4a","timestamp":"2026-10-09T12:00:01Z",
 "nonce":"...","encryptedKey":"...","iv":"...","payload":"...(the answer, encrypted)...","signature":"..."}

POST /API/Payout

Creates a payout. The plain JSON you encrypt into payload:

{
  "APIRequestID": "REQ-0001",
  "TransMode": "IMPS",
  "Amount": 100.00,
  "AccountNo": "1234567890123",
  "IFSC": "HDFC0000123",
  "BeneName": "Ramesh Kumar",
  "BeneMobile": "9876543210",
  "SenderName": "Suresh Sharma",
  "SenderMobile": "9999999999",
  "SenderEmail": "sender@example.com"
}

The answer (decrypted)

{
  "success": true,
  "status": 2,
  "statusName": "Success",
  "message": "Transaction successful.",
  "apiRequestID": "REQ-0001",
  "transactionId": "S26100912242010EDA3C",
  "utr": "UTR12345678",
  "errorCode": 0,
  "referenceId": null
}

POST /API/Payout/Status

Returns the current state of one of your own payouts. Plain JSON to encrypt:

{ "APIRequestID": "REQ-0001" }

The answer has the same fields as the payout answer. For a payout that is still Pending, our server asks the bank and updates the payout, so call this to resolve a Pending payout. An unknown id gives errorCode 1001. You can only see payouts created by your own account.

GET /API/PublicKey

Public (no key, no encryption) - returns our currently active public key:

{
  "serverKeyId": "sk_9f8e7d6c5b4a",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "keyBits": 3072,
  "specification": "FZP1", "keyWrap": "RSA-OAEP-SHA256", "payload": "AES-256-GCM", "signature": "RSA-PSS-SHA256"
}

The fingerprint is the SHA-256 of the key's SubjectPublicKeyInfo, lower-case hex. Compare it with the value in the portal (API Access) before trusting a key. Fetch the key once and cache it; fetch again when we tell you the key was rotated.

Statuses & lifecycle

Recommended polling

• If the answer to /API/Payout is Pending (or you got no answer - a timeout, a network error), call /API/Payout/Status with the same APIRequestID after ~15 seconds, then every 30-60 seconds, for up to about 30 minutes.
• Never resend a payout "to be safe". Sending the same APIRequestID again is refused (code 150) and a different one could pay the beneficiary twice. Always check the status first.
• A Success or Failed payout never changes by itself afterwards. (A Success payout can still be disputed later through the portal's refund-request process - that is not part of this API.)

Webhooks

Instead of polling /API/Payout/Status, you can give us an https URL. Finzep calls it (HTTP POST) when a payout or refund changes state after your original request. Webhooks are optional, and they use the same signed + encrypted envelope as the API.

When we call you

Setup

1. You need a registered public key (API Access, section "Encryption keys") - every webhook is encrypted for your newest active public key.
2. In API Access → Webhook enter your URL (must be https, a public internet address - no localhost, no private IPs, no redirects), tick Enabled, click Save, then Send test event.
3. The list below the form shows every delivery with its status, attempts and your server's HTTP answer; View shows the payload and Resend sends an event again.

What we send

POST https://your-server.example.com/finzep/webhook
Content-Type: application/json
X-Encrypted: 1
X-Webhook-Event: payout.success
X-Webhook-Id: 0b1f6c52-3a7d-4f0e-9c1a-6f2f1d5b7a10
X-Webhook-Attempt: 1
User-Agent: Finzep-Webhook/1.0

{ "clientKeyId": "ck_1a2b3c4d5e6f", "serverKeyId": "sk_9f8e7d6c5b4a", "timestamp": "2026-10-09T12:00:00Z", "nonce": "...",
  "encryptedKey": "...", "iv": "...", "payload": "<the event JSON, AES-encrypted>", "signature": "..." }

The body is the same envelope as in the API: encrypted for your public key (clientKeyId says which one) and signed with our private key (serverKeyId). X-Webhook-Id is the event id; it is part of the signed text, so it cannot be changed.

The event (decrypted)

{
  "event": "payout.success",
  "eventId": "0b1f6c52-3a7d-4f0e-9c1a-6f2f1d5b7a10",
  "createdAt": "2026-10-09T12:00:00Z",
  "source": "admin",
  "success": true,
  "status": 2,
  "statusName": "Success",
  "message": "Transaction successful.",
  "errorCode": 0,
  "apiRequestID": "REQ-0001",
  "transactionId": "S26100912242010EDA3C",
  "utr": "UTR12345678",
  "amount": 100.00,
  "refund": null
}

For a refund event refund is filled: { "status": "Accepted", "amount": 103.00, "remark": "verified, refunding" } (amount = the charged amount credited to your wallet; null when rejected).

Verifying and decrypting

1. Read the raw body and the header X-Webhook-Id.
2. signedText = FZP1 \n WEBHOOK \n <X-Webhook-Id> \n clientKeyId \n serverKeyId \n timestamp \n nonce \n encryptedKey \n iv \n payload (joined with a single \n; the same layout as in the specification, with WEBHOOK and the event id on lines 2-3).
3. Verify signature with our public key (RSA-PSS-SHA256). Reject the call if it does not verify.
4. Decrypt exactly as for an API answer: RSA-OAEP unwraps the AES key with your private key, AES-256-GCM opens payload.
5. Optionally check that timestamp is recent (we create a fresh envelope for every attempt).

The client files in Samples already do this: openWebhook(...) (Node.js), OpenWebhook(...) (C#), open_webhook(...) (Python), openWebhook(...) (Java). Complete, tested receivers: webhook-receiver.js (Node.js), webhook_receiver.py.txt (Python), WebhookReceiver.java.txt (Java).

const { openWebhook } = require('./fzp-client');

// inside your HTTPS handler: `body` = raw request text, `req.headers['x-webhook-id']` = event id
const event = JSON.parse(openWebhook({ body, eventId: req.headers['x-webhook-id'],
                                       clientPrivateKeyPem, serverPublicKeyPem: pk.publicKeyPem }));   // throws if the signature is wrong
if (!alreadyHandled(event.eventId)) { process(event); }       // event.event, event.transactionId, event.statusName, event.utr ...
res.writeHead(200); res.end('ok');                            // any 2xx = delivered

// ASP.NET Core minimal API; `client` is the FzpClient from the Samples section
app.MapPost("/finzep/webhook", async (HttpRequest req) =>
{
    var body = await new StreamReader(req.Body).ReadToEndAsync();
    var json = client.OpenWebhook(body, req.Headers["X-Webhook-Id"]!);      // throws CryptographicException if the signature is wrong
    var evt = JsonDocument.Parse(json).RootElement;
    if (!AlreadyHandled(evt.GetProperty("eventId").GetString()!)) Process(evt);   // evt "event", "transactionId", "statusName", "utr" ...
    return Results.Ok();                                                    // any 2xx = delivered
});

from fzp_client import open_webhook
import json

# inside your HTTPS handler: `body` = raw request text, `event_id` = the X-Webhook-Id header
event = json.loads(open_webhook(body, event_id, client_private_pem, server_public_pem))   # raises if the signature is wrong
if not already_handled(event["eventId"]):
    process(event)            # event["event"], event["transactionId"], event["statusName"], event["utr"] ...
# answer HTTP 200 - any 2xx = delivered

// inside your HTTPS handler: `body` = raw request text, `eventId` = the X-Webhook-Id header
String json = FzpClient.openWebhook(body, eventId, clientPrivate, serverPublic);   // throws if the signature is wrong
String id = FzpClient.field(json, "eventId");
if (!alreadyHandled(id)) process(json);       // fields: event, transactionId, statusName, utr ...
// answer HTTP 200 - any 2xx = delivered

Your answer, retries and duplicates

• Answer HTTP 2xx within 10 seconds. Do the real work afterwards (queue it) - slow handlers time out and we retry.
• Any other answer, a timeout or a connection error is a failed attempt. We retry after 1 min, 5 min, 15 min, 1 hour, 3 hours, 6 hours (7 attempts in all), then mark the event Failed (gave up). Use Resend in the portal once your server is back. X-Webhook-Attempt tells you which attempt it is.
• Delivery is at least once: after a timeout we may deliver an event you already processed, and events can arrive out of order. Make your handler idempotent on eventId, and use statusName / transactionId to see the final state.
• We do not follow redirects. Your URL must be https on a public address; we refuse to call private or local addresses. Allow our servers' outgoing IP through your firewall (ask your account manager for the address).
• Never trust a webhook you could not verify. If in doubt, call /API/Payout/Status - it is always the source of truth.

Errors & codes

HTTP status

Payout and status codes

Encryption and access codes

Rules & limits

Encryption specification (FZP1)

Only needed if you write your own client; otherwise use the samples.

Building a request

1. json = the plain request, e.g. {"APIRequestID":"REQ-1", ...}
2. Generate aesKey (32 random bytes), iv (12), nonce (16); timestamp = now in UTC, yyyy-MM-ddTHH:mm:ssZ.
3. aad = UTF-8 of timestamp + "\n" + nonce
4. payload = Base64( AES-256-GCM-encrypt(aesKey, iv, json, aad) )  (ciphertext followed by the 16-byte tag)
5. encryptedKey = Base64( RSA-OAEP-SHA256-encrypt(our public key, aesKey) )
6. signedText = the lines below joined with a single \n (no trailing newline), each Base64 value exactly as it is sent:

   FZP1
   REQUEST
   <path, e.g. /API/Payout>
   <clientKeyId>
   <serverKeyId>
   <timestamp>
   <nonce>
   <encryptedKey>
   <iv>
   <payload>

7. signature = Base64( RSA-PSS-SHA256-sign(your private key, UTF-8(signedText)) )
8. POST the envelope with the headers from Authentication & headers.

The path is part of the signed text, so a request signed for /API/Payout/Status cannot be replayed against /API/Payout.

Webhooks use the same machinery in the other direction

A webhook envelope is built by us exactly like an answer, but its signed text has WEBHOOK on line 2 and the event id (the X-Webhook-Id header) on line 3 instead of a request nonce. See Webhooks.

Opening the answer

1. signedText = the same layout but line 2 is RESPONSE and line 3 is the nonce of your request; lines 4-10 come from the answer's envelope.
2. Verify signature with our public key (RSA-PSS-SHA256). If it does not verify, discard the answer.
3. aesKey = RSA-OAEP-SHA256-decrypt(your private key, encryptedKey)
4. json = AES-256-GCM-decrypt(aesKey, iv, payload without its last 16 bytes, tag = the last 16 bytes, aad = timestamp + "\n" + nonce of the answer)

Samples (Node.js, C#, Python, Java)

Each client file below is self-contained, tested against our server, and has the same command line interface: keygen, build-request, open-response. Download: fzp-client.js (Node.js 18+, no dependencies) · FzpClient.cs.txt (.NET 6+, rename to FzpClient.cs) · fzp_client.py.txt (Python 3.8+, pip install cryptography requests, rename to fzp_client.py) · FzpClient.java.txt (Java 11+, rename to FzpClient.java).

const fs = require('fs');
const { buildRequest, openResponse } = require('./fzp-client');

const base = 'https://your-finzep-host';
const apiKey = 'fzp_...';
const clientKeyId = 'ck_...';
const clientPrivateKeyPem = fs.readFileSync('client-private.pem', 'utf8');

async function main() {
  // 1) our public key (once; cache it)
  const pk = await (await fetch(base + '/API/PublicKey')).json();

  // 2) the plain request
  const payout = { APIRequestID: 'REQ-' + Date.now(), TransMode: 'IMPS', Amount: 100, AccountNo: '1234567890123', IFSC: 'HDFC0000123',
                   BeneName: 'Ramesh Kumar', BeneMobile: '9876543210', SenderName: 'Suresh Sharma', SenderMobile: '9999999999', SenderEmail: 'sender@example.com' };

  // 3) encrypt + sign, send
  const { envelope, body } = buildRequest({ clientKeyId, serverKeyId: pk.serverKeyId, path: '/API/Payout', json: JSON.stringify(payout),
                                            clientPrivateKeyPem, serverPublicKeyPem: pk.publicKeyPem });
  const res = await fetch(base + '/API/Payout', { method: 'POST', body,
    headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey, 'X-Encrypted': '1' } });
  const text = await res.text();

  // 4) verify + decrypt (plain JSON means an early error such as a wrong API key)
  const answer = res.headers.has('x-encrypted')
    ? JSON.parse(openResponse({ responseBody: text, requestEnvelope: envelope, clientPrivateKeyPem, serverPublicKeyPem: pk.publicKeyPem }))
    : JSON.parse(text);
  console.log(res.status, answer);   // { success, status, statusName, message, apiRequestID, transactionId, utr, errorCode, referenceId }
}
main();

// FzpClient.cs from this page, in your project
using System.Security.Cryptography;
using System.Text.Json;

var http = new HttpClient { BaseAddress = new Uri("https://your-finzep-host") };

// our public key (once; cache it)
var pk = JsonDocument.Parse(await http.GetStringAsync("/API/PublicKey")).RootElement;
using var serverPublic = RSA.Create();
serverPublic.ImportFromPem(pk.GetProperty("publicKeyPem").GetString());
using var clientPrivate = RSA.Create();
clientPrivate.ImportFromPem(File.ReadAllText("client-private.pem"));

var client = new FzpClient(http, apiKey: "fzp_...", clientKeyId: "ck_...", clientPrivate,
                           pk.GetProperty("serverKeyId").GetString()!, serverPublic);

var payout = JsonSerializer.Serialize(new {
    APIRequestID = "REQ-" + DateTime.UtcNow.Ticks, TransMode = "IMPS", Amount = 100.00, AccountNo = "1234567890123", IFSC = "HDFC0000123",
    BeneName = "Ramesh Kumar", BeneMobile = "9876543210", SenderName = "Suresh Sharma", SenderMobile = "9999999999", SenderEmail = "sender@example.com" });

var (status, answer) = await client.PostAsync("/API/Payout", payout);   // encrypts, signs, verifies and decrypts for you
Console.WriteLine($"{status} {answer}");

import json, time
from fzp_client import FzpClient
import requests

base = "https://your-finzep-host"
pk = requests.get(base + "/API/PublicKey").json()            # our public key (once; cache it)

client = FzpClient(base_url=base, api_key="fzp_...", client_key_id="ck_...",
                   client_private_pem=open("client-private.pem").read(),
                   server_key_id=pk["serverKeyId"], server_public_pem=pk["publicKeyPem"])

payout = {"APIRequestID": "REQ-%d" % int(time.time()), "TransMode": "IMPS", "Amount": 100.00, "AccountNo": "1234567890123",
          "IFSC": "HDFC0000123", "BeneName": "Ramesh Kumar", "BeneMobile": "9876543210",
          "SenderName": "Suresh Sharma", "SenderMobile": "9999999999", "SenderEmail": "sender@example.com"}

status, answer = client.post("/API/Payout", payout)         # encrypts, signs, verifies and decrypts for you
print(status, answer)   # {'success': True, 'status': 2, 'statusName': 'Success', ..., 'transactionId': 'S2610...', 'errorCode': 0}

// FzpClient.java from this page, in your project
import java.net.URI;
import java.net.http.*;

public class Demo {
    public static void main(String[] a) throws Exception {
        String base = "https://your-finzep-host";
        String pk = HttpClient.newHttpClient().send(HttpRequest.newBuilder(URI.create(base + "/API/PublicKey")).build(),
                HttpResponse.BodyHandlers.ofString()).body();                    // our public key (once; cache it)
        String serverKeyId = FzpClient.field(pk, "serverKeyId");
        String serverPem = FzpClient.field(pk, "publicKeyPem").replace("\\n", "\n");

        FzpClient c = new FzpClient(base, "fzp_...", "ck_...",
                java.nio.file.Files.readString(java.nio.file.Path.of("client-private.pem")), serverKeyId, serverPem);

        String payout = "{\"APIRequestID\":\"REQ-" + System.currentTimeMillis() + "\",\"TransMode\":\"IMPS\",\"Amount\":100.00,"
                + "\"AccountNo\":\"1234567890123\",\"IFSC\":\"HDFC0000123\",\"BeneName\":\"Ramesh Kumar\",\"BeneMobile\":\"9876543210\","
                + "\"SenderName\":\"Suresh Sharma\",\"SenderMobile\":\"9999999999\",\"SenderEmail\":\"sender@example.com\"}";
        System.out.println(c.post("/API/Payout", payout));                          // encrypts, signs, verifies and decrypts for you
    }
}

Webhook receivers (a small server that verifies and decrypts our calls): webhook-receiver.js, webhook_receiver.py.txt, WebhookReceiver.java.txt - see Webhooks.

PHP, Go and others: implement the specification with your language's standard crypto library (RSA-OAEP-SHA256, RSA-PSS-SHA256 with salt length 32, AES-256-GCM) - the four samples above are the reference.

Postman

Download Finzep-Payout-API.postman_collection.json and Finzep-Payout.postman_environment.json, and import both.

1. Select the Finzep Payout environment and fill baseUrl, apiKey, clientKeyId and clientPrivateKey (paste the whole PEM of your private key).
2. Run 0. Setup → Get server public key. It stores serverKeyId and serverPublicKey.
3. Run 1. Payout → Payout - bank transfer (IMPS). Edit the plain JSON in the Body as you like - a pre-request script encrypts and signs it just before sending, and a tests script verifies and decrypts the answer. See the Visualize tab (or the console) for the plain answer.
4. Run Payout status (last request); {{lastApiRequestId}} is filled by the previous payout call.
5. Folder 2. Learn the errors shows what a plain request (1012), a missing key and a wrong key return.

node fzp-client.js build-request --client-key-id ck_... --server-key-id sk_... --path /API/Payout \
     --client-private client-private.pem --server-public server-public.pem --json '{"APIRequestID":"REQ-1", ...}'

Troubleshooting

Security checklist

• Keep client-private.pem and the API key in a secrets manager, never in source control, logs or the browser.
• Call the API only from your server; never from a mobile app or web page.
• Whitelist your server's IP in API Access.
• Keep your clock in sync (NTP); use TLS (https) for all calls as well.
• Verify our signature on every answer and on every webhook, and reject anything that does not verify.
• Rotate your key pair and API key periodically, and at once if staff with access leave or you suspect a leak. Revoke old keys in API Access.
• Store the transactionId, utr and referenceId with your own order for reconciliation and support.