Merchant SDKs

Official Paywize merchant SDKs for Node.js, Python, and Java. Simplify V2 AES-256-GCM encryption integration with pre-built libraries.

Last updated: 2026-03-16

Merchant SDKs

Overview

Paywize provides official SDKs for Node.js, Python, and Java that handle AES-256-GCM encryption and decryption out of the box. Instead of implementing cryptographic operations yourself, use these pre-built libraries to encrypt request payloads and decrypt API responses with a single function call.

Each SDK provides:

Class-based usage with a reusable instance bound to your secret key
Standalone functions for one-off encrypt/decrypt operations
JSON helpers that serialize and deserialize objects automatically
V2 encryption format using AES-256-GCM with random nonces and 128-bit auth tags

Why use the SDK?

The SDKs eliminate common integration mistakes such as incorrect nonce generation, missing auth tags, and wrong Base64 encoding. They are tested against the Paywize backend and kept in sync with API changes.

Installation

npm install @paywize/merchant-crypto

pip install paywize-crypto

<!-- Maven dependency — add to your pom.xml -->
<dependency>
  <groupId>com.paywize</groupId>
  <artifactId>merchant-crypto</artifactId>
  <version>2.0.0</version>
</dependency>

Quick Start

const { PaywizeCrypto } = require('@paywize/merchant-crypto');

// Create an instance with your secret key from the Paywize dashboard
const crypto = new PaywizeCrypto('your_secret_key_here');

// Encrypt a plaintext string
const encrypted = crypto.encrypt('Hello, Paywize!');
console.log('Encrypted:', encrypted);

// Decrypt back to plaintext
const decrypted = crypto.decrypt(encrypted);
console.log('Decrypted:', decrypted);

// Encrypt a JSON object directly
const payload = { senderId: 'TXN123', amount: '500.00' };
const encryptedJSON = crypto.encryptJSON(payload);
console.log('Encrypted JSON:', encryptedJSON);

// Decrypt back to an object
const decryptedObj = crypto.decryptJSON(encryptedJSON);
console.log('Decrypted object:', decryptedObj);

from paywize_crypto import PaywizeCrypto

# Create an instance with your secret key from the Paywize dashboard
crypto = PaywizeCrypto("your_secret_key_here")

# Encrypt a plaintext string
encrypted = crypto.encrypt("Hello, Paywize!")
print("Encrypted:", encrypted)

# Decrypt back to plaintext
decrypted = crypto.decrypt(encrypted)
print("Decrypted:", decrypted)

# Encrypt a dict directly
payload = {"senderId": "TXN123", "amount": "500.00"}
encrypted_json = crypto.encrypt_json(payload)
print("Encrypted JSON:", encrypted_json)

# Decrypt back to a dict
decrypted_obj = crypto.decrypt_json(encrypted_json)
print("Decrypted object:", decrypted_obj)

import com.paywize.crypto.PaywizeCrypto;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // Create an instance with your secret key from the Paywize dashboard
        PaywizeCrypto crypto = new PaywizeCrypto("your_secret_key_here");

        // Encrypt a plaintext string
        String encrypted = crypto.encrypt("Hello, Paywize!");
        System.out.println("Encrypted: " + encrypted);

        // Decrypt back to plaintext
        String decrypted = crypto.decrypt(encrypted);
        System.out.println("Decrypted: " + decrypted);

        // Encrypt a JSON object directly
        String payload = "{\"senderId\":\"TXN123\",\"amount\":\"500.00\"}";
        String encryptedJSON = crypto.encryptJSON(payload);
        System.out.println("Encrypted JSON: " + encryptedJSON);

        // Decrypt back to an object
        String decryptedObj = crypto.decryptJSON(encryptedJSON);
        System.out.println("Decrypted object: " + decryptedObj);
    }
}

API Reference

Constructor

Language	Constructor	Parameter
Node.js	`new PaywizeCrypto(secretKey)`	Your secret key from the Paywize dashboard
Python	`PaywizeCrypto(secret_key)`	Your secret key from the Paywize dashboard
Java	`new PaywizeCrypto(secretKey)`	Your secret key from the Paywize dashboard

The constructor derives a 32-byte AES key from your secret key using SHA-256 and stores it on the instance. All subsequent calls to encrypt and decrypt reuse this derived key.

