---
title: Custom PG Documentation
slug: custom-pg-documentation
docTags: 
createdAt: 2025-05-28T07:34:39.096Z
---

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:
  1. The Authorization header during payment creation.
  2. 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: 

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

### 🔐 Headers

```php
Authorization: Bearer your_auth_token
Content-Type: application/json
```

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

### ✅ Expected Response

```json
{
  "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:

```php
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: 

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

### 🔐 Webhook Headers 

```php
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.