PAYMENT GATEWAY

0.1 What is a Payment Gateway?

A Payment Gateway is a technology service that securely transmits payment information between a customer, the merchant's website, and the bank (or payment processor). It acts as a digital “point‑of‑sale” terminal for online transactions, encrypting sensitive card data and ensuring secure communication.

In simple words, when a customer enters their credit card details on a shopping website, the payment gateway collects that information, sends it to the acquiring bank in a secure format, and returns a response (approved or declined) so the merchant can either confirm or cancel the order.

0.2 How Online Payments Work (Step‑by‑Step)

An online payment involves multiple parties and a series of secure messages. Below is the typical flow for a card‑based transaction. Understanding each step helps identify where security breaches can happen.

1. Customer initiates purchase: Adds items to cart and clicks “Checkout”.
2. Enters payment details: Fills in card number, expiry, CVV, and billing address on the merchant’s site.
3. Browser sends encrypted data: Data is encrypted using TLS and sent to the merchant’s server (or directly to the gateway via API).
4. Merchant forwards to payment gateway: The merchant’s server sends the payment data to the gateway (Stripe, Razorpay, etc.).
5. Gateway validates and routes: The gateway checks for fraud, tokenises the card if needed, and sends the request to the acquiring bank / processor.
6. Processor contacts card network: Acquirer sends the request to the card network (Visa/Mastercard).
7. Card network forwards to issuing bank: The customer’s bank receives the request, checks funds/validity, and records the transaction.
8. Authorization response travels back: Approve/decline message goes back through the chain (issuer → network → acquirer → gateway → merchant).
9. Merchant displays result: The website shows “Payment Successful” or “Declined”.
10. Settlement (later): Funds move from issuing bank to acquiring bank to merchant account (usually after 2‑3 days).

0.3 Payment Gateway vs Payment Processor (Key Differences)

Though often used interchangeably, a payment gateway and a payment processor serve different roles. A gateway transmits payment data; a processor settles the funds.

Many modern providers (like Stripe, Razorpay) offer both gateway and processing services, so the distinction blurs.

0.4 Payment Ecosystem – Who is Involved?

The payment ecosystem includes several entities, each with specific responsibilities. Understanding them helps identify attack surfaces and compliance requirements.

0.5 Merchant Accounts & Settlements

A merchant account is a special bank account that allows businesses to accept credit/debit card payments. Settlement is the process of moving funds from the customer’s bank to the merchant’s account.

📌 Types of Merchant Accounts

• Dedicated Merchant Account: Owned by one business – better rates, longer approval.
• Aggregated Account (PayFac): Shared account (Stripe, Square) – fast setup, higher fees.
• Third‑Party Processor: A service that provides both gateway and merchant account.

💰 Settlement Flow

1. Transaction authorised – customer’s funds are reserved.
2. Capture – merchant initiates capture (or auto‑capture after shipping).
3. Batch settlement – at end of day, all captured transactions are sent as a batch.
4. Funding – funds appear in merchant account after 1‑3 business days (including fees deduction).

0.6 Payment Flow Architecture (API‑based & Hosted)

Payment gateways offer different integration methods. The architecture affects security responsibilities and PCI DSS scope.

0.7 Types of Online Payments (Use Cases)

Payment gateways support different transaction types depending on the business model.

0.8 UPI, Cards, Wallets & Net Banking (Popular Methods)

Modern gateways support multiple payment instruments. Each has a different security model.

0.9 Sandbox vs Production Environment (Testing vs Live)

Every payment gateway provides a sandbox (test) environment that mimics the live system but uses test credentials, test card numbers, and does not move real money.

0.10 Common Payment Terminology – Glossary

Familiarise yourself with these terms – they appear in every payment integration and security assessment.

1.1 REST API Fundamentals

Most modern payment gateways (Stripe, Razorpay, PayPal) expose a RESTful API that allows merchants to programmatically create payments, refunds, manage customers, and handle webhooks.

1.2 API Authentication & Tokens

Payment gateways require authentication to ensure only authorised merchants can access APIs. Common methods include API keys, OAuth2, and JWT (JSON Web Tokens).

# Example: API Key in curl
curl -X GET https://api.paymentgateway.com/v1/payments \
  -H "Authorization: Basic base64(publishable_key:secret_key)"

# Bearer token
curl -X GET https://api.paymentgateway.com/v1/payments \
  -H "Authorization: Bearer sk_live_abc123"

1.3 API Keys & Secret Keys (Publishable vs Secret)

Payment gateways typically provide two types of keys: a publishable key (client‑side) and a secret key (server‑side). Mixing them up leads to security breaches.

# Correct usage (server‑side Node.js)
const stripe = require('stripe')('sk_live_...'); // secret key

# Incorrect (exposing secret key in frontend JS)
const stripe = Stripe('sk_live_...'); // DANGEROUS!

1.4 JSON Requests & Responses

Payment APIs use JSON (JavaScript Object Notation) for data exchange. Understanding the structure helps in integration and security testing.

📤 Create Payment Request (example – Razorpay style)

POST /v1/payments HTTP/1.1
Host: api.razorpay.com
Authorization: Basic base64(key:secret)
Content-Type: application/json

{
    "amount": 1000,          // ₹10.00 (in paise)
    "currency": "INR",
    "receipt": "order_123",
    "payment_capture": 1,
    "notes": {
        "customer_email": "user@example.com"
    }
}

📥 Success Response

