Finvex API Reference

Finvex provides a complete payment infrastructure API for Indian startups. Accept payments via Razorpay + Cashfree, manage subscriptions, automate GST, send WhatsApp payment links, and more — all through a single API.

Base URL

https://finvexpay.com/v1

100+ Endpoints

33 features

REST API

JSON responses

Rate Limit

300 req/min

Authentication

Finvex supports two authentication methods:

1. API Key (Server-to-server)

Pass your API key in the X-Finvex-Key header:

cURL
curl https://finvexpay.com/v1/orders \
  -H "X-Finvex-Key: finvex_test_KEYID:SECRET"

2. JWT Bearer Token (Dashboard)

Used by the dashboard. Obtain via login, include in Authorization header:

cURL
curl https://finvexpay.com/v1/merchant \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Test vs Live Mode

Keys prefixed with finvex_test_ operate in test mode. Switch to finvex_live_ for production.

Orders & Payments

Create payment orders, verify payments, and process refunds.

POST
/orders

Create a new payment order

GET
/orders

List all orders

GET
/orders/:id

Get order details

POST
/orders/:id/verify

Verify payment after checkout

GET
/payments

List all payment transactions

POST
/payments/:id/refund

Refund a payment

GET
/settlements

List settlements

Create Order

Creates a payment order and routes to the best provider (Razorpay or Cashfree).

Parameters

amountintegerrequiredAmount in paise (e.g., 50000 = ₹500)
currencystringCurrency code (default: INR)
receiptstringYour internal order reference
descriptionstringOrder description
customerobjectCustomer info: name, email, phone
cURL
curl -X POST https://finvexpay.com/v1/orders \
  -H "X-Finvex-Key: finvex_test_KEY:SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "INR",
    "description": "Pro Plan",
    "customer": {
      "name": "Anil Kumar",
      "email": "anil@example.com",
      "phone": "+919876543210"
    }
  }'
Node.js
const finvex = require('finvex-node')('finvex_test_KEY:SECRET')

const order = await finvex.orders.create({
  amount: 50000,
  currency: 'INR',
  description: 'Pro Plan'
})
console.log(order.id) // finvex_ord_...
Python
import finvex
client = finvex.Client('finvex_test_KEY:SECRET')

order = client.orders.create(
    amount=50000,
    currency='INR',
    description='Pro Plan'
)
print(order['id'])  # finvex_ord_...

Subscriptions

Create recurring billing plans and manage customer subscriptions with UPI Autopay support.

POST
/plans

Create a billing plan

GET
/plans

List all plans

POST
/subscriptions

Subscribe a customer to a plan

GET
/subscriptions

List subscriptions

POST
/subscriptions/:id/cancel

Cancel subscription

POST
/subscriptions/:id/pause

Pause subscription

POST
/subscriptions/:id/resume

Resume subscription

cURL
# Create a monthly plan
curl -X POST https://finvexpay.com/v1/plans \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{"name":"Pro","amount":99900,"interval":"monthly"}'

# Subscribe a customer
curl -X POST https://finvexpay.com/v1/subscriptions \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{"plan_id":"finvex_plan_xxx","customer_email":"user@example.com"}'

Webhooks

Receive real-time notifications for payment events. Webhooks are signed with HMAC-SHA256.

POST
/webhooks

Create a webhook endpoint

GET
/webhooks

List webhook endpoints

POST
/webhooks/:id/test

Send a test webhook

DELETE
/webhooks/:id

Delete webhook endpoint

Verify Webhook Signature

Node.js
const crypto = require('crypto')

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

