Skip to main content

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:

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.

View Authentication Details →

2. Initiate Payout

POST https://merchant.paywize.in/api/payout/v1/initiate

Initiate a payout transaction to transfer money to a beneficiary account.

View API Details →

3. Transaction Status

GET https://merchant.paywize.in/api/payout/v1/status

Check the current status of a payout transaction.

View API Details →

4. Wallet Balance

GET https://merchant.paywize.in/api/payout/v1/balance

Check your current wallet balance.

View API Details →

5. Webhook Notifications

Receive real-time payout status updates via webhooks (configured per transaction).

View Webhook Details →

Transfer Modes

ModeDescriptionProcessing TimeMin AmountMax Amount
IMPSImmediate Payment ServiceInstant (24x7)₹1₹5,00,000
NEFTNational Electronic Funds Transfer30 minutes - 2 hours₹1₹10,00,000
RTGSReal Time Gross Settlement30 minutes - 2 hours₹2,00,000₹10,00,00,000

Transaction Status Values

StatusDescription
INITIATEDTransaction has been initiated
PROCESSINGTransaction is being processed
SUCCESSTransaction completed successfully
FAILEDTransaction failed
REFUNDEDTransaction amount refunded

Error Codes

Authentication Errors

CodeMessage
2000Access Token generated
4001Unauthorized access

Payout Initiation Errors

CodeMessage
2000Transaction initiated successfully
4001Unauthorized - invalid or expired token
4002Insufficient wallet balance
4003Invalid beneficiary details
4004Invalid amount format
4005Amount below minimum limit
4006Amount above maximum limit
4007Invalid IFSC code
4008Invalid account number
4009Duplicate client reference ID
4010Daily limit exceeded
4011Monthly limit exceeded
4012Invalid transfer mode
4013Beneficiary account verification failed
4014Bank down for maintenance
4015Transaction not allowed to this bank
5000Internal 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:

BankAccount NumberIFSC CodeExpected Result
Test Bank1234567890TEST0001234Success
Test Bank9876543210TEST0001234Failed
Test Bank5555555555TEST0001234Pending

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

Resources

Next Steps

  1. Get API Credentials: Contact Paywize to obtain your API key and secret key
  2. Test Integration: Start with our sandbox environment
  3. Implement Webhooks: Set up webhook endpoints to receive real-time updates
  4. Go Live: Switch to production environment after testing
  5. Monitor: Use our dashboard to monitor transaction status and analytics

Get Started with API Credentials →


Version 1.0.0 | Last Updated: November 2025