{
    "id": "pay_abc123",
    "entity": "payment",
    "amount": 1000,
    "currency": "INR",
    "status": "captured",
    "method": "card",
    "created_at": 1612345678
}

1.5 Webhooks & Event Handling

Webhooks are asynchronous HTTP callbacks that notify your server when an event occurs (e.g., payment success, refund processed). They are essential for real‑time order updates, especially when the user is not on the website.

📡 How a Webhook Works

1. Merchant registers a webhook URL (e.g., https://shop.com/webhook) in the gateway dashboard.
2. When a payment succeeds, the gateway sends a POST request to that URL with a JSON payload.
3. Your server processes the payload and updates the order status.

🔐 Security for Webhooks

• Signature verification: Gateways sign webhook payloads with a secret. Verify the signature before processing (prevents fake events).
• Idempotency: Webhooks may be retried – ensure your handler can process duplicates safely.
• Authentication: Require a custom header or use the signature for authentication.
• Logging: Log all incoming webhooks for auditing and debugging.

# Example webhook receiver (Node.js/Express)
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['x-razorpay-signature'];
    const webhookSecret = process.env.WEBHOOK_SECRET;
    try {
        const event = razorpay.validateWebhookSignature(req.body, sig, webhookSecret);
        if (event.event === 'payment.captured') {
            // Update order
        }
        res.status(200).send('OK');
    } catch (err) {
        res.status(400).send('Invalid signature');
    }
});

1.6 Callback URLs & Redirects (Synchronous)

While webhooks are asynchronous, many gateways also support redirect‑based callbacks for hosted payment pages. After payment, the customer is redirected back to your site with payment status in the URL (GET parameters).

🔄 Typical Redirect Flow

1. Customer clicks “Pay” and is sent to gateway’s hosted page.
2. After payment, gateway redirects to return_url (e.g., https://shop.com/return) with parameters like payment_id, order_id, status.
3. Merchant validates the data (often using a signature) and updates the order.

⚠️ Security Risks with Redirects

• Parameter tampering: A user might modify URL parameters (e.g., change status to success).
• Missing signature: Without signature validation, anyone can fake a success callback.
• Open redirect: If the merchant does not validate return_url, attackers can redirect customers to phishing sites.

# Example vulnerable redirect handling (DO NOT DO THIS)
if ($_GET['status'] == 'success') {
    $order->paid = true;               // Attacker can craft ?status=success
}

1.7 Signature Verification (Integrity & Authenticity)

Payment gateways sign webhook payloads and sometimes redirect parameters using a secret key. Verifying the signature proves the data was sent by the gateway and not tampered with.

🔏 How Signature Verification Works

1. The gateway generates a hash (HMAC) of the payload using a secret key (webhook secret).
2. The hash is sent in a header (e.g., X-Razorpay-Signature).
3. Your server computes the same hash using the payload and its copy of the secret.
4. If they match, the payload is genuine.

# Python example (Razorpay)
import razorpay
client = razorpay.Client(auth=("key", "secret"))
webhook_secret = "your_webhook_secret"
payload = request.get_data()
signature = request.headers.get('X-Razorpay-Signature')

try:
    client.utility.verify_webhook_signature(payload, signature, webhook_secret)
    # Payment is legitimate
except razorpay.errors.SignatureVerificationError:
    # Reject request

1.8 Payment Verification Workflow (Best Practices)

A secure payment verification workflow combines synchronous callbacks, webhooks, and API fallbacks to ensure no failed payment is marked successful and no successful payment is lost.

✅ Recommended Workflow

1. Create order – Store order details, generate unique order ID.
2. Initiate payment – Call gateway API to create a payment session (or redirect to hosted page).
3. After redirect (if used) – Extract payment ID from URL parameters; do NOT rely on status parameter.
4. Query payment status via API – Call GET /v1/payments/{id} to get authoritative status.
5. Update order – Only after API confirms captured or paid.
6. Handle webhooks – Listen to payment.captured events to cover cases where user closes the browser before redirect.
7. Idempotent processing – Use order ID as idempotency key to prevent double processing.

1.9 Transaction Status APIs (GET Payment)

The status API allows you to query a specific transaction by its ID. It returns the most up‑to‑date information including status, amount, method, and failure reason.

Common Status Values

# Example GET status API (Stripe)
curl https://api.stripe.com/v1/payments/py_abc123 \
  -u sk_live_...:

# Response
{
  "id": "py_abc123",
  "object": "payment_intent",
  "amount": 2000,
  "status": "succeeded"
}

1.10 Refund APIs (Processing Returns)

Refund APIs allow merchants to return funds to customers partially or fully. They are critical for customer satisfaction but also a vector for fraud if not properly secured.

📦 Typical Refund Request

POST /v1/payments/pay_abc123/refunds
Authorization: Basic base64(key:secret)
Content-Type: application/json

{
    "amount": 500,          // refund amount in minor units (paise/cents)
    "reason": "customer_request",
    "notes": {
        "order_id": "order_xyz"
    }
}

📥 Refund Response

{
    "id": "ref_abc123",
    "payment_id": "pay_abc123",
    "amount": 500,
    "status": "processed",
    "created_at": 1612345678
}

🔒 Security Considerations

• Authentication: Only authorised users (admin) should be able to initiate refunds.
• Idempotency: Use unique refund IDs or idempotency keys to prevent double refunds.
• Audit logs: Record who initiated refund and why.
• Partial refunds: Some gateways allow multiple partial refunds – track remaining amount.
• Webhooks: Listen to refund.created / refund.updated events to sync status.

2.1 HTTPS & SSL Certificates (Encryption in Transit)

All communication between the merchant server, payment gateway, and customer browser must be encrypted using TLS (Transport Layer Security). HTTPS protects payment card data, API keys, and webhook payloads from eavesdropping and tampering.

🛡️ Best Practices

• Use TLS 1.2 or TLS 1.3 only – disable SSLv2, SSLv3, TLS 1.0, TLS 1.1.
• Obtain certificates from trusted Certificate Authorities (CA).
• Enable HSTS (Strict-Transport-Security) to enforce HTTPS for all subdomains.
• Regularly test with SSL Labs (https://www.ssllabs.com/ssltest/).

# Example HSTS header (Apache)
Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

2.2 PCI-DSS Compliance (Payment Card Industry Data Security Standard)

PCI-DSS is a set of security standards enforced by major card brands (Visa, Mastercard, etc.). Any business that stores, processes, or transmits cardholder data must comply. Non‑compliance can result in heavy fines, increased transaction fees, and loss of ability to accept credit cards.

📜 Key PCI-DSS Requirements (v3.2.1)

🎯 SAQ (Self‑Assessment Questionnaire) Types

• SAQ A: Redirect / iFrame (tokenisation) – lowest burden.
• SAQ A-EP: Partially hosted e‑commerce.
• SAQ D: Store or process card data directly – highest burden.

2.3 Secure API Key Management (Secrets Protection)

API keys (especially secret keys) are the digital keys to your payment account. A leaked secret key allows an attacker to create charges, refunds, and even modify webhook endpoints.

🔑 Do’s and Don’ts

🛠️ Detection & Response

• Use git hooks (e.g., git‑secrets) to prevent accidental commits.
• Enable key rotation API – gateways allow instant revocation.
• Monitor API activity for unexpected geographic locations or IPs.

# .env file example (never commit)
STRIPE_SECRET_KEY=sk_live_...
RAZORPAY_KEY_ID=rzp_live_...  

2.4 Payment Tampering Prevention (Amount, Currency, ID Manipulation)

Attackers often try to modify payment parameters – amount, currency, merchant ID, or order reference – to pay less, receive money, or bypass checks. Preventing tampering requires server‑side validation and cryptographic signatures.

🎯 Common Tampering Attacks

• Amount manipulation: Change amount from $100 to $1 in request.
• Currency change: Switch from USD to INR to reduce value.
• ID substitution: Replace merchant ID to pay a different seller.
• Callback spoofing: Fake success notification.

🛡️ Prevention Techniques

• Server‑side amount validation: Never trust client‑side price – recalculate from order data.
• Signed payloads: Use HMAC signatures for all callbacks and webhooks.
• Idempotency keys: Prevent replay of successful requests.
• Strict input validation: Reject unexpected fields or data types.

# Example: Server‑side amount validation (Node.js)
function createPayment(orderId) {
    const order = db.getOrder(orderId);
    const total = order.totalPrice; // recalculated from DB, not from client
    return gateway.payments.create({ amount: total, currency: 'INR' });
}

2.5 Webhook Security (Signature Verification & Idempotency)

Webhooks are critical for asynchronous payment status updates, but they are also a prime attack vector. Without proper security, attackers can send fake “payment succeeded” events and trick your system into fulfilling orders without actual payment.

🔒 Essential Webhook Security Controls

# Example: Webhook signature verification (Stripe in Node.js)
const stripe = require('stripe')('sk_...');
const endpointSecret = 'whsec_...';

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;
    try {
        event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
    } catch (err) {
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }
    // Handle event (payment_intent.succeeded, etc.)
    res.json({received: true});
});