// In your Express/Fastify handler:
app.post('/webhooks/finvex', (req, res) => {
  const sig = req.headers['x-finvex-signature']
  if (!verifyWebhook(req.rawBody, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }
  // Process event...
  res.sendStatus(200)
})

GST Engine

Auto-calculate GST (CGST/SGST/IGST), generate e-invoices, and prepare GSTR-1 returns.

POST
/gst/calculate

Calculate GST for a transaction

POST
/gst/invoices

Generate e-invoice

GET
/gst/invoices

List GST invoices

GET
/gst/gstr1?month=2026-04

Generate GSTR-1 for a month

GET
/gst/hsn-lookup?q=software

Search HSN/SAC codes

cURL
curl -X POST https://finvexpay.com/v1/gst/calculate \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "amount": 100000,
    "hsn_code": "998316",
    "seller_state": "KA",
    "buyer_state": "MH"
  }'

AI Dunning

AI-powered payment recovery. When a subscription charge fails, Finvex uses Claude AI to determine the optimal retry strategy.

POST
/dunning/trigger

Trigger dunning for a failed payment

GET
/dunning

List dunning records

GET
/dunning/:id/schedule

Get AI retry schedule

GET
/dunning/analytics/recovery-rate

Recovery analytics

WhatsApp Payments

Send payment links, invoices, and receipts via WhatsApp. Supports 6 Indian languages.

POST
/whatsapp/send-payment

Send payment link via WhatsApp

POST
/whatsapp/send-invoice

Send invoice via WhatsApp

POST
/whatsapp/send-receipt

Send receipt via WhatsApp

POST
/whatsapp/bulk-send

Bulk send via CSV

cURL
curl -X POST https://finvexpay.com/v1/whatsapp/send-payment \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "phone": "+919876543210",
    "amount": 50000,
    "description": "Monthly subscription",
    "language": "hi"
  }'

Analytics (CFO Mode)

SaaS metrics: MRR, ARR, churn rate, LTV, and cohort analysis.

GET
/analytics/overview

Revenue, orders, success rate

GET
/analytics/mrr

Monthly Recurring Revenue + history

GET
/analytics/churn

Churn rate and churned customers

GET
/analytics/ltv

Average customer lifetime value

GET
/analytics/top-customers

Top 10 customers by revenue

Instant Payouts

Send money to any UPI ID or bank account instantly.

POST
/payouts

Create a payout

GET
/payouts

List payouts

POST
/payouts/bulk

Bulk payouts (up to 500)

POST
/payouts/verify-upi

Verify a UPI VPA

cURL
curl -X POST https://finvexpay.com/v1/payouts \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{"amount":100000,"method":"upi","upi_vpa":"merchant@upi"}'

Checkout Builder

Create no-code checkout pages with custom branding.

POST
/checkout-pages

Create a checkout page

GET
/checkout-pages

List checkout pages

GET
/p/:slug

Public checkout page (no auth)

Embed SDK

Add Finvex payments to any website or app.

HTML
<script src="https://js.finvexpay.com/v1/checkout.js"></script>
<script>
  const finvex = Finvex('finvex_test_YOUR_KEY')
  finvex.checkout({
    order_id: 'ORDER_ID',
    amount: 50000,
    currency: 'INR',
    handler: (response) => {
      // Verify payment on your server
      fetch('/verify', {
        method: 'POST',
        body: JSON.stringify(response)
      })
    }
  })
</script>

Integration Guide

Step-by-step guide to integrate Finvex payments into your application.

Step 1: Get API Keys

Log in to your Finvex Dashboard and create API keys from the Developers section. You will get a key_id and key_secret.

Step 2: Create an Order (Server-side)

When a customer initiates payment, create an order from your backend:

Node.js (Express)
app.post('/create-order', async (req, res) => {
  const response = await fetch('https://finvexpay.com/v1/orders', {
    method: 'POST',
    headers: {
      'X-Finvex-Key': 'KEY_ID:KEY_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: req.body.amount,
      currency: 'INR',
      customer: { email: req.body.email }
    })
  })
  const order = await response.json()
  res.json(order)
})

Step 3: Open Checkout (Client-side)

Use the Finvex SDK to open the payment checkout:

