Loading...
Loading...
Integrate Paywize Collection API for UPI and intent-based payment collection.
Last updated: 2026-02-21
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/collection/v1/
All Collection API requests use shared authentication and encryption:
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/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/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/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();
POST merchant.paywize.in/v1/auth/clients/token
Generate a JWT access token for authenticating API requests. Tokens expire after 5 minutes.
POST https://merchant.paywize.in/collection/v1/initiate/
Creates a new UPI payment intent for collecting payments.
GET https://merchant.paywize.in/collection/v1/status
Check the current status of a payment transaction.
POST https://merchant.paywize.in/collection/v1/webhook
Receive real-time payment status updates via webhooks.
| Status | Description |
|---|---|
| INITIATED | Payment request created, awaiting customer action |
| SUCCESS | Payment completed successfully |
| FAILED | Payment failed |
| PENDING | Payment under review |
| Code | Message |
|---|---|
| 2000 | Access Token generated |
| 4001 | Unauthorized access |
| Code | Message |
|---|---|
| 2000 | Payment link generated |
| 4001 | Invalid request format |
| 4014 | Decryption failed. Please check the encryption |
| 4008 | Unauthorized – invalid or expired token |
| 4003 | Invalid senderId |
| 4004 | Missing or invalid amount format |
| 4005 | Missing or invalid txnType |
| 4006 | Missing or invalid Callback URL |
| 4007 | VPA not Registered |
| 4010 | Transaction amount above maximum limit |
| 4011 | Transaction amount below minimum limit |
| 4012 | SenderId already exists |
| 4013 | Daily limit Reached |
| 4016 | No active settlement account found |
| 4015 | Commercials are not yet configured and activated or channel/vpa do not match |
| 5000 | Internal Server Error |
| Code | Message |
|---|---|
| 2000 | Transaction status fetched successfully |
| 4000 | Either Transaction ID (txnId) or Sender ID (senderId) is required |
| 4008 | Unauthorized – invalid or expired token |
| 4104 | Transaction not found |
| 4103 | Provide either senderId or txnId. Not both. |
| 4105 | Missing or invalid txnId format |
| 4107 | Unauthorized: Transaction does not belong to this merchant |
| 5000 | Internal server error |
Use the sandbox environment for testing:
https://sandbox.merchant.paywize.in/collection/v1/Download our Postman collection for easy API testing: Download Postman Collection →
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'
});
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'
})
Get Started with API Credentials →
Version 1.0.0 | Last Updated: July 2025