2.6 Fraud Detection Basics (Rules & Machine Learning)

Payment fraud includes card testing, unauthorised transactions, friendly fraud (chargebacks), and account takeover. Gateways offer built‑in fraud detection, but merchants should add extra layers.

📊 Common Fraud Indicators

• Multiple failed payment attempts in short time (card testing).
• Orders from high‑risk countries or anonymous proxies (VPN / Tor).
• Unusually large order amounts or high velocity.
• Mismatch between billing and shipping address (for physical goods).
• Suspicious email addresses (temporary, misspelt).

🛡️ Fraud Prevention Techniques

• 3D Secure (3DS2): Transfers liability to issuer – reduces chargeback risk.
• Velocity checks: Limit number of attempts from same IP or card.
• AVS (Address Verification Service): Match billing address with cardholder’s bank.
• CVV check: Require CVV for card‑not‑present transactions.
• Machine learning models: Stripe Radar, Braintree Advanced Fraud Protection.
• Manual review queue: Flag high‑risk orders for human verification.

2.7 Rate Limiting & Abuse Prevention (Throttling)

Attackers may abuse payment APIs by submitting many requests – to test stolen cards, brute‑force discounts, or cause denial of service. Rate limiting prevents such abuse.

🎯 What to Rate Limit

• Create payment endpoint: Limit by IP, session, or user account.
• Refund API: Stricter limits – typically admin‑only with low threshold.
• Webhook receiver: Not usually rate‑limited, but ensure idempotency.
• Login / OTP generation: Critical for preventing credential stuffing.

🔧 Implementation Strategies

• Sliding window counters: Redis + time‑buckets.
• Token bucket: Allows bursts then throttles.
• Per‑user/account limits: Prevent one account from flooding.
• Penalty box: Temporary blocks (e.g., 1 hour) after exceeding limits.

