API Docs Back to site

Dashboard Sign Up

Authentication

Learn how to authenticate with Paywize APIs using JWT tokens.

Last updated: 2026-02-21

Authentication

Overview

All Paywize APIs use a unified authentication system that combines AES-256-CBC encryption with JWT Bearer tokens. This guide covers the authentication process used across all Paywize products including Collection API and Payout API.

Quick Reference

Attribute	Details
Token Type	JWT Bearer Token
Token Expiry	5 minutes
Encryption	AES-256-CBC required
Endpoint	`POST merchant.paywize.in/v1/auth/clients/token`
Rate Limit	100 requests/minute
Security	HTTPS only, IP whitelisting

Security Measures

Authentication: All requests require a Bearer token in the Authorization header
Encryption: Request/response data encrypted using AES-256-CBC
IP Whitelisting: Only approved merchant IPs can access APIs and receive callbacks
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

Token Generation

Generate Access Token

Description: This API endpoint generates a temporary JWT access token to authenticate all subsequent API requests. The request body must be AES-256-CBC encrypted and Base64 encoded. Tokens expire after 5 minutes and must be regenerated regularly.

Request Headers

Content-Type: application/json

Request Body (Before Encryption)

{
  "apiKey": "MshTymhj6llgEhzpJ5s0M9gI3soYz82h",
  "secretKey": "QI8zFZWX272Z0Unb"
}

Request Body (After Encryption)

{
  "payload": "0oA+t8GGuDZ0FrEbhM9bZ2pxTDZasdasdasasdjqwuhenqwj^7y="
}

Success Response (200 OK)

{
  "respCode": 2000,
  "respMessage": "Token generated successfully",
  "data": "nqiNrwBEk770qbQ3tyn1MY2QzYSa0N8qmGSp/W0AtOs8",
  "expiresIn": 300,
  "tokenType": "Bearer"
}

Decrypted Token Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response Codes

Success Response

Code	Message
`2000`	Access Token generated

Client Error Responses

Code	Message	Description
`4001`	Unauthorized access	Invalid API key or secret key

Using Bearer Tokens

Once you have obtained a JWT token, include it in the Authorization header of all API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWF2QT4fwpMeJf36POk6yJV_adQssw5c

Token Expiry

Expiry Time: 5 minutes (300 seconds)
Renewal: Generate new tokens before expiry
Best Practice: Implement automatic token refresh in your application

Implementation Example

JavaScript

// Generate access token
async function generateAccessToken() {
  const credentials = {
    apiKey: "your_api_key",
    secretKey: "your_secret_key"
  };

  // Encrypt the credentials
  const encryptedPayload = encryptMerchantData(
    JSON.stringify(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) {
    // Decrypt the token data
    const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
    const tokenData = JSON.parse(decryptedData);
    return tokenData.token;
  }

  throw new Error(result.respMessage);
}

// Use token in API calls
async function makeAuthenticatedRequest(endpoint, data, token) {
  const encryptedPayload = encryptMerchantData(
    JSON.stringify(data),
    API_KEY,
    SECRET_KEY
  );

  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      payload: encryptedPayload
    })
  });

  return response.json();
}

Python

import requests
import json
from encryption_utils import encrypt_merchant_data, decrypt_merchant_data

def generate_access_token(api_key, secret_key):
    credentials = {
        "apiKey": api_key,
        "secretKey": secret_key
    }

    # Encrypt the credentials
    encrypted_payload = encrypt_merchant_data(
        json.dumps(credentials),
        api_key,
        secret_key
    )

    response = requests.post(
        'https://merchant.paywize.in/v1/auth/clients/token',
        headers={'Content-Type': 'application/json'},
        json={'payload': encrypted_payload}
    )

    result = response.json()

    if result['respCode'] == 2000:
        # Decrypt the token data
        decrypted_data = decrypt_merchant_data(result['data'], api_key, secret_key)
        token_data = json.loads(decrypted_data)
        return token_data['token']

    raise Exception(result['respMessage'])

def make_authenticated_request(endpoint, data, token, api_key, secret_key):
    encrypted_payload = encrypt_merchant_data(
        json.dumps(data),
        api_key,
        secret_key
    )

    response = requests.post(
        endpoint,
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {token}'
        },
        json={'payload': encrypted_payload}
    )

    return response.json()

Security Best Practices

Store Credentials Securely: Never hardcode API keys in your source code
Use Environment Variables: Store credentials in environment variables or secure configuration files
Implement Token Caching: Cache tokens and refresh before expiry to avoid unnecessary API calls
Handle Token Expiry: Implement automatic token refresh when receiving 401 Unauthorized responses
Use HTTPS Only: All API communications must use HTTPS
IP Whitelisting: Ensure your server IPs are whitelisted with Paywize
Validate Responses: Always validate API responses and handle errors appropriately

Error Handling

Always implement proper error handling for authentication:

