Shulker Payment Gateway v1.0.0

Introduction

The Shulker Payment Gateway API lets you generate payment requests, track their status, and receive webhook notifications when payments succeed. It powers the branded checkout page at /payment-gateway/ and handles all the heavy lifting.

https://shulker.in/api/shulker-pg-v1.0/

Authentication

All endpoints except ping, log_event, and complete_payment require an API key. Pass it via the X-API-Key header, the Authorization: Bearer header, or the api_key query parameter.

X-API-Key: spgk_your_secret_key_here

Authorization: Bearer spgk_your_secret_key_here

Rate limits

Per‑API‑key limits are soft and can be raised on request.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1697385645

Error handling

{
    "success": false,
    "message": "amount_usd must be between 0.01 and 10000.00"
}

Create payment request

Generates a new payment link. The request is valid for 24 hours.

curl -X POST https://shulker.in/api/shulker-pg-v1.0/ \
  -H "X-API-Key: spgk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_request",
    "amount_usd": 49.99,
    "redirect_url": "https://myapp.com/success",
    "description": "Pro plan subscription",
    "metadata": { "user_id": 12345 }
  }'

{
    "success": true,
    "message": "Payment request created.",
    "data": {
        "payment_request_id": "SPGR_A1B2C3D4E5F6",
        "checkout_url": "https://shulker.in/payment-gateway/?payment_request=SPGR_A1B2C3D4E5F6",
        "amount_usd": 49.99,
        "amount_inr": 4699.06,
        "expires_at": "2026-09-09 16:30:00",
        "status": "pending"
    }
}

Get payment status

curl "https://shulker.in/api/shulker-pg-v1.0/?action=get_status&payment_request_id=SPGR_A1B2C3&api_key=spgk_..."

{
    "success": true,
    "data": {
        "payment_request_id": "SPGR_A1B2C3",
        "status": "completed",
        "amount_usd": 49.99,
        "payer": {
            "name": "John Doe",
            "email": "[email protected]",
            "country_code": "IN"
        },
        "txn_id": "pay_xyz",
        "completed_at": "2026-09-09 14:20:00"
    }
}

List payment requests

Manually expire a request

curl -X POST https://shulker.in/api/shulker-pg-v1.0/ \
  -H "X-API-Key: spgk_..." \
  -d "action=expire_request&payment_request_id=SPGR_A1B2C3"

Log analytics event

Internal endpoint used by the checkout page to track user behaviour. No API key required — uses the payment request ID as a token.

Complete payment

Called by the checkout page after a successful Razorpay payment. No API key required — uses a checkout token for authorisation.

Checkout flow (frontend)

1. Create a payment request via the API → get checkout_url.
2. Redirect the user to that URL (or embed it).
3. The checkout page automatically detects the user’s country & currency (via ipapi.co) and shows the branded form.
4. User fills in name, email, phone → selects payment method (UPI / card / net banking / wallet).
5. Razorpay modal opens → user completes payment.
6. On success, the page calls complete_payment → logs data, fires webhook, redirects to your redirect_url.

Webhooks

When a payment is completed, Shulker sends a POST request to your configured webhook_url with a JSON payload and a X-SPG-Signature header (HMAC‑SHA256 of the raw body using your webhook_secret).

{
    "event": "payment.completed",
    "payment_request_id": "SPGR_A1B2C3",
    "amount_usd": 49.99,
    "currency": "INR",
    "display_amount": 4699.06,
    "payment_method": "card",
    "txn_id": "pay_xyz",
    "payer": {
        "name": "John Doe",
        "email": "[email protected]",
        "country": "IN"
    },
    "metadata": { "user_id": 12345 },
    "completed_at": "2026-09-09T14:20:00+00:00"
}

Best practices