# Example: Express‑rate‑limit (Node.js)
const rateLimit = require('express-rate-limit');
const createPaymentLimiter = rateLimit({
    windowMs: 15 * 60 * 1000, // 15 minutes
    max: 10, // limit each IP to 10 requests
    message: 'Too many payment attempts, try later'
});
app.post('/api/payments', createPaymentLimiter, paymentHandler);

2.8 Secure Transaction Logging (Audit Trails)

Comprehensive logging is required by PCI-DSS and helps during incident investigations. However, logs must never contain sensitive cardholder data (PAN, CVV, track data).

📝 What to Log (and what NOT to log)

🔒 Best Practices

• Use centralized logging (ELK, Splunk, Datadog) with strict access controls.
• Enable log rotation and retention policies (e.g., 1 year for PCI).
• Mask or truncate PAN – only last 4 digits can be stored.
• Integrate with SIEM for real‑time alerts.
• Regularly audit log access – who can read them.

# Example: Logging a payment event (JSON format)
{
    "timestamp": "2025-01-15T10:30:00Z",
    "event": "payment.created",
    "payment_id": "pay_abc123",
    "order_id": "order_xyz",
    "amount": 1000,
    "currency": "INR",
    "status": "created",
    "ip": "203.0.113.45",
    "user_id": "user_789",
    "panic": null
}

3.1 Stripe Account Setup (Production & Test Mode)

Stripe offers both Test Mode (sandbox) and Live Mode (production). Always start with Test Mode to integrate and test without moving real money.

📝 Step‑by‑Step Setup

1. Go to https://dashboard.stripe.com/register and sign up.
2. Verify your email address.
3. Complete business details (country, type, product description).
4. Toggle between Test Mode and Live Mode using the switcher in the dashboard.
5. In Test Mode, you can use test card numbers (e.g., 4242 4242 4242 4242) to simulate payments.

3.2 Stripe Dashboard Overview (Key Sections)

The Stripe Dashboard is your central control panel for managing payments, customers, disputes, and settings.

🔧 Key Developer Tools

• API Keys: Publishable key (pk_test_...) and secret key (sk_test_...).
• Webhooks: Add endpoints, view recent deliveries, and retry failed events.
• Logs: Detailed request/response logs for debugging.
• Events: All webhook‑triggered events listed with payloads.

3.3 Stripe API Keys (Publishable vs Secret)

Stripe provides two types of keys: publishable key (client‑side) and secret key (server‑side). Never expose the secret key in client‑side code.

# Storing keys in .env (Node.js)
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...

# Using keys
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

3.4 Stripe Checkout Integration (Pre‑built Payment Page)

Stripe Checkout is a hosted payment page that handles card collection, 3D Secure, and payment confirmation. It reduces PCI compliance burden and is the quickest way to start accepting payments.

🛒 Integration Steps (Server‑side)

1. Create a Checkout Session on your server.
2. Redirect the customer to the session URL.
3. Stripe handles the rest – customer pays, and you receive webhooks.

# Node.js (Express) example
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

app.post('/create-checkout-session', async (req, res) => {
    const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        line_items: [{
            price_data: {
                currency: 'usd',
                product_data: { name: 'T-shirt' },
                unit_amount: 2000, // $20.00
            },
            quantity: 1,
        }],
        mode: 'payment',
        success_url: 'https://your-site.com/success?session_id={CHECKOUT_SESSION_ID}',
        cancel_url: 'https://your-site.com/cancel',
    });
    res.json({ id: session.id });
});

On the frontend, redirect the customer using session.id with Stripe.js:

<script src="https://js.stripe.com/v3/"></script>
<script>
    const stripe = Stripe('pk_test_...');
    stripe.redirectToCheckout({ sessionId: '{{session.id}}' });
</script>

3.5 Stripe Payment Intents API (Manual Payment Flow)

Payment Intents API gives you full control over the payment lifecycle – from authorisation to capture. It is used for custom checkout forms, delayed capture, or when you need to handle 3D Secure yourself.

📦 Payment Intent Steps

1. Create a PaymentIntent on the server with amount and currency.
2. Return the client secret to the frontend.
3. Confirm the payment on the client side (Stripe.js).
4. Listen to webhook events (payment_intent.succeeded) to update order status.

# Create PaymentIntent (Node.js)
const paymentIntent = await stripe.paymentIntents.create({
    amount: 2000,
    currency: 'usd',
    payment_method_types: ['card'],
});

// Response includes client_secret (for frontend)
{ id: 'pi_123', client_secret: 'pi_123_secret_abc' }

# Frontend confirmation (Stripe Elements)
const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
    payment_method: { card: cardElement }
});

🔧 Advanced Options

• Capture method: manual (authorise only, capture later).
• Payment method types: Add card, link, us_bank_account.
• Statement descriptor: Custom text on customer’s bank statement.
• Metadata: Store custom data (order ID, user ID).

3.6 Stripe Webhooks (Asynchronous Event Handling)

Stripe sends webhooks for asynchronous events like payment success, refund completion, subscription renewal, and failed payments. Webhooks are critical for reliable order processing.

📡 Common Webhook Events

🔒 Webhook Security

• Stripe signs each webhook with a secret (whsec_...).
• Verify signature using Stripe library – reject unsigned requests.
• Use HTTPS for webhook endpoint.
• Respond with 200 OK within 10 seconds; otherwise Stripe retries.
• Implement idempotency – process each event only once (use event.id).