async function authenticatedApiCall(endpoint, data) {
  let token = await getStoredToken();

  try {
    const response = await makeAuthenticatedRequest(endpoint, data, token);

    if (response.respCode === 4008) { // Unauthorized
      // Token expired, generate new one
      token = await generateAccessToken();
      storeToken(token);
      return await makeAuthenticatedRequest(endpoint, data, token);
    }

    return response;
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Next Steps

Learn about Encryption and Decryption used across all APIs
Explore Collection API documentation
Explore Payout API documentation

PreviousWebhook for Collection

NextEncryption (V1)

Authentication

Learn how to authenticate with Paywize APIs using JWT tokens.

Last updated: 2026-02-21

Authentication

Overview

Quick Reference

Attribute	Details
Token Type	JWT Bearer Token
Token Expiry	5 minutes
Encryption	AES-256-CBC required
Endpoint	`POST merchant.paywize.in/v1/auth/clients/token`
Rate Limit	100 requests/minute
Security	HTTPS only, IP whitelisting

Security Measures

Authentication: All requests require a Bearer token in the Authorization header
Encryption: Request/response data encrypted using AES-256-CBC
IP Whitelisting: Only approved merchant IPs can access APIs and receive callbacks
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

Token Generation

Generate Access Token

Request Headers

Content-Type: application/json

Request Body (Before Encryption)

{
  "apiKey": "MshTymhj6llgEhzpJ5s0M9gI3soYz82h",
  "secretKey": "QI8zFZWX272Z0Unb"
}

Request Body (After Encryption)

{
  "payload": "0oA+t8GGuDZ0FrEbhM9bZ2pxTDZasdasdasasdjqwuhenqwj^7y="
}

Success Response (200 OK)

{
  "respCode": 2000,
  "respMessage": "Token generated successfully",
  "data": "nqiNrwBEk770qbQ3tyn1MY2QzYSa0N8qmGSp/W0AtOs8",
  "expiresIn": 300,
  "tokenType": "Bearer"
}

Decrypted Token Response

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Response Codes

Success Response

Code	Message
`2000`	Access Token generated

Client Error Responses

Code	Message	Description
`4001`	Unauthorized access	Invalid API key or secret key

Using Bearer Tokens

Once you have obtained a JWT token, include it in the Authorization header of all API requests:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWF2QT4fwpMeJf36POk6yJV_adQssw5c

Token Expiry

Expiry Time: 5 minutes (300 seconds)
Renewal: Generate new tokens before expiry
Best Practice: Implement automatic token refresh in your application

Implementation Example

JavaScript

// Generate access token
async function generateAccessToken() {
  const credentials = {
    apiKey: "your_api_key",
    secretKey: "your_secret_key"
  };

  // Encrypt the credentials
  const encryptedPayload = encryptMerchantData(
    JSON.stringify(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) {
    // Decrypt the token data
    const decryptedData = decryptMerchantData(result.data, API_KEY, SECRET_KEY);
    const tokenData = JSON.parse(decryptedData);
    return tokenData.token;
  }

  throw new Error(result.respMessage);
}

// Use token in API calls
async function makeAuthenticatedRequest(endpoint, data, token) {
  const encryptedPayload = encryptMerchantData(
    JSON.stringify(data),
    API_KEY,
    SECRET_KEY
  );

  const response = await fetch(endpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      payload: encryptedPayload
    })
  });

  return response.json();
}

Python

import requests
import json
from encryption_utils import encrypt_merchant_data, decrypt_merchant_data

def generate_access_token(api_key, secret_key):
    credentials = {
        "apiKey": api_key,
        "secretKey": secret_key
    }

    # Encrypt the credentials
    encrypted_payload = encrypt_merchant_data(
        json.dumps(credentials),
        api_key,
        secret_key
    )

    response = requests.post(
        'https://merchant.paywize.in/v1/auth/clients/token',
        headers={'Content-Type': 'application/json'},
        json={'payload': encrypted_payload}
    )

    result = response.json()

    if result['respCode'] == 2000:
        # Decrypt the token data
        decrypted_data = decrypt_merchant_data(result['data'], api_key, secret_key)
        token_data = json.loads(decrypted_data)
        return token_data['token']

    raise Exception(result['respMessage'])

def make_authenticated_request(endpoint, data, token, api_key, secret_key):
    encrypted_payload = encrypt_merchant_data(
        json.dumps(data),
        api_key,
        secret_key
    )

    response = requests.post(
        endpoint,
        headers={
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {token}'
        },
        json={'payload': encrypted_payload}
    )

    return response.json()

Security Best Practices

Store Credentials Securely: Never hardcode API keys in your source code
Use Environment Variables: Store credentials in environment variables or secure configuration files
Implement Token Caching: Cache tokens and refresh before expiry to avoid unnecessary API calls
Handle Token Expiry: Implement automatic token refresh when receiving 401 Unauthorized responses
Use HTTPS Only: All API communications must use HTTPS
IP Whitelisting: Ensure your server IPs are whitelisted with Paywize
Validate Responses: Always validate API responses and handle errors appropriately

Error Handling

Always implement proper error handling for authentication:

async function authenticatedApiCall(endpoint, data) {
  let token = await getStoredToken();

  try {
    const response = await makeAuthenticatedRequest(endpoint, data, token);

    if (response.respCode === 4008) { // Unauthorized
      // Token expired, generate new one
      token = await generateAccessToken();
      storeToken(token);
      return await makeAuthenticatedRequest(endpoint, data, token);
    }

    return response;
  } catch (error) {
    console.error('API call failed:', error);
    throw error;
  }
}

Next Steps

Learn about Encryption and Decryption used across all APIs
Explore Collection API documentation
Explore Payout API documentation

PreviousWebhook for Collection

NextEncryption (V1)