Paywize Connected-Banking API Documentation

Version: 1.0.2
Release Date: May 20, 2026

Overview

This guide helps you integrate Paywize's Connected Banking services into your application securely and seamlessly. Using our RESTful APIs, you can connect bank accounts, fetch real-time balances, and enable automated fund disbursements with high reliability and speed. This documentation covers API endpoints, security and consent mechanisms, webhook/callback formats, and detailed request and response samples.

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;
}