Paywize Connected-Banking Collections API Documentation

Version: 1.0.0
Release Date: Jul 06, 2026

Overview

This guide helps you integrate Paywize's Connected Banking Collections services into your application securely and seamlessly. Using our RESTful APIs, you can manage virtual accounts, generate collection requests, receive real-time payment notifications, and reconcile incoming transactions with high reliability and speed. This documentation covers API endpoints, authentication and security mechanisms, webhook/callback formats, and detailed request and response examples to help you integrate collections efficiently.

Base URL

https://merchant.paywize.in

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

Encryption and Decryption

Encryption Process:

• Encrypt the data using AES-256-GCM encryption
• Derive the 32-byte encryption key by applying SHA-256 hash on your Secret Key
• Generate a random 12-byte nonce (IV) for each encryption operation
• Append the 16-byte GCM authentication tag at the end of the ciphertext
• Concatenate Nonce + Ciphertext + AuthTag and Base64 encode for transmission

Note: AES-256-GCM provides both encryption and integrity verification via the authentication tag. The nonce must be unique for every encryption call. The encoded payload format is: Base64(Nonce[12 bytes] + CipherText + AuthTag[16 bytes]).

JavaScript Encryption Code

import crypto from 'crypto';

export function encrypt(data, secretKey) {
  if (typeof data === 'object') {
    data = JSON.stringify(data);
  }
  const nonce = crypto.randomBytes(12); // 96-bit nonce — GCM recommended size
  const key = crypto.createHash('sha256').update(secretKey).digest();
  const cipher = crypto.createCipheriv('aes-256-gcm', key, nonce);
  const ciphertext = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
  const authTag = cipher.getAuthTag(); // 16-byte authentication tag

  // Payload format: Nonce (12 bytes) + CipherText + AuthTag (16 bytes)
  return Buffer.concat([nonce, ciphertext, authTag]).toString('base64');
}

JavaScript Decryption Code

import crypto from 'crypto';

export function decrypt(encryptedData, secretKey) {
  const combined = Buffer.from(encryptedData, 'base64');
  const NONCE_LEN = 12;
  const AUTH_TAG_LEN = 16;

  const nonce = combined.subarray(0, NONCE_LEN);
  const authTag = combined.subarray(combined.length - AUTH_TAG_LEN);
  const ciphertext = combined.subarray(NONCE_LEN, combined.length - AUTH_TAG_LEN);

  const key = crypto.createHash('sha256').update(secretKey).digest();
  const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce);
  decipher.setAuthTag(authTag);

  let decrypted = decipher.update(ciphertext, undefined, 'utf8');
  decrypted += decipher.final('utf8');
  return decrypted;
}