JavaScript
const order = await fetch('/create-order', {
  method: 'POST',
  body: JSON.stringify({ amount: 50000 })
}).then(r => r.json())

const finvex = Finvex('finvex_test_KEY')
finvex.checkout({
  order_id: order.id,
  amount: order.amount,
  handler: (response) => {
    // Step 4: Verify payment
    verifyPayment(response)
  }
})

Step 4: Verify Payment (Server-side)

Always verify payments on your server before fulfilling orders:

Node.js
app.post('/verify-payment', async (req, res) => {
  const { order_id, payment_id, signature } = req.body

  const response = await fetch(`https://finvexpay.com/v1/orders/${order_id}/verify`, {
    method: 'POST',
    headers: {
      'X-Finvex-Key': 'KEY_ID:KEY_SECRET',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ payment_id, signature })
  })

  const result = await response.json()
  if (result.verified) {
    // Payment confirmed - fulfill the order
    await fulfillOrder(order_id)
  }
})

Step 5: Handle Webhooks

Set up webhooks for reliable payment notifications:

Node.js
// Register webhook in dashboard or via API
// Then handle incoming events:
app.post('/webhooks/finvex', (req, res) => {
  const sig = req.headers['x-finvex-signature']
  if (!verifySignature(req.rawBody, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid')
  }

  const event = req.body
  switch (event.event) {
    case 'payment.captured':
      handlePaymentCaptured(event.data)
      break
    case 'refund.processed':
      handleRefund(event.data)
      break
  }
  res.sendStatus(200)
})

Store (Merchant of Record)

Create and manage your storefront. Finvex acts as your Merchant of Record, handling payments, taxes, and compliance.

POST
/store

Create a new store

GET
/store

Get store details

PUT
/store

Update store settings

cURL
curl -X POST https://finvexpay.com/v1/store \
  -H "X-Finvex-Key: KEY:SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SaaS Store",
    "slug": "my-saas",
    "currency": "INR",
    "description": "Digital products and subscriptions"
  }'

Products

Create and manage digital products with auto-generated checkout URLs. Supports one-time purchases and recurring subscriptions.

POST
/products

Create a new product

GET
/products

List all products

PUT
/products/:id

Update a product

DELETE
/products/:id

Delete a product

cURL
curl -X POST https://finvexpay.com/v1/products \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "name": "Pro Plan",
    "price": 99900,
    "type": "subscription",
    "interval": "monthly",
    "description": "Access to all premium features"
  }'

Sales & Purchases

Track all purchases, revenue, and platform fees. View detailed sales analytics and export reports.

GET
/sales

List all sales with filters

GET
/sales/stats

Revenue stats, platform fees, net earnings

cURL
# Get sales with date filter
curl https://finvexpay.com/v1/sales?from=2026-01-01&to=2026-04-13 \
  -H "X-Finvex-Key: KEY:SECRET"

# Get revenue stats
curl https://finvexpay.com/v1/sales/stats \
  -H "X-Finvex-Key: KEY:SECRET"

Hosted Checkout

Customer-facing hosted checkout pages. No integration required -- share the URL and start selling.

GET
/buy/:store/:product

Public checkout page (no auth required)

POST
/buy/:store/:product/pay

Process payment for a product

GET
/buy/:store/:product/success

Post-payment success page

cURL
# Process a checkout payment (public endpoint)
curl -X POST https://finvexpay.com/v1/buy/my-saas/pro-plan/pay \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "customer_name": "Priya Sharma",
    "payment_method": "upi"
  }'

License Keys

Issue and manage software license keys. Auto-generated on purchase, with activation and verification endpoints.

POST
/licenses/verify

Verify a license key

POST
/licenses/activate

Activate a license on a device

cURL
# Verify a license key
curl -X POST https://finvexpay.com/v1/licenses/verify \
  -H "Content-Type: application/json" \
  -d '{"license_key":"FINVEX-XXXX-XXXX-XXXX","product_id":"prod_xxx"}'