# Webhook handler (Node.js)
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const endpointSecret = 'whsec_...';

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;
    try {
        event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
    } catch (err) {
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }
    switch (event.type) {
        case 'payment_intent.succeeded':
            const paymentIntent = event.data.object;
            // Update order status in your DB
            break;
        default:
            console.log(`Unhandled event type ${event.type}`);
    }
    res.status(200).end();
});

3.7 Stripe Refunds & Subscriptions (Recurring Billing)

Stripe supports full and partial refunds via API or dashboard. Subscriptions allow recurring billing with flexible plans, trial periods, and automatic invoicing.

💰 Processing Refunds

# Full refund of a payment intent
const refund = await stripe.refunds.create({
    payment_intent: 'pi_123',
});

# Partial refund
const refund = await stripe.refunds.create({
    charge: 'ch_123',
    amount: 500, // refund $5.00
});

• Refunds are synchronous – they happen immediately (but bank processing may take days).
• You can refund up to the original captured amount.
• Webhook event: charge.refunded.

🔄 Setting Up Subscriptions

1. Create a Product and Price (one‑time, recurring).
2. Create a Customer (if not exists).
3. Create a Subscription with the price ID and customer ID.
4. Stripe handles recurring charges, prorations, and invoice emails.

# Create a subscription (Node.js)
const subscription = await stripe.subscriptions.create({
    customer: 'cus_123',
    items: [{ price: 'price_1ABC123' }],
    expand: ['latest_invoice.payment_intent'],
});

4.1 PayPal Business Setup (Sandbox & Live)

To integrate PayPal, you need a Business Account. PayPal provides a Sandbox environment for testing with fake money and a Live environment for real transactions.

📝 Step‑by‑Step Setup

1. Go to https://www.paypal.com/business/signup and sign up for a Business account.
2. Verify your email address and provide basic business information.
3. Access the Developer Dashboard at https://developer.paypal.com.
4. Create Sandbox test accounts (buyer and seller) under Sandbox → Accounts.
5. Toggle between Sandbox and Live mode in your API credentials.

4.2 PayPal Developer Console – Key Sections

The PayPal Developer Dashboard is your central hub for managing apps, API credentials, webhooks, and testing tools.

4.3 PayPal API Credentials (Client ID & Secret)

PayPal uses OAuth2 for API authentication. You receive a Client ID (public) and a Secret (confidential). Never expose the secret on the client side.

# Store credentials in .env (Node.js)
PAYPAL_CLIENT_ID=Adf3jkl...
PAYPAL_SECRET=EdfG45...

# Use with PayPal SDK
const paypal = require('@paypal/checkout-server-sdk');
const environment = new paypal.core.SandboxEnvironment(process.env.PAYPAL_CLIENT_ID, process.env.PAYPAL_SECRET);
const client = new paypal.core.PayPalHttpClient(environment);

4.4 PayPal Checkout Integration (Hosted & Custom)

PayPal offers two main integration methods: the hosted smart buttons (JavaScript) and the server‑side Orders API for full control. Both support cards, PayPal balance, and local payment methods.

🛒 Smart Buttons (Hosted – Easiest)

<div id="paypal-button-container"></div>
<script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&currency=USD"></script>
<script>
    paypal.Buttons({
        createOrder: function(data, actions) {
            return actions.order.create({
                purchase_units: [{
                    amount: { value: '10.00' }
                }]
            });
        },
        onApprove: function(data, actions) {
            return actions.order.capture().then(function(details) {
                alert('Transaction completed by ' + details.payer.name.given_name);
                // Send the order ID to your server for verification
            });
        }
    }).render('#paypal-button-container');
</script>

⚙️ Server‑Side Orders API (More Control)

# Node.js – Create order
const request = new paypal.orders.OrdersCreateRequest();
request.requestBody({
    intent: 'CAPTURE',
    purchase_units: [{ amount: { currency_code: 'USD', value: '10.00' } }]
});
const order = await client.execute(request);
// Return order.id to frontend
res.json({ id: order.result.id });

4.5 PayPal IPN & Webhooks (Asynchronous Notifications)

PayPal provides two asynchronous notification mechanisms: Instant Payment Notification (IPN) (legacy, POST form‑encoded) and Webhooks (modern, JSON). Both are used to update order statuses in real time.

📡 Webhook Events (Recommended)

🔒 Security – Verifying IPN Messages

# Node.js IPN verification (legacy)
const ipn = require('paypal-ipn');
ipn.verify(req.body, function callback(err, msg) {
    if (err) { /* invalid */ }
    else { /* valid – process */ }
});

4.6 PayPal Subscriptions (Billing Plans & Agreements)

PayPal Subscriptions allow merchants to charge customers on a recurring basis (weekly, monthly, yearly) with trial periods, proration, and automatic retry of failed payments.

🔄 Subscription Steps

1. Create a Product (if not exists).
2. Create a Billing Plan (duration, frequency, pricing).
3. Create a Subscription (assign plan to customer).
4. Redirect customer to PayPal to approve.
5. Listen to webhook events (e.g., BILLING.SUBSCRIPTION.ACTIVATED).

# Create Billing Plan (Node.js)
const request = new paypal.billingPlans.BillingPlansCreateRequest();
request.requestBody({
    name: 'Monthly Membership',
    description: 'Recurring monthly subscription',
    type: 'INFINITE',
    payment_definitions: [{
        name: 'Monthly Payment',
        type: 'REGULAR',
        frequency_interval: '1',
        frequency: 'MONTH',
        amount: { currency: 'USD', value: '9.99' },
        cycles: '0' // infinite
    }],
    merchant_preferences: {
        return_url: 'https://shop.com/success',
        cancel_url: 'https://shop.com/cancel'
    }
});