Instance Methods

Method	Description	Input	Output
`encrypt(plaintext)`	Encrypt a UTF-8 string	`string`	Base64-encoded string
`decrypt(encoded)`	Decrypt a Base64 string	Base64-encoded string	`string`
`encryptJSON(obj)` / `encrypt_json(dict)`	Serialize an object to JSON, then encrypt	`object` / `dict`	Base64-encoded string
`decryptJSON(encoded)` / `decrypt_json(str)`	Decrypt, then parse the JSON result	Base64-encoded string	`object` / `dict`

Python methods use snake_case (encrypt_json, decrypt_json). Node.js and Java methods use camelCase (encryptJSON, decryptJSON). The underlying behavior is identical across all three SDKs.

Standalone Functions

If you prefer not to create a class instance, each SDK also exports standalone functions that accept the secret key as an argument.

const { encrypt, decrypt, encryptJSON, decryptJSON } = require('@paywize/merchant-crypto');

const secretKey = 'your_secret_key_here';

// Encrypt a string
const encoded = encrypt('sensitive data', secretKey);

// Decrypt a string
const decoded = decrypt(encoded, secretKey);

// Encrypt an object
const obj = { orderId: 'ORD-001', amount: '250.00' };
const encodedObj = encryptJSON(obj, secretKey);

// Decrypt to an object
const decodedObj = decryptJSON(encodedObj, secretKey);

from paywize_crypto import encrypt, decrypt, encrypt_json, decrypt_json

secret_key = "your_secret_key_here"

# Encrypt a string
encoded = encrypt("sensitive data", secret_key)

# Decrypt a string
decoded = decrypt(encoded, secret_key)

# Encrypt a dict
obj = {"orderId": "ORD-001", "amount": "250.00"}
encoded_obj = encrypt_json(obj, secret_key)

# Decrypt to a dict
decoded_obj = decrypt_json(encoded_obj, secret_key)

import com.paywize.crypto.CryptoUtils;

public class StandaloneExample {
    public static void main(String[] args) throws Exception {
        String secretKey = "your_secret_key_here";

        // Encrypt a string
        String encoded = CryptoUtils.encrypt("sensitive data", secretKey);

        // Decrypt a string
        String decoded = CryptoUtils.decrypt(encoded, secretKey);

        // Encrypt a JSON string
        String json = "{\"orderId\":\"ORD-001\",\"amount\":\"250.00\"}";
        String encodedObj = CryptoUtils.encryptJSON(json, secretKey);

        // Decrypt to a JSON string
        String decodedObj = CryptoUtils.decryptJSON(encodedObj, secretKey);
    }
}

Encryption Internals

All three SDKs implement the same V2 encryption scheme. This section describes the internal steps so you can verify compatibility or build a custom implementation if needed.

Step	Detail
Key derivation	`SHA-256(secretKey)` produces a 32-byte (256-bit) AES key
Nonce	12 cryptographically random bytes generated per operation
Cipher	AES-256-GCM
Auth tag	16 bytes (128-bit) appended after the ciphertext
Output format	`base64(nonce \|\| ciphertext \|\| authTag)`

Breakdown of the encoded output:

base64(
  [12 bytes nonce] + [N bytes ciphertext] + [16 bytes authTag]
)

The nonce is unique per encryption call, ensuring that identical plaintexts produce different ciphertexts.
The auth tag provides authenticated encryption -- any tampering with the ciphertext or nonce causes decryption to fail.
The final result is a single Base64 string safe for JSON transport.

Do not reuse nonces

The SDKs generate a fresh 12-byte random nonce for every encrypt call. If you build a custom implementation, you must guarantee nonce uniqueness. Reusing a nonce with the same key under GCM completely breaks confidentiality and authenticity.

Requirements

SDK	Runtime	Dependencies
Node.js	Node.js >= 16	None (uses built-in `crypto` module)
Python	Python >= 3.8	`cryptography >= 3.0`
Java	Java >= 11	None (uses `javax.crypto`)

The Node.js and Java SDKs have zero external dependencies -- they rely entirely on the standard library. The Python SDK depends on the widely-used cryptography package, which is automatically installed when you pip install paywize-crypto.

Source Code

The Paywize Merchant SDKs are distributed through their respective package managers:

Node.js: @paywize/merchant-crypto on npm
Python: paywize-crypto on PyPI
Java: com.paywize:merchant-crypto on Maven Central

For source code access or enterprise licensing inquiries, contact developer-support@paywize.in.

Next Steps

V2 Encryption Guide -- Full details on the AES-256-GCM encryption protocol
Authentication -- JWT token generation and usage
Collection API -- Accept payments via UPI and intent flows
Payout API -- Disburse funds to bank accounts and wallets

PreviousEncryption V2 (AES-256-GCM)

NextChangelog

Merchant SDKs

Official Paywize merchant SDKs for Node.js, Python, and Java. Simplify V2 AES-256-GCM encryption integration with pre-built libraries.

Last updated: 2026-03-16

Merchant SDKs

Overview

Each SDK provides:

Class-based usage with a reusable instance bound to your secret key
Standalone functions for one-off encrypt/decrypt operations
JSON helpers that serialize and deserialize objects automatically
V2 encryption format using AES-256-GCM with random nonces and 128-bit auth tags

Why use the SDK?

Installation

npm install @paywize/merchant-crypto

pip install paywize-crypto

<!-- Maven dependency — add to your pom.xml -->
<dependency>
  <groupId>com.paywize</groupId>
  <artifactId>merchant-crypto</artifactId>
  <version>2.0.0</version>
</dependency>

Quick Start

const { PaywizeCrypto } = require('@paywize/merchant-crypto');

// Create an instance with your secret key from the Paywize dashboard
const crypto = new PaywizeCrypto('your_secret_key_here');

// Encrypt a plaintext string
const encrypted = crypto.encrypt('Hello, Paywize!');
console.log('Encrypted:', encrypted);

// Decrypt back to plaintext
const decrypted = crypto.decrypt(encrypted);
console.log('Decrypted:', decrypted);

// Encrypt a JSON object directly
const payload = { senderId: 'TXN123', amount: '500.00' };
const encryptedJSON = crypto.encryptJSON(payload);
console.log('Encrypted JSON:', encryptedJSON);

// Decrypt back to an object
const decryptedObj = crypto.decryptJSON(encryptedJSON);
console.log('Decrypted object:', decryptedObj);

from paywize_crypto import PaywizeCrypto

# Create an instance with your secret key from the Paywize dashboard
crypto = PaywizeCrypto("your_secret_key_here")

# Encrypt a plaintext string
encrypted = crypto.encrypt("Hello, Paywize!")
print("Encrypted:", encrypted)

# Decrypt back to plaintext
decrypted = crypto.decrypt(encrypted)
print("Decrypted:", decrypted)

# Encrypt a dict directly
payload = {"senderId": "TXN123", "amount": "500.00"}
encrypted_json = crypto.encrypt_json(payload)
print("Encrypted JSON:", encrypted_json)

# Decrypt back to a dict
decrypted_obj = crypto.decrypt_json(encrypted_json)
print("Decrypted object:", decrypted_obj)

import com.paywize.crypto.PaywizeCrypto;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // Create an instance with your secret key from the Paywize dashboard
        PaywizeCrypto crypto = new PaywizeCrypto("your_secret_key_here");

        // Encrypt a plaintext string
        String encrypted = crypto.encrypt("Hello, Paywize!");
        System.out.println("Encrypted: " + encrypted);

        // Decrypt back to plaintext
        String decrypted = crypto.decrypt(encrypted);
        System.out.println("Decrypted: " + decrypted);

        // Encrypt a JSON object directly
        String payload = "{\"senderId\":\"TXN123\",\"amount\":\"500.00\"}";
        String encryptedJSON = crypto.encryptJSON(payload);
        System.out.println("Encrypted JSON: " + encryptedJSON);

        // Decrypt back to an object
        String decryptedObj = crypto.decryptJSON(encryptedJSON);
        System.out.println("Decrypted object: " + decryptedObj);
    }
}

API Reference

Constructor

Language	Constructor	Parameter
Node.js	`new PaywizeCrypto(secretKey)`	Your secret key from the Paywize dashboard
Python	`PaywizeCrypto(secret_key)`	Your secret key from the Paywize dashboard
Java	`new PaywizeCrypto(secretKey)`	Your secret key from the Paywize dashboard

