Getting Started

Welcome to the Paywize Platform! This guide will help you understand our payment infrastructure and get started with the right product for your needs.

Platform Overview

Paywize provides a complete payment infrastructure with three core products:

Quick Decision Guide

Choose the right product based on your use case:

Use Payout API When:

• Sending money to vendors, employees, or customers
• Processing refunds and cashbacks
• Bulk salary payments
• Marketplace seller payouts
• Insurance claim settlements

Use Collection API When:

• Accepting payments from customers
• E-commerce payment processing
• Subscription billing
• Invoice payments
• Donation collection

Use Connected Banking When:

• Verifying customer bank accounts
• KYC and compliance requirements
• Account balance verification
• Transaction history analysis
• Virtual Account Management (VAM)

Prerequisites

Before you start, ensure you have:

1. Active Paywize Account: Sign up at dashboard.paywize.in
2. API Credentials: Get your API key and secret key from the dashboard
3. Development Environment: Set up your preferred programming environment
4. Webhook Endpoint: Prepare an HTTPS endpoint for receiving notifications

Integration Steps

1. Account Setup

1. Create Account: Visit our dashboard and create your merchant account
2. Complete KYC: Submit required documents for verification
3. Get API Credentials: Generate your API key and secret key from the dashboard

2. Environment Setup

Production Environment

Base URL: https://merchant.paywize.in/api/
Dashboard: https://dashboard.paywize.in

Sandbox Environment

Base URL: https://sandbox.merchant.paywize.in/api/
Dashboard: https://sandbox-dashboard.paywize.in

3. Authentication & Encryption

All Paywize APIs use unified authentication and encryption:

• Authentication: JWT tokens with 5-minute expiry
• Encryption: AES-256-CBC encryption for all data
• Base URL: https://merchant.paywize.in/api/

Detailed Guides:

• Authentication Guide - Learn JWT token generation
• Encryption Guide - Learn AES-256-CBC implementation

Quick Authentication Example

import crypto from 'crypto';

// Encryption function (shared across all APIs)
function encryptMerchantData(data, key, iv) {
  if (typeof data === 'object') {
    data = JSON.stringify(data);
  }
  const cipher = crypto.createCipheriv('aes-256-cbc', key, iv);
  const encrypted = Buffer.concat([cipher.update(data, 'utf8'), cipher.final()]);
  return encrypted.toString('base64');
}

// Generate access token
async function generateAccessToken() {
  const credentials = {
    apiKey: 'your_32_char_api_key_here_123456',
    secretKey: 'your_16_char_iv_12'
  };

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

4. Make Your First API Call

Payout API Example

// Step 1: Generate token
const token = await generateAccessToken();

// Step 2: Initiate payout
const payoutData = {
  sender_id: "unique_transaction_id",
  wallet_id: "PAYWIZE12345679",
  payment_mode: "IMPS",
  beneficiary_name: "John Doe",
  beneficiary_acc_number: "123456789012",
  beneficiary_ifsc: "HDFC0001234",
  amount: 1000,
  remarks: "Payment",
  callback_url: "https://your-website.com/webhook/payout"
};

const encryptedPayload = encryptMerchantData(payoutData, API_KEY, SECRET_KEY);

const response = await fetch('https://merchant.paywize.in/api/payout/v1/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ payload: encryptedPayload })
});

Collection API Example

// Step 1: Generate token (same as above)
const token = await generateAccessToken();

// Step 2: Initiate collection
const collectionData = {
  senderId: "unique_sender_id",
  requestAmount: "500.00",
  vpa: "merchant@paywize",
  callbackUrl: "https://your-website.com/webhook/collection"
};

const encryptedPayload = encryptMerchantData(collectionData, API_KEY, SECRET_KEY);

const response = await fetch('https://merchant.paywize.in/api/collection/v1/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({ payload: encryptedPayload })
});

Security Best Practices

1. API Credentials: Never expose API secrets in client-side code
2. HTTPS Only: Always use HTTPS for API requests
3. Token Management: Implement proper token refresh logic (5-minute expiry)
4. Encryption: Always encrypt request/response data using AES-256-CBC
5. Webhook Security: Verify webhook signatures
6. Error Handling: Implement proper error handling and retry logic

Testing

Sandbox Environment

Use our sandbox environment for testing:

• Base URL: https://sandbox.merchant.paywize.in/api/
• No real money: All transactions are simulated
• Test credentials: Use sandbox API credentials
• Test accounts: Use provided test bank accounts

Test Bank Accounts

// Test bank account (always successful)
{
  account_number: "1234567890",
  ifsc: "TEST0001234",
  name: "Test Account"
}

// Test bank account (always fails)
{
  account_number: "9876543210",
  ifsc: "TEST0001234",
  name: "Test Fail Account"
}

Webhooks

Set up webhooks for real-time notifications:

1. Per-transaction Setup: Provide callback_url in each API request
2. HTTPS Endpoints: Ensure webhook URLs use HTTPS
3. Signature Verification: Always verify webhook signatures
4. Idempotency: Handle duplicate webhook deliveries
5. Quick Response: Return 200 OK within 30 seconds

Common Integration Patterns

1. E-commerce Platform

• Use Collection API for customer payments
• Use Payout API for vendor settlements
• Use Connected Banking for verification

2. Marketplace

• Use Collection API for buyer payments
• Use Payout API for seller payouts
• Use Connected Banking for seller onboarding

3. Fintech Application

• Use all APIs for comprehensive financial services
• Start with Collection and Payout APIs
• Add Connected Banking for comprehensive financial services

Error Handling

Implement robust error handling:

try {
  const response = await fetch(apiUrl, options);
  const data = await response.json();

  if (data.respCode !== 2000) {
    throw new Error(`API Error ${data.respCode}: ${data.respMessage}`);
  }

  // Decrypt response data
  const decryptedData = decryptMerchantData(data.data, API_KEY, SECRET_KEY);
  return JSON.parse(decryptedData);
} catch (error) {
  console.error('API call failed:', error);
  // Implement retry logic or fallback
}

Next Steps

Get Started with Available APIs

1. Payout API Quick Start - Start sending money instantly
2. Collection API Quick Start - Start accepting payments

Learn Core Concepts

1. Authentication Guide - Master JWT token generation
2. Encryption Guide - Implement AES-256-CBC encryption

Explore More

1. Connected Banking Overview - Multi-bank integration APIs

Support

Need help? We're here to assist:

• Technical Support: developer-support@paywize.in
• Business Queries: business@paywize.in
• Documentation Issues: docs@paywize.in

Resources

• Developer Portal: https://developer.paywize.in
• Status Page: https://status.paywize.in
• Community Forum: https://community.paywize.in

Rate Limits

All APIs have rate limits to ensure fair usage:

• Token Generation: 10 requests per minute
• API Calls: 1000 requests per minute (varies by endpoint)
• Webhook Retries: 5 attempts with exponential backoff

Monitor your usage through the dashboard and implement proper backoff strategies.

Ready to build? Choose your product and start integrating today!