Payout API Overview
Integrate Paywize Payout API for instant IMPS, NEFT, and bulk disbursements.
Last updated: 2026-02-21
Payout API
Overview
The Paywize Payout API enables businesses to send money instantly to bank accounts using IMPS, NEFT, and RTGS transfer methods. Built for high performance and reliability, our API handles everything from single transfers to bulk payouts with real-time status tracking and webhook notifications.
Version: 1.0.0
Release Date: November 5, 2025
Base URL: https://merchant.paywize.in/api/payout/v1/
Key Features
- Instant Transfers: IMPS, NEFT, and RTGS support
- Bulk Processing: Handle thousands of payouts simultaneously
- Real-time Status: Live transaction tracking and updates
- Webhook Support: Instant status notifications
- Enterprise Security: AES-256-CBC encryption and JWT authentication
- High Performance: 99.9% uptime with <200ms response times
Security Measures
- Authentication: All requests require a Bearer token in the Authorization header
- Encryption: Request/response data encrypted using AES-256-CBC
- IP Whitelisting: Only approved merchant IPs can access APIs and receive callbacks
- TLS Enforcement: All endpoints are accessible only over HTTPS
- Rate Limiting: Transactions are controlled by both TPS and daily limits
- Input Validation: Every request payload is strictly validated before processing
Quick Start
1. Authentication & Encryption
All Payout API requests use shared authentication and encryption:
- Authentication: Learn about JWT token generation
- Encryption: Learn about AES-256-CBC encryption
2. Complete Integration Example
import crypto from 'crypto';
// Encryption/Decryption functions (shared across all APIs)
function encryptMerchantData(data, key, iv) {
if (typeof data === 'object') {
data = JSON.stringify(data);
}
const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
return encrypted.toString('base64');
}
function decryptMerchantData(data, key, iv) {
const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
const decrypted = Buffer.concat([
decipher.update(Buffer.from(data, 'base64')),
decipher.final()
]);
return decrypted.toString('utf8');
}
// Your API credentials
const API_KEY = 'your_32_char_api_key_here_123456';
const SECRET_KEY = 'your_16_char_iv_12';
// Step 1: Generate access token
async function generateAccessToken() {
const credentials = {
apiKey: API_KEY,
secretKey: SECRET_KEY
};
const encryptedPayload = encryptMerchantData(credentials, API_KEY, SECRET_KEY);
const response = await fetch('https://merchant.paywize.in/api/v1/auth/clients/token', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ payload: encryptedPayload })
});
const result = await response.json();
if (result.respCode === 2000) {
const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
return JSON.parse(decryptedData).token;
}
throw new Error(result.respMessage);
}
// Step 2: Initiate payout
async function initiatePayout(token) {
const payoutData = {
sender_id: "unique_transaction_id",
wallet_id: "PAYWIZE12345679",
payment_mode: "IMPS",
beneficiary_name: "John Doe",
beneficiary_acc_number: "123456789012",
beneficiary_ifsc: "HDFC0001234",
amount: 1000,
remarks: "Payment",
callback_url: "https://your-webhook-url.com/payout-webhook"
};
const encryptedPayload = encryptMerchantData(payoutData, API_KEY, SECRET_KEY);
const response = await fetch('https://merchant.paywize.in/api/payout/v1/initiate', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({ payload: encryptedPayload })
});
const result = await response.json();
if (result.respCode === 2000) {
const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
return JSON.parse(decryptedData);
}
throw new Error(result.respMessage);
}
// Step 3: Check payout status
async function checkPayoutStatus(token, transactionId) {
const response = await fetch(
`https://merchant.paywize.in/api/payout/v1/status?transaction_id=${transactionId}`,
{
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
}
}
);
const result = await response.json();
if (result.respCode === 2000) {
const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
return JSON.parse(decryptedData);
}
throw new Error(result.respMessage);
}
// Step 4: Check wallet balance
async function checkWalletBalance(token, walletId) {
const response = await fetch(`https://merchant.paywize.in/api/payout/v1/balance?wallet_id=${walletId}`, {
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
}
});
const result = await response.json();
if (result.respCode === 2000) {
const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
return JSON.parse(decryptedData);
}
throw new Error(result.respMessage);
}
// Complete workflow
async function payoutWorkflow() {
try {
// Generate token
const token = await generateAccessToken();
console.log('✅ Token generated successfully');
// Check wallet balance
const balance = await checkWalletBalance(token, 'PAYWIZE12345679');
console.log('✅ Wallet balance:', balance);
// Initiate payout
const payout = await initiatePayout(token);
console.log('✅ Payout initiated:', payout);
// Check status
const status = await checkPayoutStatus(token, payout.transaction_id);
console.log('✅ Payout status:', status);
} catch (error) {
console.error('❌ Error:', error.message);
}
}
// Run the workflow
payoutWorkflow();
API Endpoints
1. Generate Access Token
POST merchant.paywize.in/api/v1/auth/clients/token
Generate a JWT access token for authenticating API requests. Tokens expire after 5 minutes.
2. Initiate Payout
POST https://merchant.paywize.in/api/payout/v1/initiate
Initiate a payout transaction to transfer money to a beneficiary account.
3. Transaction Status
GET https://merchant.paywize.in/api/payout/v1/status
Check the current status of a payout transaction.
4. Wallet Balance
GET https://merchant.paywize.in/api/payout/v1/balance
Check your current wallet balance.
5. Webhook Notifications
Receive real-time payout status updates via webhooks (configured per transaction).
Transfer Modes
| Mode | Description | Processing Time | Min Amount | Max Amount |
|---|---|---|---|---|
| IMPS | Immediate Payment Service | Instant (24x7) | ₹1 | ₹5,00,000 |
| NEFT | National Electronic Funds Transfer | 30 minutes - 2 hours | ₹1 | ₹10,00,000 |
| RTGS | Real Time Gross Settlement | 30 minutes - 2 hours | ₹2,00,000 | ₹10,00,00,000 |
Transaction Status Values
| Status | Description |
|---|---|
| INITIATED | Transaction has been initiated |
| PROCESSING | Transaction is being processed |
| SUCCESS | Transaction completed successfully |
| FAILED | Transaction failed |
| REFUNDED | Transaction amount refunded |
Error Codes
Authentication Errors
| Code | Message |
|---|---|
| 2000 | Access Token generated |
| 4001 | Unauthorized access |
Payout Initiation Errors
| Code | Message |
|---|---|
| 2000 | Transaction initiated successfully |
| 4001 | Unauthorized - invalid or expired token |
| 4002 | Insufficient wallet balance |
| 4003 | Invalid beneficiary details |
| 4004 | Invalid amount format |
| 4005 | Amount below minimum limit |
| 4006 | Amount above maximum limit |
| 4007 | Invalid IFSC code |
| 4008 | Invalid account number |
| 4009 | Duplicate client reference ID |
| 4010 | Daily limit exceeded |
| 4011 | Monthly limit exceeded |
| 4012 | Invalid transfer mode |
| 4013 | Beneficiary account verification failed |
| 4014 | Bank down for maintenance |
| 4015 | Transaction not allowed to this bank |
| 5000 | Internal server error |
Testing
Sandbox Environment
Use the sandbox environment for testing:
- Base URL:
https://sandbox.merchant.paywize.in/api/payout/v1/ - Test Credentials: Contact support for sandbox API credentials
- Test Accounts: Use test bank accounts provided by Paywize for testing
Test Bank Accounts
For testing purposes, use these test bank account details:
| Bank | Account Number | IFSC Code | Expected Result |
|---|---|---|---|
| Test Bank | 1234567890 | TEST0001234 | Success |
| Test Bank | 9876543210 | TEST0001234 | Failed |
| Test Bank | 5555555555 | TEST0001234 | Pending |
SDKs and Libraries
JavaScript/Node.js SDK
npm install @paywize/payout-api
import { PaywizePayout } from '@paywize/payout-api';
const client = new PaywizePayout({
apiKey: 'your_api_key',
secretKey: 'your_secret_key',
environment: 'production' // or 'sandbox'
});
const payout = await client.initiate({
client_ref_id: 'TXN123456',
amount: '1000.00',
beneficiary: {
name: 'John Doe',
account_number: '1234567890',
ifsc: 'HDFC0001234'
}
});
Python SDK
pip install paywize-payout
from paywize_payout import PaywizePayout
client = PaywizePayout(
api_key='your_api_key',
secret_key='your_secret_key',
environment='production' # or 'sandbox'
)
payout = client.initiate({
'client_ref_id': 'TXN123456',
'amount': '1000.00',
'beneficiary': {
'name': 'John Doe',
'account_number': '1234567890',
'ifsc': 'HDFC0001234'
}
})
Support
Documentation
Help & Support
- Technical Support: developer-support@paywize.in
- Business Queries: business@paywize.in
- Documentation Issues: docs@paywize.in
Resources
- Developer Portal: https://developer.paywize.in
- Status Page: https://status.paywize.in
- Community Forum: https://community.paywize.in
Next Steps
- Get API Credentials: Contact Paywize to obtain your API key and secret key
- Test Integration: Start with our sandbox environment
- Implement Webhooks: Set up webhook endpoints to receive real-time updates
- Go Live: Switch to production environment after testing
- Monitor: Use our dashboard to monitor transaction status and analytics
Get Started with API Credentials →
Version 1.0.0 | Last Updated: November 2025