Skip to main content

Overview

The Payments APIs provide comprehensive payment processing capabilities for the TalentG platform, including order creation, payment verification, coupon management, and billing operations using Razorpay as the payment gateway.

Base URL

https://talentg.vercel.app/api

Authentication

All payment endpoints require user authentication. Users must be signed in to create orders or access billing information.
Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Order Management

Create Payment Order

Verify Payment

Coupon Management

Validate Coupon

Apply Coupon

Webhook Handling

Razorpay Webhook

Payment Configuration

Supported Features

The following features/services support payment processing:
Feature KeyDescriptionBase Price (INR)
strength_finderStrength Finder Assessment₹499
premium_supportPremium Support Access₹999
advanced_analyticsAdvanced Analytics Dashboard₹1999

Pricing Modes

  • inclusive: Tax included in base price
  • exclusive: Tax added to base price

Supported Currencies

  • INR: Indian Rupee (primary)
  • USD: US Dollar (international users)

Tax Calculation

The system automatically calculates taxes based on:
  • CGST: 9% (for Indian transactions)
  • SGST: 9% (for Indian transactions)
  • IGST: 18% (for international transactions)
Tax rates are configured per payment feature and can be updated through the admin panel.

Coupon Types

Percentage Discount

{
  "discount_type": "percentage",
  "discount_value": 20  // 20% off
}

Fixed Amount Discount

{
  "discount_type": "fixed_amount",
  "discount_value": 10000  // ₹100 off (in paise)
}

Free Access

{
  "discount_type": "free_access",
  "discount_value": null  // 100% discount
}

Error Handling

Common Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401User not authenticated
INVALID_REQUEST400Invalid request parameters
FEATURE_NOT_ACTIVE404Requested feature not available
INVALID_COUPON400Coupon code is invalid or inactive
COUPON_EXPIRED400Coupon has expired
COUPON_LIMIT_REACHED400Coupon usage limit exceeded
ORDER_CREATION_FAILED500Failed to create payment order
PAYMENT_VERIFICATION_FAILED400Payment verification failed

Error Response Format

{
  "error": "Invalid coupon code",
  "code": "INVALID_COUPON",
  "details": {
    "coupon_code": "INVALID123",
    "reason": "Coupon not found or inactive"
  }
}

Rate Limiting

  • Create order: 10 requests per hour per user
  • Verify payment: 50 requests per hour per user
  • Coupon validation: 100 requests per hour per user
  • Webhooks: Unlimited (system endpoint)

SDK Examples

const createPaymentOrder = async (featureKey, couponCode = null) => {
  const token = await getSupabaseToken();

  const response = await fetch('/api/payments/create-order', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      feature_key: featureKey,
      coupon_code: couponCode
    })
  });

  const orderData = await response.json();

  if (orderData.free_access) {
    // Free access granted
    return { success: true, free: true };
  }

  // Initialize Razorpay payment
  const options = {
    key: orderData.key_id,
    amount: orderData.amount_total_paise,
    currency: orderData.currency,
    order_id: orderData.rzp_order_id,
    name: 'TalentG',
    description: 'Strength Finder Assessment',
    handler: async function (response) {
      // Verify payment
      await verifyPayment(orderData.order_id, response);
    }
  };

  const rzp = new Razorpay(options);
  rzp.open();

  return orderData;
};

const verifyPayment = async (orderId, razorpayResponse) => {
  const token = await getSupabaseToken();

  const response = await fetch('/api/payments/verify', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      order_id: orderId,
      payment_id: razorpayResponse.razorpay_payment_id,
      signature: razorpayResponse.razorpay_signature
    })
  });

  return response.json();
};

Payment Flow

  1. Create Order: Client requests payment order with feature and optional coupon
  2. Order Validation: System validates feature availability and coupon eligibility
  3. Amount Calculation: Base amount, discounts, and taxes are calculated
  4. Razorpay Order: Razorpay order is created (unless free access)
  5. Payment: User completes payment through Razorpay checkout
  6. Verification: Payment is verified and entitlements are granted
  7. Access: User gains access to the purchased feature
Always verify payments on the server side using the /api/payments/verify endpoint. Never trust client-side payment confirmations.