Merchant API Docs

Public

This page explains how a merchant should integrate CGPEY payment APIs (create checkout, redirect user, and verify status).

Base URL
These APIs are served by the Node.js payment service (Express) on /api.
Examples
  • https://pay.cgpey.com
If you’re using a gateway/proxy in front of the Node service, use that domain as the Base URL.
If you are calling from this Next.js app domain, you can also use /api/checkout (proxied to the payment service).
Authentication
Merchant-authenticated endpoints require these headers.
  • x-merchant-id — your merchant ID
  • x-api-key — public API key (mode based)
  • x-secret-key — secret key (mode based)
IP whitelisting is required. Add your server IP(s) in the merchant profile before calling POST /api/checkout. Requests from non-whitelisted IPs return 403 with IP_NOT_WHITELISTED.
Quick start flow
Typical checkout integration sequence.
  1. Create checkout: POST /api/checkout (auth required)
  2. Redirect customer to returned checkoutUrl
  3. After payment, verify using POST /api/payments/verify or fetch status using GET /api/payments/:paymentId/status (auth required for status endpoint)
Create Checkout
Creates a payment and returns a hosted checkout URL for the customer.
POST
/api/checkout
Auth required
Request body
  • orderId (string, must start with ORDER_, e.g. ORDER_10078)
  • amount (number/string) — INR amount (max ₹100,000)
  • redirectUrl (string, optional) — customer redirect URL after payment
  • meta (object, optional) — customer metadata: name, email, phone
  • lat, lng (optional) — geo info (if available)
curl -X POST "$BASE_URL/api/checkout" \
  -H "Content-Type: application/json" \
  -H "x-merchant-id: MERCHANT_123" \
  -H "x-api-key: YOUR_PUBLIC_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY" \
  -d '{
    "orderId": "ORDER_10001",
    "amount": 199.00,
    "redirectUrl": "https://merchant.example.com/payment/return",
    "meta": { "name": "Customer", "email": "c@example.com", "phone": "9999999999" }
  }'
Success response
{
  "success": true,
  "data": {
    "paymentId": "pay_1712470000000_abcdef123456",
    "checkoutUrl": "https://business.cgpey.com/checkout/pay_1712470000000_abcdef123456",
    "expiresAt": "2026-04-07T12:34:56.000Z",
    "merchantOrderId": "ORDER_10001",
    "amount": "199.00",
    "currency": "INR",
    "_token": "<checkoutToken>"
  }
}
Get Payment Status
Fetch payment details from our system by paymentId.
GET
/api/payments/:paymentId/status
Auth required
curl -X GET "$BASE_URL/api/payments/pay_1712470000000_abcdef123456/status" \
  -H "x-merchant-id: MERCHANT_123" \
  -H "x-api-key: YOUR_PUBLIC_KEY" \
  -H "x-secret-key: YOUR_SECRET_KEY"
Returns 404 if payment does not exist for that merchant.
Last updated: 2026-07-09