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 allow-list may be enforced (based on merchant configuration). If enabled, requests from non-whitelisted IPs will be rejected.
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, max 100 chars, [a-zA-Z0-9_-])
  • 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.
Verify Payment (by Order ID)
Verifies payment with gateway and updates our records (useful post-redirect).
POST
/api/payments/verify
No merchant auth header required
curl -X POST "$BASE_URL/api/payments/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": "PHONEPE",
    "orderId": "ORDER_10001"
  }'
Error format
Most errors respond with success: false and an error code.
{
  "success": false,
  "error": "INVALID_ORDER_ID",
  "message": "Order ID must be alphanumeric (a-z, A-Z, 0-9, _, -) with max 100 characters"
}
Last updated: 2026-04-16