Finsova
API Docs
REST Reference v1
finsova.org
Finsova Fintech Pvt Ltd · v1

Payments infrastructure,
documented properly.

Collections, payouts and TSP rails through a single REST interface. Every endpoint below is live-ready, JSON-only, and authenticated with a short-lived bearer token.

10
Endpoints
JSON
Request / Response
60 min
Token Validity
24×7
IMPS / UPI Rails
Getting Started

Overview

The Finsova API is organised into two suites. The Core Suite covers merchant collections (payment gateway) and payouts. The TSP Suite exposes the same payout rails for technology service provider partners operating under a sponsor bank arrangement.

Whitelist your infrastructureShare your production server IP and callback URLs with your Finsova relationship manager.
Collect your credentialsYou receive a client-key and client-secret pair from the Finsova dashboard.
Generate a bearer tokenCall /api/v1/createtoken and cache the token until it expires.
Transact and reconcileFire payouts or create PG orders, then confirm every transaction via status API — never via callback alone.
Idempotency: txn_id aapke system ka unique reference hai. Same txn_id dobara bhejne par Finsova naya transfer create nahi karega — existing record return hoga. Isliye har attempt ke liye ek hi txn_id rakhein.
Security

Authentication

Finsova uses a two-step scheme. Static credentials mint a short-lived JWT; that JWT authorises every business call.

Step 1 — Mint the token
client-key Static key issued by Finsova. Sent as a header.
client-secret Static secret issued by Finsova. Sent as a header.
Step 2 — Use the token
Authorization Bearer <token> on every subsequent request.
Content-Type application/json
Never expose credentials client-side. Keys ko sirf server-side environment variables mein rakhein — browser, mobile app ya public repo mein kabhi nahi. Token expire hone par hi naya token generate karein; har request par token banane se rate limit lag sakti hai.
Configuration

Base URL & Environment

Environment Base URL Notes
Production https://app.finsova.in Live funds. IP whitelisting mandatory.
UAT / Sandbox Issued on request Sandbox credentials onboarding team se milte hain.
All endpoints are POST and accept application/json. Full URL = https://app.finsova.in + endpoint path shown on each card below.
Async

Webhooks & Callbacks

Finsova posts a JSON callback to your registered URL whenever a transaction reaches a terminal state. Respond with HTTP 200 within 10 seconds; non-200 responses are retried.

Payout callback
{
  "http_code": 201,
  "status": "SUCCESS",
  "message": "Transaction updated successfully.",
  "data": {
    "transaction_id": "FSV124630413",
    "reference_id": "Y0YFXY8QG8XTVSIX",
    "utr": "525612007094",
    "transfer_mode": "IMPS",
    "amount": 100,
    "timestamp": "2026-07-31 09:25:16"
  }
}
Payin callback
{
  "http_code": 200,
  "status": "SUCCESS",
  "message": "Transaction updated successfully.",
  "data": {
    "transaction_id": "FSV124630413",
    "reference_id": "Y0YFXY8QG8XTVSIX",
    "utr": "525612007094",
    "transfer_mode": "UPI",
    "amount": 100,
    "timestamp": "2026-07-31 09:25:16"
  }
}
Reconciliation rule: callback ko trigger maaniye, truth nahi. Ledger update karne se pehle hamesha status API se transaction confirm karein.
No endpoint matches that search.
Reference

Transfer Modes

Mode Availability Per-txn limit Typical settlement
IMPS 24×7×365 ₹5,00,000 Instant
UPI 24×7×365 ₹1,00,000 Instant
NEFT 24×7 (half-hourly batches) No upper cap Same batch cycle
RTGS Banking hours Min ₹2,00,000 Real time
Limits are indicative and follow your sponsor bank's prevailing rules — final limits contract mein confirm hote hain.
Reference

Status Model

txn_status Terminal? What it means What to do
SUCCESS Yes Funds transferred; UTR available. Mark settled, store bank_reference.
PENDING No At bank / NPCI, outcome awaited. Poll status API; do not retry the payout.
FAILED Yes Rejected; amount reversed to wallet. Fix the cause and retry with a new txn_id.
NOT CREATED Yes Request never registered (validation / balance). Correct the payload and resubmit.
Reference

Error Codes

HTTP Meaning Common cause
200 OK Request processed. Check status in the body.
201 Created Transaction registered successfully.
202 Accepted Transaction queued, currently PENDING.
400 Bad Request Missing/invalid field, bad IFSC, duplicate txn_id.
401 Unauthorized Token missing, expired, or wrong client credentials.
403 Forbidden IP not whitelisted or account disabled.
404 Not Found Unknown endpoint or transaction reference.
422 Unprocessable Insufficient wallet balance or limit breach.
429 Too Many Requests Rate limit exceeded — back off and retry.
500 Server Error Upstream/bank issue. Retry status check, do not re-fire the payout.
Help

Support

Integration desk

Technical queries, whitelisting requests, and UAT credentials — apne relationship manager ko likhein ya Finsova support desk par raise karein.

Escalation checklist

Har ticket ke saath txn_id, request timestamp (IST), full request payload aur received response zaroor bhejein — resolution turant hoti hai.

Copied