Custom PG Documentation

This guide helps you integrate your payment provider with our system using our Custom Payment Gateway setup. We support:

Redirect-based checkout for customers.

Webhook-based confirmation for payment status.

🔐 Step 1: Setup & Authentication

To integrate with our system, you need to provide:

Key	Description
url	Base URL of your Payment API
auth_token	Token used for authentication (both API & webhook)

You’ll set these values in the Admin Panel while configuring your payment gateway.

📌 Note:

The auth_token is used as a Bearer Token in:

The Authorization header during payment creation.

The Authorization header when your system sends the webhook.

🧾 Step 2: Creating a Payment

When a customer places an order, we’ll call your url with the following request:

▶️ Sample Request

We will send this payload to your system:

{
  "amount": 25000,                // In minor units (e.g., paise, cents)
  "currency": "INR",
  "customer_name": "John Doe",
  "customer_email": "[email protected]"
  "customer_phone": "+911234567890",
  "reference_id": "ORDER123_INTENT456", // Unique reference
  "return_url": "https://example.com/payment/success",
  "cancel_url": "https://example.com/payment/fail"
}

🔐 Headers

Authorization: Bearer your_auth_token
Content-Type: application/json

Your system should return a payment URL where we redirect the user:

✅ Expected Response

{
  "payment_url": "https://yourpaymentgateway.com/checkout/txn123"
}

The user is redirected to this payment_url to complete the payment.

🔔 Step 3: Sending Webhooks (Required)

Once the transaction is complete (either success or failure), your system must notify us via webhook.

📬 Webhook URL

Your unique webhook URL is auto-generated and visible in the Admin Panel under the “Environment” tab. It looks like:

https://api.hyperzod.app/public/v1/payment/pg/webhook/custompg/{tenant_id}

📦 Webhook Payload

Send a POST request to the webhook URL with the following structure:

{
  "transaction_id": "TXN123456",
  "transaction_status": "completed",       // completed / failed
  "reference_id": "ORDER123_INTENT456",
  "currency_code": "INR",
  "amount": 25000,
  "tenant_id": "your-tenant-id"
}

🔐 Webhook Headers

Authorization: Bearer your_auth_token
Content-Type: application/json

📘 transaction_status Values

Value	Description
completed	Payment successful
failed	Payment failed

Any other status will be treated as pending.

✅ Webhook Validation

We validate the Authorization header in the webhook request.

If the token doesn’t match what you set in the panel, we’ll reject the request.

✅ Make sure your webhook server handles retries in case of temporary failure.