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:
- 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 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.
2. Initiate Payment
POST https://merchant.paywize.in/api/collection/v1/initiate/
Creates a new UPI payment intent for collecting payments.
3. Status Check
GET https://merchant.paywize.in/api/collection/v1/status
Check the current status of a payment transaction.
4. Webhook Notifications
POST https://merchant.paywize.in/api/collection/v1/webhook
Receive real-time payment status updates via webhooks.
Transaction Status Values
| Status | Description |
|---|---|
| INITIATED | Payment request created, awaiting customer action |
| SUCCESS | Payment completed successfully |
| FAILED | Payment failed |
| PENDING | Payment under review |
Error Codes
Authentication Errors
| Code | Message |
|---|---|
| 2000 | Access Token generated |
| 4001 | Unauthorized access |
Payment Initiation Errors
| 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 |
Status Check Errors
| 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 |
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
- 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: July 2025