Paywize LogoPaywize

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

AttributeDetails
Token TypeJWT Bearer Token
Token Expiry5 minutes
EncryptionAES-256-CBC required
EndpointPOST merchant.paywize.in/api/v1/auth/clients/token
Rate Limit100 requests/minute
SecurityHTTPS 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

CodeMessage
2000Access Token generated

Client Error Responses

CodeMessageDescription
4001Unauthorized accessInvalid 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/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) {
    // 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/api/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

  1. Store Credentials Securely: Never hardcode API keys in your source code
  2. Use Environment Variables: Store credentials in environment variables or secure configuration files
  3. Implement Token Caching: Cache tokens and refresh before expiry to avoid unnecessary API calls
  4. Handle Token Expiry: Implement automatic token refresh when receiving 401 Unauthorized responses
  5. Use HTTPS Only: All API communications must use HTTPS
  6. IP Whitelisting: Ensure your server IPs are whitelisted with Paywize
  7. 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

PreviousWebhook for Collection
NextEncryption