# Activate on a device
curl -X POST https://finvexpay.com/v1/licenses/activate \
  -d '{"license_key":"FINVEX-XXXX-XXXX-XXXX","device_id":"device_abc123"}'

Affiliates

Create and manage a referral program. Track affiliate signups, conversions, and commissions.

POST
/affiliates

Create an affiliate partner

GET
/affiliates

List all affiliates and stats

GET
/ref/:code

Public referral redirect (no auth)

cURL
curl -X POST https://finvexpay.com/v1/affiliates \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "name": "Partner One",
    "email": "partner@example.com",
    "commission_percent": 20,
    "products": ["prod_xxx"]
  }'

Coupons

Create discount codes with flexible rules -- percentage or flat discounts, usage limits, and expiry dates.

POST
/coupons

Create a coupon code

GET
/coupons

List all coupons

POST
/coupons/validate

Validate a coupon at checkout

cURL
curl -X POST https://finvexpay.com/v1/coupons \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "code": "LAUNCH50",
    "discount_type": "percent",
    "discount_value": 50,
    "max_uses": 100,
    "expires_at": "2026-12-31"
  }'

Revenue Splits

Automatically split revenue between team members, co-founders, or partners on every sale.

POST
/splits

Create a revenue split rule

GET
/splits

List all split rules

cURL
curl -X POST https://finvexpay.com/v1/splits \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "product_id": "prod_xxx",
    "splits": [
      {"email": "founder@example.com", "percent": 60},
      {"email": "cofounder@example.com", "percent": 40}
    ]
  }'

Product Variants

Create pricing tiers for your products (e.g., Starter, Pro, Enterprise) with different features and limits.

POST
/products/:id/variants

Create a product variant

GET
/products/:id/variants

List variants for a product

cURL
curl -X POST https://finvexpay.com/v1/products/prod_xxx/variants \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "name": "Enterprise",
    "price": 499900,
    "features": ["Unlimited users", "Priority support", "Custom domain"],
    "sort_order": 3
  }'

Bundles

Bundle multiple products together and sell them at a discounted price.

POST
/bundles

Create a product bundle

GET
/bundles

List all bundles

cURL
curl -X POST https://finvexpay.com/v1/bundles \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "name": "Complete Toolkit",
    "products": ["prod_aaa", "prod_bbb", "prod_ccc"],
    "price": 199900,
    "description": "Get all three products at 40% off"
  }'

Reviews

Collect and display customer ratings and reviews on your product pages.

POST
/reviews

Submit a review (public, no auth)

GET
/products/:id/reviews

List reviews for a product

cURL
# Submit a review (public endpoint)
curl -X POST https://finvexpay.com/v1/reviews \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "rating": 5,
    "comment": "Excellent product, saved us hours!",
    "customer_email": "buyer@example.com"
  }'

Waitlist

Collect early interest before launching a product. Manage pre-launch waitlists with position tracking.

POST
/waitlist/join

Join a waitlist (public, no auth)

GET
/waitlist/:product_id

List waitlist entries for a product

cURL
# Join a waitlist (public endpoint)
curl -X POST https://finvexpay.com/v1/waitlist/join \
  -H "Content-Type: application/json" \
  -d '{"product_id":"prod_xxx","email":"interested@example.com","name":"Rahul"}'

# View waitlist (authenticated)
curl https://finvexpay.com/v1/waitlist/prod_xxx \
  -H "X-Finvex-Key: KEY:SECRET"

Abandoned Carts

Track visitors who start checkout but do not complete payment. Use data for recovery campaigns.

POST
/cart/track

Track a cart event (public, no auth)

GET
/abandoned-carts

List abandoned carts

cURL
# Track a cart event (public endpoint)
curl -X POST https://finvexpay.com/v1/cart/track \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xxx",
    "customer_email": "visitor@example.com",
    "step": "checkout_started"
  }'