5.1 Razorpay Account Setup (Dashboard & API Access)

To start accepting payments with Razorpay, you need to create a merchant account and obtain API keys. Razorpay offers a free test environment for integration and a production environment for live transactions.

📝 Step‑by‑Step Setup

1. Go to https://dashboard.razorpay.com/signup and sign up.
2. Verify your email and provide basic business details (company type, PAN, GST optional for test).
3. Once logged in, navigate to Settings → API Keys to generate your Key ID and Key Secret.
4. For production, you will also need to submit KYC documents and activate your account.

5.2 Razorpay Test & Live Mode (Sandbox vs Production)

Razorpay separates test and live environments using different API keys. Switching between them is manual – you must change keys in your code.

5.3 Razorpay Orders API (Create & Fetch Orders)

Razorpay uses an Order object to represent a payment request. You create an order on your server, then pass the order ID to the frontend Checkout.

📦 Create Order – API Reference

POST https://api.razorpay.com/v1/orders
Authorization: Basic base64(key_id:key_secret)
Content-Type: application/json

{
    "amount": 50000,           // ₹500.00 (in paise)
    "currency": "INR",
    "receipt": "order_rcptid_11",
    "notes": {
        "order_id": "order_123",
        "customer_email": "user@example.com"
    }
}

📥 Sample Response

{
    "id": "order_Examp1e12345",
    "entity": "order",
    "amount": 50000,
    "amount_paid": 0,
    "status": "created",
    "created_at": 1650000000
}

🔧 Code Example (Node.js with Razorpay NPM)

const Razorpay = require('razorpay');
const instance = new Razorpay({
    key_id: process.env.RAZORPAY_KEY_ID,
    key_secret: process.env.RAZORPAY_KEY_SECRET
});

async function createOrder(amount, receipt) {
    const options = {
        amount: amount * 100, // convert to paise
        currency: 'INR',
        receipt: receipt,
        notes: { version: '1.0' }
    };
    const order = await instance.orders.create(options);
    return order;
}

5.4 Razorpay Checkout Integration (JavaScript SDK)

Razorpay Checkout is a hosted payment page that handles cards, UPI, net banking, wallets, and EMI. It is the simplest and most secure way to accept payments – card data never touches your server.

🛒 Integration Steps

1. Include the Razorpay Checkout script on your payment page.
2. Create an order on your server (as shown in 5.3) and pass the order ID to the frontend.
3. Initialise the Razorpay Checkout object with the order ID and user details.
4. Handle success (payment capture) via a callback, then verify the payment status on your server.

<script src="https://checkout.razorpay.com/v1/checkout.js"></script>
<script>
    const options = {
        key: "{{RAZORPAY_KEY_ID}}",        // Your test/live key ID
        amount: 50000,                    // in paise
        currency: "INR",
        name: "Acme Corp",
        description: "Test Transaction",
        order_id: "{{order_id}}",          // Order ID from server
        handler: function (response) {
            // Send payment_id and order_id to your server for verification
            fetch('/verify-payment', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    razorpay_payment_id: response.razorpay_payment_id,
                    razorpay_order_id: response.razorpay_order_id,
                    razorpay_signature: response.razorpay_signature
                })
            });
        },
        prefill: {
            name: "Customer Name",
            email: "customer@example.com",
            contact: "9999999999"
        },
        theme: { color: "#F37254" }
    };
    const rzp = new Razorpay(options);
    document.getElementById('pay-btn').onclick = function() { rzp.open(); };
</script>

5.5 Razorpay Webhooks (Payment & Refund Events)

Razorpay sends webhooks (HTTP callbacks) for important events like payment capture, refund processed, and subscription renewal. Webhooks are the most reliable way to update order status asynchronously.

📡 Common Webhook Events

🔒 Webhook Signature Verification

Razorpay signs each webhook with a secret. You must verify the signature before processing.

// Node.js example using Razorpay utility
const crypto = require('crypto');
const webhookSecret = process.env.RAZORPAY_WEBHOOK_SECRET;

app.post('/razorpay-webhook', express.raw({type: 'application/json'}), (req, res) => {
    const signature = req.headers['x-razorpay-signature'];
    const body = req.body.toString('utf8');
    const expectedSignature = crypto.createHmac('sha256', webhookSecret).update(body).digest('hex');
    if (signature !== expectedSignature) {
        return res.status(400).send('Invalid signature');
    }
    const event = JSON.parse(body);
    switch (event.event) {
        case 'payment.captured':
            // Update order in database
            break;
    }
    res.status(200).end();
});

5.6 Razorpay Refund APIs (Full & Partial)

Razorpay allows you to refund a payment fully or partially via API. Refunds can be initiated from the dashboard or programmatically. Always ensure refunds are authorised (e.g., admin action) to prevent abuse.

💰 Refund Request (Full Refund)

POST https://api.razorpay.com/v1/payments/{payment_id}/refund
Authorization: Basic base64(key_id:key_secret)
Content-Type: application/json

{
    "amount": 50000,           // amount in paise – optional, full if omitted
    "notes": {
        "reason": "customer_request",
        "order_id": "order_123"
    }
}

📥 Sample Response

{
    "id": "ref_Examp1e123",
    "entity": "refund",
    "amount": 50000,
    "status": "processed",
    "payment_id": "pay_Examp1e456",
    "created_at": 1650000000
}

