Getting Started

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

Platform Overview

Paywize provides payment technology infrastructure that enables businesses to integrate with licensed banking and payment partners through three core product offerings :

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: Complete the required onboarding and verification process as applicable for the enabled services through licensed banking and payment partners
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/
Dashboard: https://dashboard.paywize.in

Sandbox Environment

Base URL: https://sandbox.paywize.dev/
Dashboard: https://sandbox.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/

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/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/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/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.paywize.dev/
• 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 payment collection workflows
• Use Payout APIfor vendor payout workflows
• Use Connected Banking for verification

2. Marketplace

• Use Collection API for buyer payment collection
• Use Payout API for seller payout workflows
• Use Connected Banking for seller onboarding

3. Fintech Application

• Use all APIs to build comprehensive payment technology workflows
• Start with Collection and Payout APIs
• Add Connected Banking APIs for enhanced banking integrations

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 automating payout workflows
2. Collection API Quick Start - Start integrating payment collection workflows

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

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!