# List abandoned carts
curl https://finvexpay.com/v1/abandoned-carts \
  -H "X-Finvex-Key: KEY:SECRET"

Email Marketing

Manage subscribers and send broadcast emails to your customer base. Built-in templates for product launches, updates, and promotions.

GET
/subscribers

List all email subscribers

POST
/broadcasts

Create a broadcast email

POST
/broadcasts/:id/send

Send a broadcast to subscribers

cURL
# Create a broadcast
curl -X POST https://finvexpay.com/v1/broadcasts \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "subject": "New Feature Launch",
    "body_html": "<h1>Big News!</h1><p>We just shipped...</p>",
    "segment": "all_customers"
  }'

# Send the broadcast
curl -X POST https://finvexpay.com/v1/broadcasts/bc_xxx/send \
  -H "X-Finvex-Key: KEY:SECRET"

UPI QR Codes

Generate dynamic UPI QR codes for in-person or invoice payments. Track scan and payment status in real time.

POST
/qr/create

Create a UPI QR code

GET
/qr/:id

Get QR code status and image URL

POST
/qr/:id/close

Close/expire a QR code

cURL
curl -X POST https://finvexpay.com/v1/qr/create \
  -H "X-Finvex-Key: KEY:SECRET" \
  -d '{
    "amount": 50000,
    "description": "Invoice #5678",
    "customer_name": "Walk-in Customer",
    "expires_in": 3600
  }'

Multi-Currency

Support international customers with real-time currency conversion. Display prices in 30+ currencies while settling in INR.

GET
/currencies

List supported currencies and rates

GET
/currencies/convert

Convert between currencies

cURL
# List supported currencies
curl https://finvexpay.com/v1/currencies \
  -H "X-Finvex-Key: KEY:SECRET"

# Convert amount
curl "https://finvexpay.com/v1/currencies/convert?from=USD&to=INR&amount=9900" \
  -H "X-Finvex-Key: KEY:SECRET"

KYC

Creator verification and KYC compliance. Required for enabling payouts and going live.

GET
/kyc

Get KYC verification status

POST
/kyc/submit

Submit KYC documents for verification

cURL
# Check KYC status
curl https://finvexpay.com/v1/kyc \
  -H "X-Finvex-Key: KEY:SECRET"

# Submit KYC documents
curl -X POST https://finvexpay.com/v1/kyc/submit \
  -H "X-Finvex-Key: KEY:SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "pan": "ABCDE1234F",
    "gst_number": "29ABCDE1234F1Z5",
    "bank_account": "encrypted_account_data",
    "document_type": "aadhaar"
  }'

Customer Portal

Give your customers a self-service portal to view purchases, download products, and manage subscriptions.

POST
/portal/login

Customer login via magic link (public)

GET
/portal/purchases

List customer purchases (public, session auth)

cURL
# Send magic link to customer
curl -X POST https://finvexpay.com/v1/portal/login \
  -H "Content-Type: application/json" \
  -d '{"email":"customer@example.com"}'

# Customer views their purchases (with session token)
curl https://finvexpay.com/v1/portal/purchases \
  -H "Authorization: Bearer portal_session_token"

Admin

Platform administration endpoints for managing merchants, viewing global stats, and assigning roles. Requires admin-level authentication.

GET
/admin/stats

Platform-wide statistics and metrics

GET
/admin/merchants

List all merchants on the platform

PUT
/admin/merchants/:id/role

Update a merchant role

cURL
# Get platform stats (admin only)
curl https://finvexpay.com/v1/admin/stats \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"

# Update merchant role
curl -X PUT https://finvexpay.com/v1/admin/merchants/merchant_xxx/role \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -d '{"role":"verified_seller"}'

Need help? Contact support@finvexpay.com

Finvex API v1.0 — Last updated April 2026