🔧 Code Example (Node.js)

// Refund a payment (partial or full)
async function refundPayment(paymentId, amountInPaise = null) {
    const options = {};
    if (amountInPaise) options.amount = amountInPaise;
    const refund = await instance.payments.refund(paymentId, options);
    return refund;
}

6.1 Paytm Merchant Account Setup

To accept payments via Paytm, you need to register as a merchant on Paytm’s business portal. Paytm provides separate test (staging) and production environments.

📝 Step‑by‑Step Setup

1. Go to https://business.paytm.com and click “Sign Up”.
2. Fill in business details (type, PAN, GST, bank account).
3. Complete KYC process – may require document submission.
4. Once approved, you will receive a Merchant ID (MID) and access to the dashboard.
5. For testing, also request staging credentials from Paytm support or use the sandbox portal.

6.2 Paytm MID & Merchant Keys

Paytm uses a combination of Merchant ID (MID), Merchant Key, and Industry Type to identify and authenticate merchants. These are used to generate checksums for request and response validation.

🔧 Securing Keys

# Store in .env file (never commit)
PAYTM_MID=1234567
PAYTM_MERCHANT_KEY=your_merchant_key
PAYTM_INDUSTRY_TYPE=RETAIL

# In code (Node.js)
const paytmConfig = {
    mid: process.env.PAYTM_MID,
    merchantKey: process.env.PAYTM_MERCHANT_KEY,
    website: 'WEBSTAGING',  // or 'WEBPRO' for production
    industryType: process.env.PAYTM_INDUSTRY_TYPE
};

6.3 Paytm Integration Workflow (Checksum‑Based)

Paytm uses a redirect‑based flow. The merchant generates a checksum for the transaction, redirects the customer to Paytm’s hosted page, and Paytm sends the response to a callback URL.

🔄 Steps

1. Initiate Transaction: Merchant creates an order, collects customer details.
2. Generate Checksum: Using Merchant Key, generate a checksum for the transaction parameters (order ID, amount, etc.).
3. Redirect to Paytm: Send the checksum and parameters to Paytm’s payment page (staging or production URL).
4. Customer Pays: Customer completes payment on Paytm (cards, UPI, wallet, net banking).
5. Callback Response: Paytm redirects back to your callback_url with a response checksum.
6. Verify Checksum: Merchant re‑computes the checksum and verifies it – only then updates order status.
7. Transaction Status API (optional): For additional confirmation, call Paytm’s order status API.

6.4 Paytm Callback Verification (Checksum Validation)

Paytm sends transaction response via a GET/POST callback to your specified URL. The response contains a checksum. You must re‑generate the checksum and compare it to verify the integrity and authenticity.

🔏 Checksum Generation & Verification

Paytm provides libraries in multiple languages. Below is a PHP example using their library.

// PHP callback handler (using Paytm's lib)
require_once("encdec_paytm.php");
$paytmChecksum = $_POST["CHECKSUMHASH"];
$paytmParams = $_POST;
unset($paytmParams["CHECKSUMHASH"]);
$isValidChecksum = verifychecksum_e($paytmParams, PAYTM_MERCHANT_KEY, $paytmChecksum);

if ($isValidChecksum && $_POST['STATUS'] == 'TXN_SUCCESS') {
    // Update order status
    $orderId = $_POST['ORDERID'];
    $txnAmount = $_POST['TXNAMOUNT'];
    // Additional verification via TxnStatus API recommended
}

📥 Sample Callback Response Parameters

6.5 Paytm Webhooks (Checksum‑Based Callbacks)

Paytm does not use standard JSON webhooks like Stripe. Instead, it relies on the same redirect‑based callback mechanism. After payment, Paytm hits your callback_url with POST parameters and a checksum. This is the equivalent of a webhook.

📡 Handling “Webhook” Callbacks

• Set your callback_url in the Paytm dashboard (Test/Live).
• This URL must be publicly accessible (HTTPS in production).
• Paytm sends both success and failure notifications to the same URL.
• Your server must respond with 200 OK (any other status may be retried, but Paytm retries are limited).
• Implement idempotency using your own order ID – the same callback may be sent twice.

🔒 Security – No IP whitelisting needed (checksum is enough)

Because all responses are signed with your Merchant Key, you don’t need to whitelist Paytm IP addresses. Checksum verification alone guarantees authenticity.

6.6 Paytm Refund & Status APIs (Transaction Management)

Paytm provides APIs to check transaction status and initiate refunds. These are server‑to‑server REST calls using the same checksum mechanism.

📊 Transaction Status API

After receiving a callback, it’s recommended to double‑check the status using the Order Status API.

POST https://securegw.paytm.in/merchant-status/getTxnStatus
Parameters (JSON):
{
    "MID": "your_mid",
    "ORDERID": "order_123",
    "CHECKSUMHASH": "generated_checksum"
}

Response includes STATUS, TXNAMOUNT, BANKTXNID, etc.

💰 Refund API

POST https://securegw.paytm.in/refund/apply
Parameters (JSON):
{
    "MID": "your_mid",
    "ORDERID": "order_123",
    "TXNID": "paytm_txn_id",
    "REFUNDAMOUNT": "500.00",
    "CHECKSUMHASH": "generated_checksum"
}

7.1 PhonePe Merchant Setup (Test & Production)

To start accepting payments via PhonePe, you need to register as a merchant on the PhonePe business portal. PhonePe provides separate test (sandbox) and production environments.

