Skip to main content

Collection API Overview

Integrate Paywize Collection API for UPI and intent-based payment collection.

Last updated: 2026-02-21

Collection API

Overview

This guide helps you integrate Paywize's Collection services into your application securely and efficiently. Use our RESTful APIs to automate fund disbursements and payment collections with high reliability and speed. This documentation provides endpoints, security protocols, callback formats, and request/response samples.

Version: 1.0.0 Release Date: July 5, 2025 Base URL: https://merchant.paywize.in/api/collection/v1/

Security Measures

  • Authentication: All requests require a Bearer token in the Authorization header
  • IP Whitelisting: Only approved merchant IPs can access APIs and receive callbacks
  • Webhook HMAC: Every webhook payload is signed using a shared secret for integrity verification
  • 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 Collection 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 payment collection
async function initiatePayment(token) {
  const paymentData = {
    senderId: "TXN123456",
    txnType: "INTENT",
    vpa: "merchant@paywize",
    channel: "FINO",
    requestAmount: "100.50",
    remarks: "Payment123",
    callbackUrl: "https://your-webhook-url.com/callback"
  };

  const encryptedPayload = encryptMerchantData(paymentData, API_KEY, SECRET_KEY);

  const response = await fetch('https://merchant.paywize.in/api/collection/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 payment status
async function checkPaymentStatus(token, txnId) {
  const response = await fetch(
    `https://merchant.paywize.in/api/collection/v1/status?txnId=${txnId}`,
    {
      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 collectionWorkflow() {
  try {
    // Generate token
    const token = await generateAccessToken();
    console.log('✅ Token generated successfully');

    // Initiate payment
    const payment = await initiatePayment(token);
    console.log('✅ Payment initiated:', payment);
    console.log('Payment URL:', payment.paymentUrl);
    console.log('UPI Intent:', payment.intentUrl);

    // Check status
    const status = await checkPaymentStatus(token, payment.txnId);
    console.log('✅ Payment status:', status);

  } catch (error) {
    console.error('❌ Error:', error.message);
  }
}

// Run the workflow
collectionWorkflow();

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 Payment

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

Creates a new UPI payment intent for collecting payments.

View API Details →

3. Status Check

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

Check the current status of a payment transaction.

View API Details →

4. Webhook Notifications

POST https://merchant.paywize.in/api/collection/v1/webhook

Receive real-time payment status updates via webhooks.

View Webhook Details →

Transaction Status Values

StatusDescription
INITIATEDPayment request created, awaiting customer action
SUCCESSPayment completed successfully
FAILEDPayment failed
PENDINGPayment under review

Error Codes

Authentication Errors

CodeMessage
2000Access Token generated
4001Unauthorized access

Payment Initiation Errors

CodeMessage
2000Payment link generated
4001Invalid request format
4014Decryption failed. Please check the encryption
4008Unauthorized – invalid or expired token
4003Invalid senderId
4004Missing or invalid amount format
4005Missing or invalid txnType
4006Missing or invalid Callback URL
4007VPA not Registered
4010Transaction amount above maximum limit
4011Transaction amount below minimum limit
4012SenderId already exists
4013Daily limit Reached
4016No active settlement account found
4015Commercials are not yet configured and activated or channel/vpa do not match
5000Internal Server Error

Status Check Errors

CodeMessage
2000Transaction status fetched successfully
4000Either Transaction ID (txnId) or Sender ID (senderId) is required
4008Unauthorized – invalid or expired token
4104Transaction not found
4103Provide either senderId or txnId. Not both.
4105Missing or invalid txnId format
4107Unauthorized: Transaction does not belong to this merchant
5000Internal server error

Testing

Sandbox Environment

Use the sandbox environment for testing:

  • Base URL: https://sandbox.merchant.paywize.in/api/collection/v1/
  • Test Credentials: Contact support for sandbox API credentials
  • Test UPI: Use test VPAs provided by Paywize for testing

Postman Collection

Download our Postman collection for easy API testing: Download Postman Collection →

SDKs and Libraries

JavaScript/Node.js SDK

npm install @paywize/collection-api
import { PaywizeCollection } from '@paywize/collection-api';

const client = new PaywizeCollection({
  apiKey: 'your_api_key',
  secretKey: 'your_secret_key',
  environment: 'production' // or 'sandbox'
});

const payment = await client.initiate({
  senderId: 'TXN123456',
  requestAmount: '100.50',
  vpa: 'merchant@paywize',
  channel: 'FINO'
});

Python SDK

pip install paywize-collection
from paywize_collection import PaywizeCollection

client = PaywizeCollection(
    api_key='your_api_key',
    secret_key='your_secret_key',
    environment='production'  # or 'sandbox'
)

payment = client.initiate({
    'senderId': 'TXN123456',
    'requestAmount': '100.50',
    'vpa': 'merchant@paywize',
    'channel': 'FINO'
})

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: July 2025