The constructor derives a 32-byte AES key from your secret key using SHA-256 and stores it on the instance. All subsequent calls to encrypt and decrypt reuse this derived key.

Instance Methods

Method	Description	Input	Output
`encrypt(plaintext)`	Encrypt a UTF-8 string	`string`	Base64-encoded string
`decrypt(encoded)`	Decrypt a Base64 string	Base64-encoded string	`string`
`encryptJSON(obj)` / `encrypt_json(dict)`	Serialize an object to JSON, then encrypt	`object` / `dict`	Base64-encoded string
`decryptJSON(encoded)` / `decrypt_json(str)`	Decrypt, then parse the JSON result	Base64-encoded string	`object` / `dict`

Standalone Functions

If you prefer not to create a class instance, each SDK also exports standalone functions that accept the secret key as an argument.

const { encrypt, decrypt, encryptJSON, decryptJSON } = require('@paywize/merchant-crypto');

const secretKey = 'your_secret_key_here';

// Encrypt a string
const encoded = encrypt('sensitive data', secretKey);

// Decrypt a string
const decoded = decrypt(encoded, secretKey);

// Encrypt an object
const obj = { orderId: 'ORD-001', amount: '250.00' };
const encodedObj = encryptJSON(obj, secretKey);

// Decrypt to an object
const decodedObj = decryptJSON(encodedObj, secretKey);

from paywize_crypto import encrypt, decrypt, encrypt_json, decrypt_json

secret_key = "your_secret_key_here"

# Encrypt a string
encoded = encrypt("sensitive data", secret_key)

# Decrypt a string
decoded = decrypt(encoded, secret_key)

# Encrypt a dict
obj = {"orderId": "ORD-001", "amount": "250.00"}
encoded_obj = encrypt_json(obj, secret_key)

# Decrypt to a dict
decoded_obj = decrypt_json(encoded_obj, secret_key)

import com.paywize.crypto.CryptoUtils;

public class StandaloneExample {
    public static void main(String[] args) throws Exception {
        String secretKey = "your_secret_key_here";

        // Encrypt a string
        String encoded = CryptoUtils.encrypt("sensitive data", secretKey);

        // Decrypt a string
        String decoded = CryptoUtils.decrypt(encoded, secretKey);

        // Encrypt a JSON string
        String json = "{\"orderId\":\"ORD-001\",\"amount\":\"250.00\"}";
        String encodedObj = CryptoUtils.encryptJSON(json, secretKey);

        // Decrypt to a JSON string
        String decodedObj = CryptoUtils.decryptJSON(encodedObj, secretKey);
    }
}

Encryption Internals

All three SDKs implement the same V2 encryption scheme. This section describes the internal steps so you can verify compatibility or build a custom implementation if needed.

Step	Detail
Key derivation	`SHA-256(secretKey)` produces a 32-byte (256-bit) AES key
Nonce	12 cryptographically random bytes generated per operation
Cipher	AES-256-GCM
Auth tag	16 bytes (128-bit) appended after the ciphertext
Output format	`base64(nonce \|\| ciphertext \|\| authTag)`

Breakdown of the encoded output:

base64(
  [12 bytes nonce] + [N bytes ciphertext] + [16 bytes authTag]
)

The nonce is unique per encryption call, ensuring that identical plaintexts produce different ciphertexts.
The auth tag provides authenticated encryption -- any tampering with the ciphertext or nonce causes decryption to fail.
The final result is a single Base64 string safe for JSON transport.

Do not reuse nonces

Requirements

SDK	Runtime	Dependencies
Node.js	Node.js >= 16	None (uses built-in `crypto` module)
Python	Python >= 3.8	`cryptography >= 3.0`
Java	Java >= 11	None (uses `javax.crypto`)

Source Code

The Paywize Merchant SDKs are distributed through their respective package managers:

Node.js: @paywize/merchant-crypto on npm
Python: paywize-crypto on PyPI
Java: com.paywize:merchant-crypto on Maven Central

For source code access or enterprise licensing inquiries, contact developer-support@paywize.in.

Next Steps

V2 Encryption Guide -- Full details on the AES-256-GCM encryption protocol
Authentication -- JWT token generation and usage
Collection API -- Accept payments via UPI and intent flows
Payout API -- Disburse funds to bank accounts and wallets

PreviousEncryption V2 (AES-256-GCM)

NextChangelog