📝 Step‑by‑Step Setup

1. Go to https://www.phonepe.com/business and click “Sign Up”.
2. Fill in business details (company name, PAN, GST, bank account).
3. Complete KYC verification (may take a few days).
4. Once approved, login to the PhonePe Merchant Dashboard.
5. Obtain your Merchant ID and Salt Key (for checksum generation).
6. For testing, request sandbox credentials or use PhonePe’s test environment (test.phonepe.com).

7.2 PhonePe API Authentication (Checksum & Salt)

PhonePe uses a checksum‑based authentication mechanism similar to Paytm. Each API request must include a X-VERIFY header containing a SHA‑256 hash generated using your Merchant ID, the request payload, and a Salt Key.

🔏 How Checksum Works

• Concatenate payload + /pg/v1/pay (API endpoint) + saltKey
• Compute SHA‑256 hash → append ###1 (suffix for the salt version).
• Example header: X-VERIFY: sha256_hash###1

// Node.js example
const crypto = require('crypto');
const payload = JSON.stringify({ merchantId: 'MERCHANTUID', ... });
const endpoint = '/pg/v1/pay';
const saltKey = process.env.PHONEPE_SALT_KEY;
const string = payload + endpoint + saltKey;
const sha256 = crypto.createHash('sha256').update(string).digest('hex');
const xVerify = sha256 + '###1';

🔑 Required Credentials

7.3 PhonePe UPI Integration (PG Pay API)

PhonePe offers a redirect‑based UPI integration using the /pg/v1/pay endpoint. The merchant creates a payment request, redirects the customer to PhonePe’s hosted page, and handles the callback.

🔄 Integration Flow

1. Create Payment Request: On your server, call POST https://api.phonepe.com/apis/hermes/pg/v1/pay (sandbox: test.phonepe.com).
2. Get Redirect URL: PhonePe returns a data.instrumentResponse.redirectInfo.url.
3. Redirect Customer: Send the customer to that URL (PhonePe’s payment page).
4. Customer Pays: Customer completes payment on PhonePe (UPI, cards, wallet).
5. Callback Response: PhonePe redirects to your redirectUrl (merchant provided) with a transaction ID.
6. Verify Checksum & Status: Verify the callback checksum, then call status API if needed.

📦 Sample Payment Request (Node.js)

const payload = {
    merchantId: 'MERCHANTUID',
    merchantTransactionId: 'TXN123',
    merchantUserId: 'USER456',
    amount: 10000, // ₹100.00 in paise
    redirectUrl: 'https://your-site.com/phonepe-callback',
    redirectMode: 'REDIRECT',
    paymentInstrument: { type: 'PAY_PAGE' }
};
const base64Payload = Buffer.from(JSON.stringify(payload)).toString('base64');
const checksum = crypto.createHash('sha256').update(base64Payload + '/pg/v1/pay' + saltKey).digest('hex') + '###1';
const response = await axios.post(`${baseUrl}/pg/v1/pay`, { request: base64Payload }, {
    headers: { 'Content-Type': 'application/json', 'X-VERIFY': checksum }
});

7.4 Payment Status Verification (Transaction Status API)

After receiving a callback, it is strongly recommended to verify the transaction status using PhonePe’s status API. This provides an extra layer of security and confirmation.

📡 Status API Endpoint

GET /pg/v1/status/{merchantId}/{merchantTransactionId}

🔍 Request Example

const endpoint = `/pg/v1/status/${merchantId}/${merchantTransactionId}`;
const checksum = crypto.createHash('sha256').update(endpoint + saltKey).digest('hex') + '###1';
const response = await axios.get(`${baseUrl}${endpoint}`, {
    headers: { 'Content-Type': 'application/json', 'X-VERIFY': checksum }
});

📥 Sample Status Response

{
    "success": true,
    "code": "PAYMENT_SUCCESS",
    "message": "Transaction successful",
    "data": {
        "merchantId": "MERCHANTUID",
        "merchantTransactionId": "TXN123",
        "transactionId": "PhonePeTxnId",
        "amount": 10000,
        "state": "COMPLETED",
        "paymentInstrument": { "type": "UPI", "utr": "1234567890" }
    }
}

7.5 Callback & Refund Handling

PhonePe sends payment responses to your redirectUrl via GET (or POST, depending on configuration). You must verify the checksum and process the transaction. Refunds are initiated via API and must be verified similarly.

📥 Callback Handling

// Node.js callback handler (GET)
app.get('/phonepe-callback', async (req, res) => {
    const { merchantId, transactionId, amount, checksumHash } = req.query;
    // Recompute checksum for the response
    const payload = `merchantId=${merchantId}&transactionId=${transactionId}&amount=${amount}`;
    const computedHash = crypto.createHash('sha256').update(payload + saltKey).digest('hex') + '###1';
    if (computedHash !== checksumHash) {
        return res.status(400).send('Invalid checksum');
    }
    // Call status API for final confirmation
    const status = await getTransactionStatus(merchantId, transactionId);
    if (status.data.state === 'COMPLETED') {
        // Update order
    }
    res.send('OK');
});

💰 Refund API

POST /pg/v1/refund (requires checksum similar to pay API).

// Refund request payload
{
    "merchantId": "MERCHANTUID",
    "merchantTransactionId": "REFUND123",
    "originalTransactionId": "PhonePeTxnId",
    "amount": 5000,
    "callbackUrl": "https://your-site.com/refund-callback"
}