# Add / Update Beneficial Owner
Source: https://payglocal.in/docs/api-reference/add-beneficial-owner

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner
Submits or replaces the complete list of Ultimate Beneficial Owners (UBOs).
The array completely replaces the existing list — always send all UBOs together.
Cannot be updated after the verification step is complete.


## When to Use

Submits or replaces the list of Ultimate Beneficial Owners (UBOs) for a merchant.

<Warning>
  The array sent in the request body **completely replaces** the existing list of beneficial owners. Always send all UBOs in a single request — partial updates are not supported.
</Warning>

A **beneficial owner** is any individual holding more than **10% equity** in the entity. For Partnerships, LLPs, and Companies, include every such individual with their PAN and shareholding percentage. See [Merchant Requirements](/docs/guides/merchant-requirements#documents-by-entity-type) for the full list per entity type.

Beneficial owner details cannot be updated after the merchant's verification step is complete.

## Error Scenarios

| Scenario                                             | HTTP Code |
| ---------------------------------------------------- | --------- |
| Required fields missing or empty                     | `400`     |
| PAN is not a personal PAN (type `P`)                 | `400`     |
| PAN does not exist                                   | `400`     |
| Update attempted after verification step is complete | `400`     |
| `onboardingId` does not exist                        | `404`     |
| `onboardingId` does not belong to this partner       | `403`     |


# Callback Handling — Node.js
Source: https://payglocal.in/docs/api-reference/callback-handling

Complete Node.js implementation for receiving and processing PayGlocal payment callbacks.

This page contains the complete Node.js implementation for handling the `merchantCallbackURL` endpoint. For a conceptual explanation of the callback flow, see [Payment Response Handling](/docs/merchant/payment-response-handling).

***

## What This Endpoint Does

PayGlocal POSTs to this endpoint after every payment — success or failure. The endpoint:

1. Extracts the `x-gl-token` from the request body
2. Decodes the JWT payload to read the payment data
3. Checks the `status` field
4. Updates your order and redirects the customer accordingly

***

## Implementation

```javascript theme={null}
app.post('/payments/merchantCallback', async (req, res) => {
  try {
    // Step 1: Extract token
    const glToken = req.body['x-gl-token'];
    if (!glToken) {
      return res.status(400).send('Token missing');
    }

    // Step 2: Split token by dot — JWT has 3 parts: header.payload.signature
    const tokenParts = glToken.split('.');
    const base64UrlPayload = tokenParts[1];

    // Step 3: Convert base64url to base64
    // base64url uses - and _ instead of + and /
    const base64Payload = base64UrlPayload
      .replace(/-/g, '+')
      .replace(/_/g, '/');

    // Step 4: Decode base64 to string
    const decodedString = Buffer
      .from(base64Payload, 'base64')
      .toString('utf-8');

    // Step 5: Parse JSON
    const paymentData = JSON.parse(decodedString);

    // Step 6: Extract payment details
    const { status, merchantTxnId, amount, gid } = paymentData;

    // Step 7: Handle success/failure
    if (status === 'SENT_FOR_CAPTURE') {
      // Payment successful — update order and redirect to success page
      await updateOrderStatus(merchantTxnId, 'paid');
      await sendConfirmationEmail(merchantTxnId);

      return res.redirect(
        `https://your-domain.com/payment/success?txnId=${merchantTxnId}`
      );
    } else {
      // Payment failed — update order and redirect to failure page
      await updateOrderStatus(merchantTxnId, 'failed');

      return res.redirect(
        `https://your-domain.com/payment/failure?txnId=${merchantTxnId}`
      );
    }
  } catch (error) {
    console.error('Error processing payment callback:', error);
    res.status(500).send('Internal server error');
  }
});
```

***

## Step-by-Step Breakdown

| Step                      | What it does                                                      |
| ------------------------- | ----------------------------------------------------------------- |
| **1 — Extract token**     | Reads `x-gl-token` from POST body. Returns 400 if missing.        |
| **2 — Split by dot**      | Splits the JWT into 3 parts. Takes index 1 — the Payload.         |
| **3 — Convert base64url** | Swaps `-` → `+` and `_` → `/` to get standard Base64.             |
| **4 — Decode Base64**     | Converts Base64 to a UTF-8 string (raw JSON).                     |
| **5 — Parse JSON**        | Parses the string into a usable JavaScript object.                |
| **6 — Extract fields**    | Pulls `status`, `merchantTxnId`, `amount`, `gid` from the object. |
| **7 — Handle result**     | `SENT_FOR_CAPTURE` → success. Anything else → failure.            |

***

## Decoded Payload Structure

```json theme={null}
{
  "country": "UNITED KINGDOM",
  "amount": "48",
  "gid": "PGL_7F8A9B3C2D1E4F5A",
  "merchantId": "MERCH_9X8Y7Z6W5V4U3T",
  "cardType": "PREPAID",
  "merchantTxnId": "TXN_4K5L6M7N8O9P0Q",
  "paymentMethod": "CARD",
  "currency": "USD",
  "cardBrand": "VISA",
  "status": "SENT_FOR_CAPTURE"
}
```

***

## Key Notes

<Note>
  Replace `updateOrderStatus` and `sendConfirmationEmail` with your own database and email logic. These are placeholders representing actions you implement.
</Note>

<Warning>
  `SENT_FOR_CAPTURE` is the **only success status**. Every other status — `ISSUER_DECLINE`, `CUSTOMER_CANCELLED`, `ABANDONED`, `GENERAL_DECLINE` — must be treated as a failure and redirect to your failure page.
</Warning>

<Note>
  Replace `https://your-domain.com/payment/success` and `https://your-domain.com/payment/failure` with your actual success and failure page URLs.
</Note>


# CodeDrop Integration Reference
Source: https://payglocal.in/docs/api-reference/codedrop

Complete technical reference for integrating CodeDrop — annotated code examples for every step.

CodeDrop embeds PayGlocal's payment experience directly on your page. No redirect. The payment form opens as a popup (modal, drawer, or inline widget) and closes itself automatically when the payment is done.

For a conceptual overview and step-by-step walkthrough, see [CodeDrop in Getting Started](/docs/merchant/paycollect/codedrop).

***

## Backend Implementation

Before your frontend can launch CodeDrop, your server must call PayGlocal's Initiate Payment API and return the `redirectUrl` to your UI. CodeDrop will use this URL to load the payment form.

***

## Step 1 — Enable CodeDrop for Your MID

Contact your PayGlocal account manager. The operations team will enable CodeDrop for your Merchant ID and provide a **`cdId`** — your CodeDrop configuration identifier.

***

## Step 2 — Add the Script Tag

Add this script tag to your HTML `<head>` or at the end of `<body>`:

<img alt="CodeDrop script tag template" />

**Parameters:**

| Attribute           | Required | Description                             |
| ------------------- | -------- | --------------------------------------- |
| `src`               | Yes      | CodeDrop script URL (UAT or Production) |
| `data-display-mode` | Yes      | `drawer` / `modal` / `inline`           |
| `data-cd-id`        | Yes      | Your `cdId` from PayGlocal              |
| `defer`             | Yes      | Load script after HTML parsing          |

**Script URLs:**

| Environment | URL                                           |
| ----------- | --------------------------------------------- |
| UAT         | `https://codedrop.uat.payglocal.in/simple.js` |
| Production  | `https://codedrop.payglocal.in/simple.js`     |

**Example** — modal mode, UAT environment, cdId `123456789`:

<img alt="CodeDrop script tag example for modal mode" />

```html theme={null}
<script
  src="https://codedrop.uat.payglocal.in/simple.js"
  data-display-mode="modal"
  data-cd-id="123456789"
  defer
></script>
```

***

## Step 3 — Add Payment Container *(Inline mode only)*

For `inline` display mode, place this container `<div>` at the location in your page where the payment form should render:

<img alt="Inline payment container div" />

```html theme={null}
<div
  id="PayGlocal_payments"
  data-width="400px"
></div>
```

| Attribute    | Required      | Notes                                |
| ------------ | ------------- | ------------------------------------ |
| `id`         | **Mandatory** | Must be exactly `PayGlocal_payments` |
| `data-width` | Optional      | `350px`–`450px`. Default: `400px`    |

Skip this step for `modal` and `drawer` modes.

***

## Step 4 — Launch the Payment Form

When the customer clicks your payment button, pass the `redirectUrl` from your backend to CodeDrop:

<img alt="window.PGPay.launchPayment call" />

```javascript theme={null}
window.PGPay.launchPayment({
  redirectUrl: '<redirectUrl>'
});
```

**Full example** — fetching `redirectUrl` from your backend via axios, then launching CodeDrop:

<img alt="displayPaymentPage function example" />

```javascript theme={null}
function displayPaymentPage() {
  axios
    .get("<merchantPayNowApi>")
    .then((res) => {
      window.PGPay.launchPayment({
        redirectUrl: res.data.redirectUrl
      });
    });
}
```

Replace `<merchantPayNowApi>` with your backend endpoint that returns the `redirectUrl`.

***

## Step 5 — Handle the Payment Callback

After the payment completes, is cancelled, or is abandoned, CodeDrop closes automatically and invokes your callback function. Pass it as the second argument to `launchPayment()`:

<img alt="paymentCallback function and launchPayment with callback" />

```javascript theme={null}
function paymentCallback(data) {
  // handle payment status based on data parameter
}

window.PGPay.launchPayment(
  { redirectUrl: res.data.redirectUrl },
  paymentCallback
);
```

**The `data` object your callback receives:**

<img alt="Callback data object with gid, status, merchantTxnId, x-gl-token" />

```javascript theme={null}
const data = {
  gid: "gl_o-62693b07-1059-45f3-b353-d65cbfa2bee1",
  // Can be used to identify the transaction in GCC (Global Control Center)

  status: "SENT_FOR_CAPTURE",
  // Gives you the current status — complete, cancelled, abandoned, etc.

  merchantTxnId: "23AEE8CB6B62EE2AF07",
  // If provided by you in the original request, returned here for your validation

  "x-gl-token": "eyJpc3N1ZWQtYnkiOiJHbG9jYWwiLCJpYXQiOiJ..."
  // Can be used to fetch full transaction status from PayGlocal server
};
```

| Field           | Type   | Description                                                                          |
| --------------- | ------ | ------------------------------------------------------------------------------------ |
| `gid`           | String | PayGlocal transaction ID — use in GCC or Status Check API                            |
| `status`        | String | Current payment status (`SENT_FOR_CAPTURE`, `CUSTOMER_CANCELLED`, `ABANDONED`, etc.) |
| `merchantTxnId` | String | Your transaction reference, echoed back for validation                               |
| `x-gl-token`    | String | Token to fetch full status from PayGlocal                                            |

***

## Step 6 — Custom Pay Now Action *(Inline mode only)*

If you hide the default PayNow button inside the inline form and use your own, wire your button's `onclick` to:

<img alt="payNowClicked function using window.PGPay.handlePayNow" />

```javascript theme={null}
function payNowClicked(event) {
  // perform custom action
  window.PGPay.handlePayNow(event);
}
```

The `event` parameter is the `onclick` event of your PayNow button element and is **mandatory**.

***

## Step 7 — Pass Updated Billing & Shipping Details *(Inline mode only)*

If your billing and shipping forms are on the same page as the inline payment widget, the customer might update their address after the widget has already loaded. Use this to push updated details to the payment form in real time:

<img alt="updateData function using window.PGPay.modifyPayment" />

```javascript theme={null}
function updateData() {
  const merchantPayload = {};
  window.PGPay.modifyPayment(merchantPayload);
}
```

**`merchantPayload` format:**

<img alt="merchantPayload structure with billingData and shippingData" />

```javascript theme={null}
const merchantPayload = {
  paymentData: {
    billingData: {
      firstName: "John",
      lastName: "Doe",
      emailId: "something@gmail.com",
      addressStreet1: "Block-2B",
      addressStreet2: "Hamilton street",
      addressCity: "Bangalore",
      addressState: "Karnataka",
      addressCountry: "IN",
      addressPostalCode: "123456"
    }
  },
  riskData: {
    shippingData: {
      firstName: "John",
      lastName: "Doe",
      emailId: "something@gmail.com",
      addressStreet1: "street 1",
      addressStreet2: "street 2",
      addressCity: "Bangalore",
      addressState: "Karnataka",
      addressCountry: "IN",
      addressPostalCode: "123456"
    }
  }
};
```

**Rules:**

* You can send `billingData`, `shippingData`, or both — any fields you omit are left unchanged
* Data entered directly by the customer on the payment form always takes highest priority — if the customer typed something, it overrides what you send here


# Configure Products and Fees
Source: https://payglocal.in/docs/api-reference/configure-products

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/products
Configures which payment products to enable for the merchant and sets fee structures.
All card networks must be included when enabling INTERNATIONAL_CARDS_AND_ALT_PAYS.


## When to Use

Configures which payment products to enable for the merchant and sets the fee structure for each. Must be completed **before** triggering [Get Verification Redirect](/docs/api-reference/get-verification-redirect).

## Fee Structure Rules

The `productFees` object is keyed by product name. The shape of each value depends on the product:

* **`GLOBAL_FUND_TRANSFER`** — single object with `feeType` (`FIXED` or `PERCENTAGE`) and `fee` (number).
* **`INTERNATIONAL_CARDS_AND_ALT_PAYS`** — **array** of objects, one entry per card network. All five card networks must be present: `AMERICAN_EXPRESS`, `DINERS`, `DISCOVER`, `OTHER_DEBIT_CARDS`, `OTHER_CREDIT_CARDS`.
* **`DOMESTIC_CARDS_UPI_AND_INB`** — single object with `feeType` (`FIXED` or `PERCENTAGE`) and `feeRate` (up to 2 decimal places).

Enable all three products in the `products` array to offer the full PayGlocal product suite.

## Error Scenarios

| Scenario                                       | HTTP Code |
| ---------------------------------------------- | --------- |
| Missing required fields                        | `400`     |
| Invalid field format                           | `400`     |
| `onboardingId` does not exist                  | `404`     |
| `onboardingId` does not belong to this partner | `403`     |


# Create Onboarding
Source: https://payglocal.in/docs/api-reference/create-onboarding

POST /gcc/v2/partner/merchant/onboard
Creates a new merchant onboarding record. This is always the first API call in the
onboarding sequence. The `onboardingId` returned is required for all subsequent calls.


## When to Use

Always the **first API call** in the onboarding sequence. The `onboardingId` returned in the response is required as a path parameter for every subsequent call.

A merchant is uniquely identified by their PAN. Each PAN can have only one active onboarding record in the PayGlocal system.

Valid PAN types: `P` (Individual), `C` (Company), `T` (Trust), `F` (Firm).

## Error Scenarios

| Scenario                                   | HTTP Code |
| ------------------------------------------ | --------- |
| Required fields missing or empty           | `400`     |
| Invalid field format                       | `400`     |
| PAN type is not one of P, C, T, F          | `400`     |
| PAN already exists in the PayGlocal system | `400`     |
| PAN does not exist (invalid PAN)           | `400`     |


# Get Business Categories
Source: https://payglocal.in/docs/api-reference/get-business-categories

GET /gcc/v2/partner/merchant/onboard/business-category
Returns the complete list of supported business category codes and subcategory codes.
Use subcategory codes (e.g., BUS.IT_SERVICES) as the value for the natureOfBusiness
field in Update Business Details.


## When to Use

Returns the full list of supported business category codes and their subcategory codes. Use the **subcategory code** (dotted format, e.g., `BUS.IT_SERVICES`) as the value for `natureOfBusiness` in [Update Business Details](/docs/api-reference/update-business-details).

For a static reference, see [Business Categories](/docs/reference/business-categories).


# Get Onboarding Status
Source: https://payglocal.in/docs/api-reference/get-status

GET /gcc/v2/partner/merchant/onboard/{onboardingId}/status
Retrieves the current onboarding status and all submitted information for a merchant.
Always call this endpoint server-to-server after the merchant completes the
iFrame verification flow to confirm final status.


## When to Use

Retrieves the current onboarding status and all submitted information for a merchant.

<Warning>
  After the merchant completes the iFrame verification flow, always call this endpoint server-to-server to confirm `vkyc` and `digiLocker` are `COMPLETE`. Do not rely on the callback redirect alone.
</Warning>

## Error Scenarios

| Scenario                                       | HTTP Code |
| ---------------------------------------------- | --------- |
| `onboardingId` does not exist                  | `404`     |
| `onboardingId` does not belong to this partner | `403`     |


# Get Verification Redirect
Source: https://payglocal.in/docs/api-reference/get-verification-redirect

PUT /gcc/v2/partner/merchant/verification/{onboardingId}/redirect

## When to Use

Call this endpoint after all data-collection steps are complete to obtain a `redirectLink` for the merchant verification iFrame. The URL loads the PayGlocal partner onboarding experience where the merchant completes T\&C acknowledgement, DigiLocker, and VKYC.

Use this as **step 8** in the onboarding sequence — after [Configure Products](/docs/api-reference/configure-products) and before polling [Get Onboarding Status](/docs/api-reference/get-status).

<Warning>
  This endpoint can only be called when every pre-verification checklist step is complete. Calling it earlier returns `400 Bad Request`. It cannot be called again after DigiLocker, VKYC, and T\&C are all complete.
</Warning>

## Preconditions

The following checklist fields must **not** be `INCOMPLETE` before calling this endpoint:

| Checklist field       | Step                                                                   |
| --------------------- | ---------------------------------------------------------------------- |
| `businessDetails`     | [Update Business Details](/docs/api-reference/update-business-details) |
| `beneficialOwners`    | [Add Beneficial Owner](/docs/api-reference/add-beneficial-owner)       |
| `bankDetails`         | [Update Bank Details](/docs/api-reference/update-bank-details)         |
| `authorisedSignatory` | [Update Auth Signatory](/docs/api-reference/update-auth-signatory)     |
| `documents`           | [Upload Documents](/docs/api-reference/upload-documents)               |
| `productsAndFees`     | [Configure Products](/docs/api-reference/configure-products)           |

Poll `GET /status` and confirm `documentsToBeUploaded` is empty before calling redirect.

## Notes

* Authenticate with `x-gl-auth` and `x-gl-digest` — sign the **raw JSON request body** (same as other PUT endpoints). See [Authentication](/docs/authentication).
* Request field is `callBackUrl` (camelCase with capital **B**).
* Response field is `redirectLink`, not `redirectUrl`.
* `redirectLink` format: `{baseUrl}?token={sessionToken}&onboardingId={onboardingId}`. The session token is valid for **24 hours** and must not be cached or reused.
* `callBackUrl` is persisted on the merchant record and used as the post-verification redirect target. Its domain must be [whitelisted](/docs/guides/iframe-integration#step-1-domain-whitelisting-action-required).
* Environment base URLs for `redirectLink`:

| Environment | Base URL                                                    |
| ----------- | ----------------------------------------------------------- |
| UAT         | `https://uat.dashboard.payglocal.in/app/partner-onboarding` |
| Production  | `https://dashboard.payglocal.in/app/partner-onboarding`     |

## What Happens Server-Side

1. Validates the onboarding checklist via `isVerificationAllowed()`.
2. Stores `callBackUrl` on the merchant record.
3. Generates a single-use session token (24-hour TTL).
4. Returns the composed `redirectLink` for iFrame embedding.

See [iFrame Integration](/docs/guides/iframe-integration) for embed instructions and [Partner Onboarding Events](/docs/guides/partner-onboarding-events) for completion signals.

## Error Scenarios

| Scenario                                                               | HTTP Code |
| ---------------------------------------------------------------------- | --------- |
| One or more pre-verification checklist steps are incomplete            | `400`     |
| Verification already completed (DigiLocker + VKYC + T\&C all complete) | `400`     |
| Missing or invalid `callBackUrl`                                       | `400`     |
| Invalid or missing `x-gl-auth` / `x-gl-digest`                         | `401`     |
| `onboardingId` does not exist                                          | `404`     |


# Fetch Virtual Accounts
Source: https://payglocal.in/docs/api-reference/mca/account-fetch

GET /gcc/v3/merchants/{merchantId}/ffms/virtualAccounts
Returns all global virtual account details assigned to a fully activated merchant,
grouped by collection label and settlement currency.


## When to Use

Call this after a merchant is **fully activated** on PayGlocal to retrieve their assigned global virtual accounts. Accounts are grouped by collection label (e.g. `general`) and within each label by currency code.

<Note>
  Returns data only for activated merchants. Calling for a merchant still in onboarding or pending review returns HTTP 401.
</Note>

## Response Structure

The `data` object is a two-level map:

```
data
└── <collection_label>        (e.g. "general")
    └── <currency_code>       (e.g. "USD", "AUD", "GBP")
        └── VirtualAccount    (account number, bank name, routing code, etc.)
```

## Error Scenarios

| Scenario                  | HTTP Code |
| ------------------------- | --------- |
| `merchantId` is not valid | `400`     |
| Merchant is not activated | `401`     |


# Upload Document via Presigned URL
Source: https://payglocal.in/docs/api-reference/mca/document-upload

POST /gcc/v1/ffms/external/transaction/{gid}/upload-presigned
Attaches a supporting document (e.g. invoice) to an FFMS transaction using a presigned
URL you already control. Provide the `presignedUrl` in the request body; the backend
downloads the file from that URL and stores it. This is a single-call alternative to
uploading the file directly as multipart form data.


## When to Use

Call this when you receive an `MCA_FUND_RECEIVED` webhook with status `DOCUMENT_PENDING` and you already have the supporting document (e.g. invoice) hosted at a presigned URL you control. Include that `presignedUrl` in the request body — the backend downloads the file from it and stores it for the transaction. This is a single-call alternative to uploading the file directly as multipart form data.

## Upload Flow

```
POST this endpoint with presignedUrl in the request body → document is fetched and stored
```

<Warning>
  The `presignedUrl` you provide must be reachable at the time of the request — the backend
  fetches it immediately during this call. It is not stored or reused afterward.
</Warning>

## Error Scenarios

| Scenario                                       | HTTP Code |
| ---------------------------------------------- | --------- |
| Missing or invalid fields                      | `400`     |
| Invalid or missing API key                     | `401`     |
| `merchantId` does not match the transaction    | `403`     |
| `gid` does not exist                           | `404`     |
| Document already uploaded for this transaction | `409`     |
| Internal server error                          | `500`     |


# MCA Demo Funding Ingestion
Source: https://payglocal.in/docs/api-reference/mca/mca-ingestion

POST /gcc/v1/ffms/transaction/demo-funding/{transactingMid}/mca-ingestion
Simulates an inbound funding event for MCA testing. Available in the UAT (sandbox)
environment only — do not use for production transactions.


## When to Use

Use this endpoint to test MCA ingestion by simulating an inbound funding event for a given `transactingMid`.

<Warning>
  This endpoint is available in the **UAT (sandbox) environment only**. Do not use it for production traffic.
</Warning>


# MCA APIs
Source: https://payglocal.in/docs/api-reference/mca/overview

API reference for Merchant Collection Accounts — virtual account fetch and transaction document upload.

<Note>
  These APIs are for **Partners** managing Merchant Collection Accounts. Merchants must be fully activated before the Account Fetch API returns data.
</Note>

## Endpoints

| Endpoint                                                            | Method | Description                                                            |
| ------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| [Fetch Virtual Accounts](/docs/api-reference/mca/account-fetch)     | `GET`  | Retrieve all global accounts assigned to a merchant, keyed by currency |
| [Get Upload Presigned URL](/docs/api-reference/mca/document-upload) | `POST` | Generate a presigned URL to upload a transaction document              |

***

## Authentication

Both endpoints authenticate via the `x-api-key` header. No request signing is required — API key only.

***

## Servers

| Environment | Base URL                        |
| ----------- | ------------------------------- |
| Production  | `https://gcc.prod.payglocal.in` |
| Sandbox     | `https://gcc.uat.payglocal.in`  |

***

## Integration Guide

For the conceptual walkthrough — lifecycle states, webhook events, and the full upload flow — see the [MCA Integration Guide](/docs/mca/overview).

<CardGroup>
  <Card title="MCA Overview" icon="book" href="/docs/mca/overview">
    What MCA is, how it works, and how to integrate.
  </Card>

  <Card title="MCA Webhooks Guide" icon="bell" href="/docs/mca/webhooks">
    All four lifecycle events and how to handle them.
  </Card>
</CardGroup>


# Partner Merchant Onboarding API
Source: https://payglocal.in/docs/api-reference/onboarding-overview

Overview of the PayGlocal Partner Merchant Onboarding API — the sequential call flow, authentication, and quick links to all 10 endpoints.

<Note>
  This API is for **Partners** onboarding their own sub-merchants onto PayGlocal. If you are a merchant looking to accept payments, see [Checkout Flow (PayCollect)](/docs/api-reference/payments-v2/paycollect/overview) or [Seamless Flow (PayDirect)](/docs/api-reference/payments-v2/paydirect/overview) instead.
</Note>

## What Is the Partner Merchant Onboarding API?

The **Partner Merchant Onboarding API** lets technology partners programmatically onboard sub-merchants onto the PayGlocal platform. It handles the full compliance lifecycle: KYC data collection, document upload, bank account verification, product configuration, and triggered VKYC.

<Note>
  The interactive API explorer on each endpoint page lets you test requests directly from this portal. Set your `x-gl-auth` and `x-gl-digest` headers in the authentication panel (top-right of the endpoint page) to make live Sandbox calls.
</Note>

***

## Call Sequence

The Onboarding API is **sequential and stateful**. Each step enriches the merchant record and PayGlocal validates completeness before the final verification step can be triggered.

```
Partner System                          PayGlocal API
      │                                       │
      │  POST /onboard  ─────────────────────▶│  Creates merchant record
      │◀────────────────  onboardingId  ───────│
      │                                       │
      │  PUT /business-details ──────────────▶│
      │  PUT /beneficial-owner ──────────────▶│
      │  PUT /bank-details ──────────────────▶│  Penny drop validation
      │  PUT /auth-signatory ────────────────▶│
      │  PUT /docs (repeat per doc) ─────────▶│
      │  PUT /products ──────────────────────▶│
      │                                       │
      │  PUT /verification/{id}/redirect ────▶│  Generates VKYC URL
      │◀──────────────── redirectLink ──────────│
      │                                       │
      │  GET /status ────────────────────────▶│  Confirm final outcome
      │◀─────────────────────────────────────│
```

***

## Endpoint Reference

| Step | Endpoint                                                                   | Method | Notes                                                              |
| ---- | -------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| 1    | [Create Onboarding](/docs/api-reference/create-onboarding)                 | POST   | Returns `onboardingId` — required for all subsequent calls         |
| 2    | [Update Business Details](/docs/api-reference/update-business-details)     | PUT    | Cannot update after T\&C acknowledgement                           |
| 3    | [Add Beneficial Owner](/docs/api-reference/add-beneficial-owner)           | PUT    | Array replaces existing UBOs — always send all together            |
| 4    | [Update Bank Details](/docs/api-reference/update-bank-details)             | PUT    | Penny drop verification runs automatically                         |
| 5    | [Update Auth Signatory](/docs/api-reference/update-auth-signatory)         | PUT    | Phone/email used for VKYC — must be accurate                       |
| 6    | [Upload Documents](/docs/api-reference/upload-documents)                   | PUT    | One call per document                                              |
| 7    | [Configure Products](/docs/api-reference/configure-products)               | PUT    | Select products and configure fee structures                       |
| 8    | [Get Verification Redirect](/docs/api-reference/get-verification-redirect) | PUT    | Returns `redirectLink` for iFrame verification (24h session token) |
| 9    | [Get Onboarding Status](/docs/api-reference/get-status)                    | GET    | Always confirm server-side after VKYC redirect                     |
| —    | [Get Business Categories](/docs/api-reference/get-business-categories)     | GET    | Lookup table for `natureOfBusiness` field                          |

***

## Authentication

The Onboarding API uses **HmacSHA256 request signing**:

* `x-gl-auth` — your static API Key
* `x-gl-digest` — per-request HMAC-SHA256 signature, Base64-encoded

See [Authentication](/docs/authentication) for the full signing specification and multi-language code examples.

***

## Onboarding Status Lifecycle

| Status                 | Meaning                                              |
| ---------------------- | ---------------------------------------------------- |
| `INITIATED`            | Onboarding record created, details not yet submitted |
| `IN_PROGRESS`          | One or more detail sections submitted                |
| `PENDING_VERIFICATION` | All details submitted, awaiting merchant VKYC        |
| `PENDING_REVIEW`       | VKYC complete, under PayGlocal compliance review     |
| `APPROVED`             | Merchant fully onboarded and activated               |
| `REJECTED`             | Onboarding rejected after review                     |
| `RFI`                  | Request for Information — additional data required   |

***

## Key Constraints

* `externalOnboardingId` must be unique per merchant — it cannot be reused.
* Business details and auth signatory cannot be updated after T\&C acknowledgement.
* Beneficial owner and bank details cannot be updated after verification is complete.
* Calling the verification redirect endpoint before all required steps are complete returns `400 Bad Request`.

<CardGroup>
  <Card title="Onboarding Flow Guide" icon="diagram-project" href="/docs/guides/api-flow-overview">
    Step-by-step walkthrough with state transitions explained.
  </Card>

  <Card title="iFrame Verification" icon="browser" href="/docs/guides/iframe-integration">
    How to embed the VKYC and DigiLocker flow in your product.
  </Card>

  <Card title="Events & Webhooks" icon="bell" href="/docs/guides/partner-onboarding-events">
    UI postMessage and server-side webhook notifications.
  </Card>
</CardGroup>


# Payload Templates
Source: https://payglocal.in/docs/api-reference/payload-templates

Ready-to-use request payloads for every PayGlocal API — select, copy, and integrate.

All payloads below are valid, copy-ready JSON. Select the tab matching your use case, copy the payload, and adapt the values to your integration. Every payload includes `merchantUniqueId` — a required field for all requests.

***

## 1. Payment Initiation Payloads

Payloads for initiating a one-time payment via PayGlocal. Select your merchant category to see the matching payload.

<div>
  <span>
    <svg>
      <path />
    </svg>

    scroll
  </span>

  <span>
    scroll

    <svg>
      <path />
    </svg>
  </span>
</div>

<Tabs>
  <Tab title="Minimum">
    The bare minimum fields required to initiate a payment. Use this as a starting point.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "15",
        "txnCurrency": "USD"
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="Ecommerce / Shipping">
    For stores that ship physical goods. Includes billing and shipping address data.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "15",
        "txnCurrency": "USD",
        "billingData": {
          "firstName": "John",
          "lastName": "Denver",
          "addressStreet1": "Test123",
          "addressStreet2": "Punctuality lane",
          "addressCity": "Bangalore",
          "addressState": "Karnataka",
          "addressPostalCode": "560094",
          "addressCountry": "IN",
          "emailId": "johndenver@myemail.com"
        }
      },
      "riskData": {
        "shippingData": {
          "firstName": "John",
          "lastName": "Denver",
          "addressStreet1": "Test123",
          "addressStreet2": "Punctuality lane",
          "addressCity": "Bangalore",
          "addressState": "Karnataka",
          "addressPostalCode": "560094",
          "addressCountry": "IN",
          "emailId": "johndenver@myemail.com",
          "callingCode": "+91",
          "phoneNumber": "9008018469"
        }
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="SaaS / Service">
    For digital products or services where no shipping address is needed.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "15",
        "txnCurrency": "USD",
        "billingData": {
          "firstName": "John",
          "lastName": "Denver",
          "addressStreet1": "Test123",
          "addressStreet2": "Punctuality lane",
          "addressCity": "Bangalore",
          "addressState": "Karnataka",
          "addressPostalCode": "560094",
          "addressCountry": "IN",
          "emailId": "johndenver@myemail.com"
        }
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="Flight — One Way">
    For one-way flight bookings. Includes passenger and leg data.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "101",
        "txnCurrency": "INR",
        "billingData": {
          "firstName": "Sam",
          "lastName": "Thomas",
          "addressStreet1": "Apartment 9B, 235 East, 43rd Street",
          "addressCity": "New York",
          "addressState": "New York",
          "addressCountry": "US",
          "emailId": "sam.thomas@gmail.com"
        }
      },
      "riskData": {
        "flightData": [
          {
            "journeyType": "ONEWAY",
            "ticketNumber": "ticket12345",
            "reservationDate": "20251201",
            "legData": [
              {
                "routeId": "1",
                "legId": "1",
                "flightNumber": "flight123",
                "departureAirportCode": "AUH",
                "departureCity": "Abu Dhabi",
                "departureCountry": "AE",
                "departureDate": "2023-03-20T09:01:56Z",
                "arrivalAirportCode": "BLR",
                "arrivalCity": "Bangalore",
                "arrivalCountry": "IN",
                "arrivalDate": "2023-03-21T09:01:56Z",
                "carrierCode": "AAL",
                "airlineServiceClass": "ECONOMY"
              }
            ],
            "passengerData": [
              {
                "firstName": "Sam",
                "lastName": "Thomas"
              }
            ]
          }
        ]
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="Flight — Return">
    For round-trip bookings with multiple legs and passengers.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF08",
      "paymentData": {
        "totalAmount": "2902",
        "txnCurrency": "INR",
        "billingData": {
          "firstName": "Roy",
          "lastName": "Thomas",
          "addressStreet1": "Apartment 9B, 235 East, 43rd Street",
          "addressCity": "New York",
          "addressState": "New York",
          "addressCountry": "US",
          "emailId": "sam.thomas@gmail.com"
        }
      },
      "riskData": {
        "billingData": {
          "emailId": "sam.thomas@gmail.com"
        },
        "flightData": [
          {
            "journeyType": "RETURN",
            "ticketNumber": "ticket56789",
            "reservationDate": "20250601",
            "legData": [
              {
                "routeId": "1",
                "legId": "1",
                "flightNumber": "NY123",
                "departureAirportCode": "JFK",
                "departureCity": "New York",
                "departureCountry": "US",
                "departureDate": "2024-06-10T08:00:00Z",
                "arrivalAirportCode": "AUH",
                "arrivalCity": "Abu Dhabi",
                "arrivalCountry": "AE",
                "arrivalDate": "2024-06-10T20:00:00Z",
                "carrierCode": "AAL",
                "airlineServiceClass": "ECONOMY"
              },
              {
                "routeId": "1",
                "legId": "2",
                "flightNumber": "AUH456",
                "departureAirportCode": "AUH",
                "departureCity": "Abu Dhabi",
                "departureCountry": "AE",
                "departureDate": "2024-06-11T02:00:00Z",
                "arrivalAirportCode": "BLR",
                "arrivalCity": "Bangalore",
                "arrivalCountry": "IN",
                "arrivalDate": "2024-06-11T08:00:00Z",
                "carrierCode": "AAL",
                "airlineServiceClass": "ECONOMY"
              },
              {
                "routeId": "2",
                "legId": "1",
                "flightNumber": "BLR789",
                "departureAirportCode": "BLR",
                "departureCity": "Bangalore",
                "departureCountry": "IN",
                "departureDate": "2024-06-20T10:00:00Z",
                "arrivalAirportCode": "AUH",
                "arrivalCity": "Abu Dhabi",
                "arrivalCountry": "AE",
                "arrivalDate": "2024-06-20T16:00:00Z",
                "carrierCode": "AAL",
                "airlineServiceClass": "ECONOMY"
              },
              {
                "routeId": "2",
                "legId": "2",
                "flightNumber": "AUH321",
                "departureAirportCode": "AUH",
                "departureCity": "Abu Dhabi",
                "departureCountry": "AE",
                "departureDate": "2024-06-21T00:00:00Z",
                "arrivalAirportCode": "JFK",
                "arrivalCity": "New York",
                "arrivalCountry": "US",
                "arrivalDate": "2024-06-21T10:00:00Z",
                "carrierCode": "AAL",
                "airlineServiceClass": "ECONOMY"
              }
            ],
            "passengerData": [
              { "firstName": "Sam", "lastName": "Thomas" },
              { "firstName": "John", "lastName": "Denver" }
            ]
          }
        ]
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="Hotel Booking">
    For hotel reservations. Includes lodging check-in/check-out and property details.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "TXN_1756806272401",
      "paymentData": {
        "totalAmount": "12000.00",
        "txnCurrency": "INR"
      },
      "merchantCallbackURL": "https://your-domain.com/callback",
      "riskData": {
        "lodgingData": [
          {
            "checkInDate": "20250104",
            "checkOutDate": "20250106",
            "city": "Mumbai",
            "country": "IN",
            "lodgingType": "Hotel",
            "lodgingName": "Lake View",
            "rating": "4",
            "cancellationPolicy": "NC"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Cab Booking">
    For cab or ride-hailing bookings with pickup leg data and passenger info.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "1756728697873338303",
      "captureTxn": false,
      "paymentData": {
        "totalAmount": "117800.00",
        "txnCurrency": "INR"
      },
      "riskData": {
        "cabData": [
          {
            "legData": [
              {
                "routeId": "1",
                "legId": "1",
                "pickupDate": "2023-03-20T09:01:56Z"
              }
            ],
            "passengerData": [
              {
                "firstName": "Sam",
                "lastName": "Thomas"
              }
            ]
          }
        ]
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>

  <Tab title="Train Booking">
    For train ticket bookings with departure/arrival city and passenger details.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "1756728697873338303",
      "captureTxn": false,
      "paymentData": {
        "totalAmount": "117800.00",
        "txnCurrency": "INR"
      },
      "riskData": {
        "trainData": [
          {
            "ticketNumber": "ticket12346",
            "reservationDate": "20230220",
            "legData": [
              {
                "routeId": "1",
                "legId": "1",
                "trainNumber": "train123",
                "departureCity": "Kannur",
                "departureCountry": "IN",
                "departureDate": "2023-03-20T09:01:56Z",
                "arrivalCity": "Coimbatore",
                "arrivalCountry": "IN",
                "arrivalDate": "2023-03-21T09:01:56Z"
              }
            ],
            "passengerData": [
              {
                "firstName": "Sam",
                "lastName": "Thomas",
                "dateOfBirth": "19980320",
                "passportCountry": "IN"
              }
            ]
          }
        ]
      },
      "merchantCallbackURL": "https://api.uat.payglocal.in/gl/v1/payments/merchantCallback"
    }
    ```
  </Tab>
</Tabs>

***

## 2. Standing Instruction (SI) Payloads

Payloads for creating and managing recurring payment mandates.

<div>
  <span>
    <svg>
      <path />
    </svg>

    scroll
  </span>

  <span>
    scroll

    <svg>
      <path />
    </svg>
  </span>
</div>

<Tabs>
  <Tab title="SI Initiate — Fixed">
    Creates a mandate with a fixed recurring amount auto-debited on a schedule.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "89",
        "txnCurrency": "USD"
      },
      "standingInstruction": {
        "data": {
          "amount": "89",
          "numberOfPayments": "12",
          "frequency": "MONTHLY",
          "type": "FIXED",
          "startDate": "20260601"
        }
      },
      "merchantCallbackURL": "https://www.yoursite.com/callback"
    }
    ```
  </Tab>

  <Tab title="SI Initiate — Variable">
    Creates a mandate where you trigger each charge manually with a variable amount.

    ```
    POST /gl/v1/payments/initiate/paycollect
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "500.00",
        "txnCurrency": "INR"
      },
      "standingInstruction": {
        "data": {
          "type": "VARIABLE",
          "frequency": "ONDEMAND",
          "numberOfPayments": "999",
          "maxAmount": "5000.00"
        }
      },
      "merchantCallbackURL": "https://yourwebsite.com/callback"
    }
    ```
  </Tab>

  <Tab title="SI On-Demand Sale">
    Triggers a manual deduction against an existing Variable SI mandate.

    ```
    POST /gl/v1/payments/si/sale
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "SALE-23AEE8CB6B62EE2AF07",
      "paymentData": {
        "totalAmount": "89"
      },
      "standingInstruction": {
        "mandateId": "md_94f0bb40-2664-4851-ab83-b86c618d3e15"
      }
    }
    ```
  </Tab>

  <Tab title="SI Status Check">
    Query the current status and details of an existing mandate.

    ```
    POST /gl/v1/payments/si/status
    ```

    ```json theme={null}
    {
      "merchantTxnId": "STATUS-23AEE8CB6B62EE2AF07",
      "standingInstruction": {
        "mandateId": "md_c87fcf0a-a62c-4dae-b001-ee69fee587c3"
      }
    }
    ```
  </Tab>

  <Tab title="SI Pause">
    Temporarily suspends a mandate — stops deductions without cancelling it.

    ```
    PUT /gl/v1/payments/si/status
    ```

    ```json theme={null}
    {
      "merchantTxnId": "PAUSE-23AEE8CB6B62EE2AF07",
      "standingInstruction": {
        "action": "PAUSE",
        "mandateId": "md_94f0bb40-2664-4851-ab83-b86c618d3e15"
      }
    }
    ```
  </Tab>

  <Tab title="SI Activate">
    Resumes a paused mandate and restarts recurring charges.

    ```
    PUT /gl/v1/payments/si/status
    ```

    ```json theme={null}
    {
      "merchantTxnId": "ACTIVATE-23AEE8CB6B62EE2AF07",
      "standingInstruction": {
        "action": "ACTIVATE",
        "mandateId": "md_94f0bb40-2664-4851-ab83-b86c618d3e15"
      }
    }
    ```
  </Tab>

  <Tab title="SI Cancel">
    Permanently revokes a mandate. This cannot be undone.

    ```
    PUT /gl/v1/payments/si/status
    ```

    ```json theme={null}
    {
      "merchantTxnId": "REVOKE-23AEE8CB6B62EE2AF07",
      "standingInstruction": {
        "action": "REVOKE",
        "mandateId": "md_94f0bb40-2664-4851-ab83-b86c618d3e15"
      }
    }
    ```
  </Tab>
</Tabs>

***

## 3. Auth & Capture Payloads

Payloads for hold-and-capture payment flows — authorize first, collect later.

<div>
  <span>
    <svg>
      <path />
    </svg>

    scroll
  </span>

  <span>
    scroll

    <svg>
      <path />
    </svg>
  </span>
</div>

<Tabs>
  <Tab title="Auth Initiation">
    Holds funds on the customer's card without charging. Use `isAuthPayment: true`.

    ```
    POST /gl/v1/payments/initiate
    ```

    ```json theme={null}
    {
      "merchantTxnId": "AUTH_TXN_20250122_001",
      "paymentData": {
        "totalAmount": "1000.00",
        "txnCurrency": "INR"
      },
      "captureTxn": false,
      "merchantCallbackURL": "https://yourwebsite.com/callback"
    }
    ```
  </Tab>

  <Tab title="Full Capture">
    Captures the full authorized amount. Use the `gid` returned from the auth response.

    ```
    POST /gl/v1/payments/{gid}/capture
    ```

    ```json theme={null}
    {
      "merchantTxnId": "CAP-23AEE8CB6B62EE2AF07"
    }
    ```
  </Tab>

  <Tab title="Partial Capture">
    Captures a specific amount less than what was authorized. The remainder is released.

    ```
    POST /gl/v1/payments/{gid}/capture
    ```

    ```json theme={null}
    {
      "merchantTxnId": "CAP-23AEE8CB6B62EE2AF07-1",
      "paymentData": {
        "totalAmount": "60.00"
      }
    }
    ```
  </Tab>

  <Tab title="Auth Reversal">
    Cancels the authorization and releases the held funds. Only possible before capture.

    ```
    POST /gl/v1/payments/{gid}/reversal
    ```

    ```json theme={null}
    {
      "merchantTxnId": "REV-23AEE8CB6B62EE2AF07"
    }
    ```
  </Tab>
</Tabs>

***

## 4. Status & Refund Payloads

Payloads for checking transaction status and initiating refunds.

<div>
  <span>
    <svg>
      <path />
    </svg>

    scroll
  </span>

  <span>
    scroll

    <svg>
      <path />
    </svg>
  </span>
</div>

<Tabs>
  <Tab title="Status Check">
    Query the real-time status of any transaction using its `gid`.

    ```
    GET /gl/v1/payments/{gid}/status
    ```

    No request body required. Pass the `gid` as a path parameter.

    ```
    GET https://api.uat.payglocal.in/gl/v1/payments/gl-13bbd3c4-9817-4786-96c6-12fa6191f118/status
    ```
  </Tab>

  <Tab title="Full Refund">
    Refunds the entire captured amount. Only possible on `SENT_FOR_CAPTURE` transactions.

    ```
    POST /gl/v1/payments/{gid}/refund
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "REFUND-23AEE8CB6B62EE2AF07",
      "refundType": "F"
    }
    ```
  </Tab>

  <Tab title="Partial Refund">
    Refunds a specific amount. Multiple partial refunds are allowed until the full amount is returned.

    ```
    POST /gl/v1/payments/{gid}/refund
    ```

    ```json theme={null}
    {
      "merchantUniqueId": "IFNN939494NJFJ",
      "merchantTxnId": "REFUND-23AEE8CB6B62EE2AF07-1",
      "refundType": "P",
      "paymentData": {
        "totalAmount": "25.00"
      }
    }
    ```
  </Tab>
</Tabs>

***

## About `merchantCallbackURL`

Every payment initiation payload contains a field called `merchantCallbackURL`. Once the transaction is processed at PayGlocal, the transaction response is sent to this URL using a **server-to-server POST request**. Merchants are required to create and expose a backend endpoint capable of receiving and handling this response. Based on the received transaction status, merchants can redirect customers to success or failure pages and update their internal order status accordingly.

<CardGroup>
  <Card title="Response Handling Guide" icon="arrow-right-from-bracket" href="/docs/merchant/payment-response-handling">
    Learn how to receive, decode, and act on the PayGlocal callback response.
  </Card>

  <Card title="Node.js Implementation" icon="node-js" href="/docs/api-reference/callback-handling">
    Complete working code for your `merchantCallbackURL` endpoint.
  </Card>

  <Card title="Payment Flow" icon="shield" href="/docs/merchant/payment-flow">
    How payloads are encrypted and signed before being sent to PayGlocal.
  </Card>

  <Card title="API Reference" icon="book" href="/docs/api-reference/payments-v2/paycollect/overview">
    Full field-level documentation for every endpoint.
  </Card>
</CardGroup>


# Overview
Source: https://payglocal.in/docs/api-reference/payment/overview

Overview of PayGlocal's Payment APIs — how authentication works, the GID lifecycle, and quick links to all payment endpoints.

## What Are the Payment APIs?

The **Payment APIs** handle the full transaction lifecycle: initiating payments, tracking status, issuing refunds, and managing recurring Standing Instructions. They are separate from the Merchant Onboarding API and use a different authentication mechanism.

<Note>
  The interactive API explorer on each endpoint page lets you test requests directly. Set your `x-gl-merchantid` and key signing headers in the authentication panel to make live Sandbox calls.
</Note>

***

## Authentication: RSA-signed JWS

<Warning>
  **The Payment APIs use RSA-signed JWS (and optionally JWE payload encryption) — not the HmacSHA256 used by the Onboarding API.** These are two different auth systems.
</Warning>

| API Area                | Auth method                             | Primary headers                                                             |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| Merchant Onboarding API | HmacSHA256                              | `x-gl-auth`, `x-gl-digest`                                                  |
| Payment APIs            | RSA-signed JWS in `x-gl-token-external` | `x-gl-token-external` (see [Key Management](/docs/key-management/overview)) |

You use your **PVT-KEY** to sign requests; **PUBCERT** verifies responses and may encrypt the body when your integration requires JWE. See [Key Management](/docs/key-management/overview) and [Constructing API Requests](/docs/key-management/request-construction) for setup.

***

## The GID — Central Transaction Identifier

Every Payment API call creates or consumes a **GID** (PayGlocal ID):

* Always starts with `gl-`
* Returned in every GPI response
* Used as the path parameter for Get Status, Refund, Capture, and Reversal
* Your `merchantUniqueId` can be used interchangeably with the GID in most endpoints

```
GPI (POST /initiate)
  └── Returns gid: "gl-13bbd3c4-..."
        │
        ├── GET /payments/{gid}/status     ← Get Status
        ├── POST /payments/{gid}/refund    ← Refund
        ├── POST /payments/{gid}/capture   ← Standalone Capture
        └── POST /payments/{gid}/auth-reversal  ← Reversal
```

***

## UPI (India)

Hosted **PayCollect** supports **UPI** and **UPI Intent** for INR. Product overview, screenshots, and a funds-flow diagram live on **[UPI](/docs/api-reference/payment/upi)**. Request and response shapes (minimal vs enriched body, initiation vs `statusData` after success, headers, callbacks) are documented on **[UPI Intent](/docs/api-reference/payment/upi-intent)**.

<CardGroup>
  <Card title="UPI" icon="wallet" href="/docs/api-reference/payment/upi">
    Checkout experience and how money moves from customer to settlement.
  </Card>

  <Card title="UPI Intent" icon="bolt" href="/docs/api-reference/payment/upi-intent">
    PayCollect payloads, two response phases, headers, and post-success `statusData`.
  </Card>
</CardGroup>

***

## Endpoint Reference

### Payment Initiation

| Endpoint                                                              | Method | When to Use                                      |
| --------------------------------------------------------------------- | ------ | ------------------------------------------------ |
| [GPI (Checkout Flow)](/docs/api-reference/payments-v2/paycollect/gpi) | POST   | Non-PCI merchants — PayGlocal collects card data |

PCI-certified PayDirect initiate is documented under **[Seamless Flow (PayDirect) → GPI](/docs/api-reference/payments-v2/paydirect/gpi)** in the sidebar.

### Transaction Management

| Endpoint                                                                                | Method | When to Use                                              |
| --------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------- |
| [Get Transaction Status](/docs/api-reference/payments-v2/common/get-transaction-status) | GET    | After GPI, after callback fails, anytime you need status |
| [Refund](/docs/api-reference/payment/refund)                                            | POST   | For captured payments requiring full or partial refund   |

### Auth & Capture (Separate Flow)

| Endpoint                                                                  | Method | When to Use                                                                 |
| ------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| [Standalone Capture](/docs/api-reference/payment/standalone-capture)      | POST   | Capture a previously authorized payment (initiated with `captureTxn=false`) |
| [Authorization Reversal](/docs/api-reference/payment/standalone-reversal) | POST   | Void an authorization before capture                                        |

### Standing Instructions

| Endpoint                                                                                        | Method | When to Use                                 |
| ----------------------------------------------------------------------------------------------- | ------ | ------------------------------------------- |
| [Subsequent Payment (SI Sale)](/docs/api-reference/standing-instructions/si-subsequent-payment) | POST   | Charge a customer using an existing mandate |
| [Cancel Mandate](/docs/api-reference/standing-instructions/si-cancellation)                     | PUT    | Revoke a mandate to stop future debits      |
| [Get Mandate Status](/docs/api-reference/standing-instructions/si-status)                       | POST   | Check mandate status and payment history    |

***

## Two Processing Models

Your MID can be configured for one of two models:

| Model                        | What happens during GPI redirect     | Your action                        |
| ---------------------------- | ------------------------------------ | ---------------------------------- |
| **Auth + Capture** (default) | Full payment processed automatically | Check status after callback        |
| **Auth Only**                | 3DS authentication only              | Send separate Auth + Capture calls |

Contact PayGlocal merchant support to configure your preferred model.

<CardGroup>
  <Card title="Which integration is right for you?" icon="map" href="/docs/guides/integration-chooser">
    PayCollect vs PayDirect vs Standalone vs Standing Instructions.
  </Card>

  <Card title="Payment Flow Overview" icon="diagram-project" href="/docs/integration/payment-flow">
    End-to-end sequence diagram for the GPI payment flow.
  </Card>
</CardGroup>


# Refund
Source: https://payglocal.in/docs/api-reference/payment/refund

POST /gl/v1/payments/{gid}/refund
Initiate a full or partial refund for a successfully captured transaction.

## When to Use

Refund all or part of a captured transaction. If the transaction is still in `AUTHORIZED` state (not yet captured), use [Auth Reversal](/docs/api-reference/payment/standalone-reversal) instead.

## Full vs Partial

* `refundType=F` — full refund. Omit `paymentData.totalAmount`.
* `refundType=P` — partial refund. `paymentData.totalAmount` is required and must be ≤ the captured amount.

Multiple partial refunds are allowed as long as the cumulative refunded amount does not exceed the original capture.


# Standalone Capture
Source: https://payglocal.in/docs/api-reference/payment/standalone-capture

POST /gl/v1/payments/{gid}/capture
Capture an authorized payment to trigger settlement.

## When to Use

Capture an `AUTHORIZED` transaction (i.e., one initiated with `captureTxn=false`). Until captured, the authorization holds funds on the customer's card but does not settle them to you.

## Full vs Partial

* `captureType=F` — full capture of the authorized amount. Omit `paymentData.totalAmount`.
* `captureType=P` — partial capture. `paymentData.totalAmount` is required and must be ≤ the authorized amount.

Only one capture is allowed per authorization. The remaining authorized amount is released after the first capture.


# Auth Reversal
Source: https://payglocal.in/docs/api-reference/payment/standalone-reversal

POST /gl/v1/payments/{gid}/auth-reversal
Reverse (void) an authorized payment before it is captured.

## When to Use

Void an `AUTHORIZED` transaction that has not yet been captured. This releases the hold on the customer's card.

<Note>
  Only **full reversals** are supported. If the payment has already been captured, use the [Refund](/docs/api-reference/payment/refund) service instead.
</Note>


# UPI
Source: https://payglocal.in/docs/api-reference/payment/upi

How UPI works on PayGlocal hosted PayCollect checkout in India — customer experience, screenshots, and funds flow.

## When to Use This Guide

Read this page if you accept **INR** payments in India and route customers through **PayCollect** (hosted checkout). It explains the **UPI** rail at a product level. For request payloads, nested responses, and headers specific to **UPI Intent**, use [UPI Intent](/docs/api-reference/payment/upi-intent).

***

## What Is UPI Here?

Think of **UPI** as “pay straight from a bank account using a phone app,” managed by India’s **NPCI** network. Your shopper does **not** type card numbers on your site. Instead, they land on a **PayGlocal-hosted** checkout: they pick **UPI**, scan a **one-time QR** (or approve in an app), enter their UPI PIN in **their own** bank app, and the debit happens on banking rails you never touch.

***

## How it gets paid

The payment is completed on PayGlocal’s hosted checkout. Your server starts the flow, PayGlocal shows the UPI experience, the customer approves the request in their bank app, and the UPI/NPCI network moves the money.

* Your backend opens a PayCollect session for UPI and receives a hosted `redirectUrl`.
* The shopper chooses UPI on the PayGlocal page and generates a QR or follows the in-app approval path.
* They complete the payment in their bank app using UPI PIN; your merchant site never sees the PIN or bank credentials.
* NPCI/bank settlement moves the funds, and PayGlocal updates the hosted checkout with success or failure.
* PayGlocal then notifies your server via `merchantCallbackURL`, and you can also verify the outcome by polling Get Status.
* Actual settlement into your account happens later through your normal bank payout process.

<Note>
  This is the same product-level path as PayCollect: PayGlocal mediates the checkout; UPI apps move the money; your backend receives a trusted result.
</Note>

***

## What your customer sees (step by step)

Each step below matches what you see in the **UAT screenshots** (blue header, white body). In production the layout stays the same; only copy and branding may differ.

<Note>
  Screenshots are from **UAT**. The **Txn ID** in the header is your `merchantTxnId` so support can match a screenshot to a server log line.
</Note>

The infographic below is one **end-to-end view** of the same journey: your server starts the payment, the customer pays on PayGlocal’s hosted page with their usual UPI habit, the bank and NPCI move the money message, PayGlocal tells your backend, then settlement and your “order complete” moment. The **numbered steps under it** walk through **real checkout screenshots** for the parts the shopper actually sees on screen.

<div>
  <img alt="How a UPI payment works with PayGlocal: a simple 7-step flow from your server through hosted checkout, UPI and the customer’s bank, back to callbacks and settlement" />
</div>

### Step 1 — Pick “UPI” on the PayGlocal checkout

The shopper leaves your cart and opens PayGlocal’s page. They see the amount (for example **₹10.00 INR**) and the transaction id in the header—**that id is the reference you sent as** `merchantTxnId`. They tap **UPI** so the page knows they want a bank-app payment instead of only cards.

<img alt="Hosted checkout with UPI selected; amount and transaction id in the blue header" />

***

### Step 2 — Tap “Generate QR Code” (or follow the on-screen UPI path)

On the same screen, PayGlocal asks them to **create the QR**. After they tap **Generate QR Code**, a **fresh QR** appears. A **countdown timer** may show how long that QR stays valid—if it expires, they generate a new one. (Some flows may deep-link into an app instead of QR; the idea is the same: PayGlocal prepares the collect request, the bank app finishes it.)

<img alt="Same screen with Generate QR Code and Pay button before scanning" />

***

### Step 3 — Open PhonePe, Google Pay, Paytm, or any UPI app and pay

They scan the QR **or** complete the in-app approval flow. The money request shows the right amount; they confirm with their **UPI PIN inside their bank’s app**. Your website never sees that PIN.

<img alt="QR code displayed with timer and text to use any UPI app to complete payment" />

***

### Step 4 — Wait on the PayGlocal page while status catches up

They should **stay on this tab**. The page shows a short note that **payment status will update here**—that is PayGlocal listening for the bank’s answer. In **Sandbox / UAT** you may also see big **Success** and **Failure** buttons: those only exist so developers can **pretend** a bank result and test your `merchantCallbackURL` without a real rupee moving.

<img alt="Same QR screen with status info banner and optional UAT Success and Failure test buttons" />

***

### Step 5 — “Paid” screen, then back to your shop

When the payment succeeds, they see a **green check** and the amount in words they understand (“your transaction of … was successful”). After a short countdown, PayGlocal sends them to the **`merchantCallbackURL`** you configured—your site shows the **order confirmation** or “try again” page.

<img alt="Success screen with green checkmark, amount, redirect countdown, and return to merchant" />

***

## How money actually moves (simple picture)

**Plain fact:** the shopping cart in the browser does **not** hold cash. Only **banks** move rupees. PayGlocal’s job is to **stand in the middle**: start a safe session, show the checkout you saw above, talk to **UPI / NPCI**, then **tell your servers** what happened using `gid`, `merchantTxnId`, callbacks, and status APIs.

### Diagram — all seven beats on one line

The image is a **timeline**: read **1 → 6** across the top for what happens in a few seconds around the payment; **step 7** is what accountants call **settlement** (often later in the day or next batch—not the same blink as “success” on screen).

<img alt="Timeline diagram: seven steps from your server through PayGlocal, customer, UPI, banks, callbacks, then settlement" />

### Same story in everyday words

| Step  | Who acts                    | What a non‑engineer should picture                                                                                                                                       |
| ----- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **1** | **Your server**             | You press “start payment” in your backend: amount, order id, and where to send the shopper when it is over (`merchantCallbackURL`).                                      |
| **2** | **Customer’s browser**      | They open PayGlocal’s blue-and-white page—not your card form—so card rules and UPI rules are handled in one certified place.                                             |
| **3** | **Customer + phone**        | They pay like they would at a kirana store QR: same apps, same PIN, same bank SMS habit.                                                                                 |
| **4** | **Customer’s bank**         | The bank checks “enough balance? fraud rules?” and, if OK, **pulls rupees** out for this UPI request.                                                                    |
| **5** | **UPI / NPCI → PayGlocal**  | A digital “receipt” travels back through the network so PayGlocal knows **paid or failed**.                                                                              |
| **6** | **PayGlocal → your server** | PayGlocal **redirects or posts** to your callback and you can also **poll Get Status**—both carry trusted tokens you verify before showing “Order confirmed.”            |
| **7** | **Banks + you + customer**  | **Settlement** (money landing in your company bank) follows your **contract timing**; separately you **email a receipt** or ship the product—happy path for the shopper. |

**Why step 7 feels slower:** authorization (steps 1–6) can be almost instant for the user, but **moving cleared funds between banks for your payout** is often a **batch** process—like clearing cheques overnight, not like handing cash across a counter.

***

## Next Step

<Card title="UPI Intent — payloads & responses" icon="file-lines" href="/docs/api-reference/payment/upi-intent">
  Minimal and enriched PayCollect requests, initiation vs post-success status payloads, headers, and callback notes.
</Card>


# Get Transaction Status
Source: https://payglocal.in/docs/api-reference/payments-v2/common/get-transaction-status

GET /gl/v1/payments/{id}/status
Poll payment status after GPI — recommended after every transaction (PayDirect and PayCollect).

## When to Use

Call status **after every payment initiation**, once the customer completes (or abandons) the flow. PayGlocal also sends lifecycle updates to your `merchantCallbackURL`, but **status polling is the recommended way to confirm the final outcome** and reconcile orders if a callback is delayed, retried, or missed.

Use this endpoint for all GPI transactions — **PayDirect and PayCollect**, cards, UPI, net banking, Apple Pay, and global alternative payments.

***

## API

|                |                                                            |
| -------------- | ---------------------------------------------------------- |
| **Method**     | `GET`                                                      |
| **Path**       | `/gl/v1/payments/{id}/status`                              |
| **Production** | `https://api.payglocal.in/gl/v1/payments/{gid}/status`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/{gid}/status` |

Pass PayGlocal `gid` or your `merchantTxnId` as `{id}`. Alternatively, call the pre-signed **`data.statusUrl`** from the [GPI initiate](/docs/api-reference/payments-v2/paydirect/gpi) response.

***

## Headers

| Header                | Mandatory | Description                                                              |
| --------------------- | --------- | ------------------------------------------------------------------------ |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                         |
| `x-gl-kid`            | Yes       | Key ID used to sign the JWS                                              |

***

## Notes

* Top-level `status` is the transaction state (e.g. `SENT_FOR_CAPTURE`, `AUTHORIZED`, `INPROGRESS`). The nested `data.status` often mirrors it for successful payments.
* The `data` object **varies by `payment-method`** — use the **Responses** examples below (card, UPI, net banking, global alt pay, authorized card).
* For auth-only flows (`captureTxn: false`), expect `AUTHORIZED` until you call [capture](/docs/api-reference/payment/standalone-capture).

***

## Error Scenarios

| Scenario                                   | HTTP code |
| ------------------------------------------ | --------- |
| Unknown or invalid `gid` / `merchantTxnId` | `404`     |
| Missing or invalid JWS                     | `401`     |


# Authorize Payment (Auth Only)
Source: https://payglocal.in/docs/api-reference/payments-v2/paycollect/auth-capture-authorise

openapi-v2-paycollect-auth.yaml POST /gl/v1/payments/initiate/paycollect
Authorize a hosted PayCollect payment without capturing funds — captureTxn false, then capture or reverse later. No card data in your request.

<span />

## Authorize payment (auth only)

Authorize a PayCollect payment **without capturing funds immediately**. This flow places a **hold** on the customer's funds so you can **capture** or **reverse** the authorization later.

The customer completes authentication on PayGlocal's **hosted checkout** (`redirectUrl`). You do **not** send card or token data in the API request.

The same PayCollect initiate API as [GPI](/docs/api-reference/payments-v2/paycollect/gpi) is used for authorization. Set **`captureTxn`** to **`false`** in **Request body**.

***

## When to Use

Use this flow when you need to **verify and reserve funds** before completing the transaction, such as:

* Hotel and hospitality bookings
* Vehicle rentals
* Delayed order fulfillment
* Inventory confirmation workflows
* Any scenario requiring payment approval before final settlement

After authorization, you can:

* **Capture** the authorized amount to complete the payment — [standalone capture](/docs/api-reference/payment/standalone-capture)
* **Reverse** the authorization to release the held funds — [auth reversal](/docs/api-reference/payment/standalone-reversal)

***

## Supported payment methods

Authorize (auth only) on hosted checkout supports **cards** and **international Apple Pay** only. **UPI and net banking are not supported** for auth transactions (they are available on [GPI](/docs/api-reference/payments-v2/paycollect/gpi) sale flows).

| Method    | Domestic | International |
| --------- | :------: | :-----------: |
| Cards     |     ✓    |       ✓       |
| Apple Pay |     —    |       ✓       |

***

## Notes

* Do **not** send **`cardData`** or **`tokenData`** — payment details are collected on the hosted page.
* Set **`captureTxn`** to **`false`** in **Request body**, with `paymentData` (amount, currency, `billingData`) as for [GPI](/docs/api-reference/payments-v2/paycollect/gpi).

***

## API

|                |                                                                   |
| -------------- | ----------------------------------------------------------------- |
| **Method**     | `POST`                                                            |
| **Path**       | `/gl/v1/payments/initiate/paycollect`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate/paycollect`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Sign the JSON from **Request body** below as the JWS in `x-gl-token-external`, then POST to the URL above.

<Warning>
  Only **one** successful capture is allowed per authorisation.
</Warning>

<div>
  ## Next steps

  | Action       | API                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
  | Capture      | [POST /payments//capture](/docs/api-reference/payment/standalone-capture)                                                   |
  | Reverse hold | [POST /payments//auth-reversal](/docs/api-reference/payment/standalone-reversal)                                            |
  | Status       | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) — expect `AUTHORIZED` until capture |
  | Refund       | After `SENT_FOR_CAPTURE` — [Refund](/docs/api-reference/payment/refund)                                                     |
</div>


# GPI
Source: https://payglocal.in/docs/api-reference/payments-v2/paycollect/gpi

openapi-v2-paycollect-gpi.yaml POST /gl/v1/payments/initiate/paycollect
PayGlocal Payment Initiate (GPI) — one-step hosted sale via POST /gl/v1/payments/initiate/paycollect. No card data in your request.

<span />

## What is GPI?

**GPI (PayGlocal Payment Initiate)** starts a **PayCollect** payment. You initiate from your server with transaction and billing data; PayGlocal returns a `gid` and a `redirectUrl`. Send the customer to that URL to pay on the hosted checkout, then read the outcome from your callback or the status API.

***

## Supported payment methods

The customer chooses on the hosted page:

| Method                                        | Domestic | International |
| --------------------------------------------- | :------: | :-----------: |
| Cards                                         |     ✓    |       ✓       |
| [UPI Intent](/docs/api-reference/payment/upi) |     ✓    |       —       |
| Net banking                                   |     ✓    |       —       |
| Apple Pay                                     |     —    |       ✓       |
| Global alternative payments                   |     —    |       ✓       |

See [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) for response shapes per method.

<Info>
  For **global alternative payments**, include `riskData.shippingData.addressCountry` and `emailId` in the request body.
</Info>

***

## API

|                |                                                                   |
| -------------- | ----------------------------------------------------------------- |
| **Method**     | `POST`                                                            |
| **Path**       | `/gl/v1/payments/initiate/paycollect`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate/paycollect`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Sign the JSON from **Request body** below as the JWS in `x-gl-token-external`, then POST to the URL above.

<div>
  ## Next steps

  | Step                   | API                                                                                     |
  | ---------------------- | --------------------------------------------------------------------------------------- |
  | Confirm outcome        | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) |
  | Refund (after capture) | [Refund](/docs/api-reference/payment/refund)                                            |
</div>


# Overview
Source: https://payglocal.in/docs/api-reference/payments-v2/paycollect/overview

Hosted checkout integration — PayGlocal collects payment details; no PCI DSS burden on your application.

## Checkout Flow (PayCollect)

**PayCollect** is PayGlocal's hosted integration mode. You initiate the payment from your server with amount, currency, and callback URL. The customer is redirected to PayGlocal's checkout, where they enter card details or choose a supported method (UPI, net banking, Apple Pay, global alternative payments, and more).

**No card data or tokens** are sent in your initiate request. PayGlocal collects payment details, runs 3DS where required, and completes the transaction.

<Note>
  **PCI DSS certified and want your own checkout UI?** Use [Seamless Flow (PayDirect)](/docs/api-reference/payments-v2/paydirect/overview) instead — you collect card data on your page and send it server-to-server.
</Note>

### Key characteristics of PayCollect

* Can be used by merchants **without** PCI DSS certification for card collection.
* The customer completes payment on a **PayGlocal-hosted** page (`redirectUrl`).
* **Multiple payment methods** (cards, UPI, net banking, Apple Pay, global alt pays) without separate initiate APIs — the customer selects the method at checkout.
* All initiation calls use **server-to-server** APIs; the browser only follows the redirect to PayGlocal.

***

## Authentication & keys

PayCollect uses the same payment authentication as PayDirect: download an **RSA key** from the GCC Dashboard and send a **JWS token** in `x-gl-token-external` on every request.

| Topic      | Details                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| Header     | `x-gl-token-external`                                                                                                    |
| Token type | RSA-signed JWS                                                                                                           |
| Setup      | [Key Management](/docs/key-management/overview) · [Constructing API Requests](/docs/key-management/request-construction) |

***

## Base URLs

| Environment | Base URL                       |
| ----------- | ------------------------------ |
| Production  | `https://api.payglocal.in`     |
| Sandbox     | `https://api.uat.payglocal.in` |

***

## Supported payment methods

The customer selects the method on the hosted page. You do **not** send a payment-method field in the initiate request.

| Method                      | Domestic | International | Notes                                                                                                  |
| --------------------------- | :------: | :-----------: | ------------------------------------------------------------------------------------------------------ |
| Cards                       |     ✓    |       ✓       | No `cardData` / `tokenData` in your request                                                            |
| UPI / UPI Intent            |     ✓    |       —       | INR; see [UPI](/docs/api-reference/payment/upi) · [UPI Intent](/docs/api-reference/payment/upi-intent) |
| Net banking                 |     ✓    |       —       | Selected on hosted page                                                                                |
| Apple Pay                   |     —    |       ✓       | International cards only                                                                               |
| Global alternative payments |     —    |       ✓       | Requires `riskData.shippingData.addressCountry` and `emailId`                                          |

PayCollect does **not** apply to merchants who need to send raw card data in the API — use [Seamless Flow (PayDirect)](/docs/api-reference/payments-v2/paydirect/overview) for that.

***

## Transaction flows

**GPI**, **authorize payment**, **SI on demand**, and **SI auto debit** all use the same initiation endpoint: `POST /gl/v1/payments/initiate/paycollect`. Only the request body changes.

<CardGroup>
  <Card title="GPI" icon="bolt" href="/docs/api-reference/payments-v2/paycollect/gpi">
    PayGlocal Payment Initiate — hosted single-step sale.
  </Card>

  <Card title="Authorize payment (auth only)" icon="shield-check" href="/docs/api-reference/payments-v2/paycollect/auth-capture-authorise">
    Hold funds on hosted checkout; capture or reverse later.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="SI — on demand" icon="rotate" href="/docs/api-reference/payments-v2/paycollect/si-on-demand">
    Hosted mandate; subsequent debits via SI sale.
  </Card>

  <Card title="SI — auto debit" icon="calendar" href="/docs/api-reference/payments-v2/paycollect/si-auto-debit">
    Hosted mandate; scheduled FIXED debits.
  </Card>
</CardGroup>

### GPI (PayGlocal Payment Initiate — sale)

Single-step payment on PayGlocal's hosted page. Funds are **authorised and captured in one flow** after the customer pays. Use this when you do **not** send card data in your API request.

→ [GPI](/docs/api-reference/payments-v2/paycollect/gpi)

### Authorize payment (auth only)

Two-step payment on hosted checkout. Set **`captureTxn: false`** to hold funds without capturing. Capture when you are ready to settle, or reverse to release the hold. **Cards and international Apple Pay only** — UPI and net banking are not supported for auth.

→ [Authorize Payment (Auth Only)](/docs/api-reference/payments-v2/paycollect/auth-capture-authorise)

### Standing instructions (international cards)

| Model                                                                  | Subsequent debits                                                                                   | Amount                                |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [On demand](/docs/api-reference/payments-v2/paycollect/si-on-demand)   | You call [SI sale](/docs/api-reference/standing-instructions/si-subsequent-payment) when you choose | `FIXED` or `VARIABLE`; no `startDate` |
| [Auto debit](/docs/api-reference/payments-v2/paycollect/si-auto-debit) | PayGlocal scheduler (`WEEKLY`, `MONTHLY`, …) — no SI sale                                           | `FIXED` only; `startDate` required    |

Store **`mandateId`** from the initiate response — it is not returned on later transactions.

| After initiate      | API                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Transaction status  | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status)                                      |
| SI sale (on-demand) | [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment)                                     |
| Mandate status      | [Check mandate status](/docs/api-reference/standing-instructions/si-status)                                                  |
| Cancel mandate      | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation)                                     |
| Capture / reversal  | [Capture](/docs/api-reference/payment/standalone-capture) · [Auth reversal](/docs/api-reference/payment/standalone-reversal) |
| Refund              | [Refund](/docs/api-reference/payment/refund) (after `SENT_FOR_CAPTURE`)                                                      |


# Standing instruction — auto debit
Source: https://payglocal.in/docs/api-reference/payments-v2/paycollect/si-auto-debit

openapi-v2-paycollect-si-auto-debit.yaml POST /gl/v1/payments/initiate/paycollect
AUTO DEBIT standing instructions — scheduled FIXED debits after PayCollect mandate registration on hosted checkout.

<span />

## AUTO DEBIT standing instructions

**AUTO DEBIT** standing instructions automatically process subsequent debits based on the configured schedule after successful mandate registration.

Registration uses the same PayCollect initiate endpoint as [GPI](/docs/api-reference/payments-v2/paycollect/gpi) with a `standingInstruction` block. The customer completes mandate setup on the **hosted checkout** page.

### Key points

* Register the mandate using the **Initiate API** with **`startDate`** and a scheduled **`frequency`** such as `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `HALFYEARLY`, or `YEARLY` (not `ONDEMAND`).
* After successful registration, subsequent debit transactions are **automatically initiated** according to the configured schedule.
* **No [SI sale API](/docs/api-reference/standing-instructions/si-subsequent-payment) calls** are required for subsequent debit transactions.
* The amount for subsequent debits must be **`FIXED`**.

<Warning>
  When **Auto Debit** is enabled for your MID, `ONDEMAND` frequency and `VARIABLE` type are not supported.
</Warning>

***

## Supported payment methods

| Method | Domestic | International |
| ------ | :------: | :-----------: |
| Cards  |     —    |       ✓       |

Standing instruction registration on hosted checkout supports **international cards** only. UPI, net banking, and domestic-only methods are not supported for SI.

## Notes

* Do **not** send **`cardData`** or **`tokenData`** — the customer registers the mandate on the PayGlocal hosted page.

***

## API

|                |                                                                   |
| -------------- | ----------------------------------------------------------------- |
| **Method**     | `POST`                                                            |
| **Path**       | `/gl/v1/payments/initiate/paycollect`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate/paycollect`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

Same as [GPI](/docs/api-reference/payments-v2/paycollect/gpi).

Set `standingInstruction.data` (`amount`, scheduled `frequency`, `type: FIXED`, `startDate`) in **Request body** below.

<div>
  ## Next actions

  PayGlocal debits on your configured schedule. **Do not** call [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment) for scheduled debits.

  | Action               | API                                                                                                                    |
  | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
  | Mandate status       | [Check mandate status](/docs/api-reference/standing-instructions/si-status)                                            |
  | Cancel mandate       | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation)                               |
  | Each scheduled debit | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) and your `merchantCallbackURL` |
</div>


# Standing instruction — on demand
Source: https://payglocal.in/docs/api-reference/payments-v2/paycollect/si-on-demand

openapi-v2-paycollect-si-on-demand.yaml POST /gl/v1/payments/initiate/paycollect
On-demand SI — register a mandate on PayCollect hosted initiate when PayGlocal has enabled on-demand SI on your MID.

<span />

## On-demand standing instructions

**On-demand SI** is a **PayGlocal MID configuration** — not a restriction that `standingInstruction.data.frequency` must be `ONDEMAND`. You can set any supported `frequency` in the request body.

Use this flow when on-demand SI is enabled for your account. Registration uses the same PayCollect initiate endpoint as [GPI](/docs/api-reference/payments-v2/paycollect/gpi) with a `standingInstruction` block. The customer completes mandate setup on the **hosted checkout** page.

### Key points

* Register the mandate using the **Initiate API** with `standingInstruction.data` (see **Request body**).
* **`frequency`** (`ONDEMAND`, `WEEKLY`, `MONTHLY`, etc.) is a mandate field only — PayGlocal does **not** auto-debit on that schedule for on-demand SI. You trigger **every** subsequent debit by calling the **[SI sale API](/docs/api-reference/standing-instructions/si-subsequent-payment)** (billing cadence is up to you).
* Subsequent debit amounts:
  * **`FIXED`** — same `amount` each time.
  * **`VARIABLE`** — up to `maxAmount` per debit.
* **`mandateId`** is returned in the Initiate API response (`data.mandateId`) and must be stored for future mandate operations. It is **not returned again** in later transactions.

***

## Supported payment methods

| Method | Domestic | International |
| ------ | :------: | :-----------: |
| Cards  |     —    |       ✓       |

Standing instruction registration on hosted checkout supports **international cards** only. UPI, net banking, and domestic-only methods are not supported for SI.

## Notes

* Do **not** send **`cardData`** or **`tokenData`** — the customer registers the mandate on the PayGlocal hosted page.

***

## API

|                |                                                                   |
| -------------- | ----------------------------------------------------------------- |
| **Method**     | `POST`                                                            |
| **Path**       | `/gl/v1/payments/initiate/paycollect`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate/paycollect`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Sign the JSON from **Request body** below as the JWS in `x-gl-token-external`, then POST to the URL above.

<div>
  ## Next actions

  Store **`data.mandateId`** from the initiate response — it is not returned on later calls.

  | Action                         | API                                                                                      |
  | ------------------------------ | ---------------------------------------------------------------------------------------- |
  | Subsequent debit               | [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment) |
  | Mandate status                 | [Check mandate status](/docs/api-reference/standing-instructions/si-status)              |
  | Cancel mandate                 | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation) |
  | Registration / payment outcome | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status)  |
</div>


# Authorize Payment (Auth Only)
Source: https://payglocal.in/docs/api-reference/payments-v2/paydirect/auth-capture-authorise

openapi-v2-paydirect-auth.yaml POST /gl/v1/payments/initiate
Authorize a PayDirect payment without capturing funds — hold funds with captureTxn false, then capture or reverse later.

<span />

## Authorize payment (auth only)

Authorize a PayDirect payment **without capturing funds immediately**. This flow places a **hold** on the customer's funds so you can **capture** or **reverse** the authorization later.

The same PayDirect initiate API as [GPI](/docs/api-reference/payments-v2/paydirect/gpi) is used for authorization. Set **`captureTxn`** to **`false`** in **Request body**.

***

## When to Use

Use this flow when you need to **verify and reserve funds** before completing the transaction, such as:

* Hotel and hospitality bookings
* Vehicle rentals
* Delayed order fulfillment
* Inventory confirmation workflows
* Any scenario requiring payment approval before final settlement

After authorization, you can:

* **Capture** the authorized amount to complete the payment — [standalone capture](/docs/api-reference/payment/standalone-capture)
* **Reverse** the authorization to release the held funds — [auth reversal](/docs/api-reference/payment/standalone-reversal)

***

## Supported payment methods

Authorize (auth only) supports **cards** and **international Apple Pay** only. UPI and net banking are not available on PayDirect.

| Method    | Domestic | International |
| --------- | :------: | :-----------: |
| Cards     |     ✓    |       ✓       |
| Apple Pay |     —    |       ✓       |

***

## API

|                |                                                        |
| -------------- | ------------------------------------------------------ |
| **Method**     | `POST`                                                 |
| **Path**       | `/gl/v1/payments/initiate`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Set **`captureTxn`** to **`false`** in **Request body** below, with **`cardData` or `tokenData`** as for GPI.

<Warning>
  Only **one** successful capture is allowed per authorisation.
</Warning>

<div>
  ## Next steps

  | Action       | API                                                                                                                         |
  | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
  | Capture      | [POST /payments//capture](/docs/api-reference/payment/standalone-capture)                                                   |
  | Reverse hold | [POST /payments//auth-reversal](/docs/api-reference/payment/standalone-reversal)                                            |
  | Status       | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) — expect `AUTHORIZED` until capture |
  | Refund       | After `SENT_FOR_CAPTURE` — [Refund](/docs/api-reference/payment/refund)                                                     |
</div>


# GPI
Source: https://payglocal.in/docs/api-reference/payments-v2/paydirect/gpi

openapi-v2-paydirect-gpi.yaml POST /gl/v1/payments/initiate
PayGlocal Payment Initiate (GPI) — one-step PayDirect sale via POST /gl/v1/payments/initiate.

<span />

## What is GPI?

**GPI (PayGlocal Payment Initiate)** is the API call that **starts a PayDirect payment**. You send transaction and card (or token) data in one request; PayGlocal returns a `gid` and a `redirectUrl`. Send the customer to that URL to complete 3DS, then read the outcome from your callback or the status API.

***

## Supported payment methods

| Method    | Domestic | International |
| --------- | :------: | :-----------: |
| Cards     |     ✓    |       ✓       |
| Apple Pay |     —    |       ✓       |

PayDirect GPI does not support UPI, net banking, or global alternative payments — use [GPI](/docs/api-reference/payments-v2/paycollect/gpi) for those.

## Notes

* In **Request body** → `paymentData`, send **`cardData` or `tokenData`** (exactly one is mandatory).

***

## API

|                |                                                        |
| -------------- | ------------------------------------------------------ |
| **Method**     | `POST`                                                 |
| **Path**       | `/gl/v1/payments/initiate`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Sign the JSON from **Request body** below as the JWS in `x-gl-token-external`, then POST to the URL above.

<div>
  ## Next steps

  | Step                   | API                                                                                     |
  | ---------------------- | --------------------------------------------------------------------------------------- |
  | Confirm outcome        | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) |
  | Refund (after capture) | [Refund](/docs/api-reference/payment/refund)                                            |
</div>


# Overview
Source: https://payglocal.in/docs/api-reference/payments-v2/paydirect/overview

PCI DSS–compliant direct card integration — your checkout collects card data; PayGlocal processes the payment.

## Seamless Flow (PayDirect)

**PayDirect** is PayGlocal's server-to-server integration mode for merchants who are PCI DSS certified. In this flow, card details are collected by the merchant's application. The merchant then securely sends the card information to PayGlocal, where the transaction is completed.

Card data (or network tokens) travel in the API request body. PayGlocal handles 3DS authentication, intelligent routing, and settlement on the back end.

<Note>
  **Not PCI DSS certified?** Use [Checkout Flow (PayCollect)](/docs/api-reference/payments-v2/paycollect/overview) instead — card details are collected on a PayGlocal-hosted page, and you do not need to handle card information in your application.
</Note>

### Key characteristics

* Can only be used by **PCI DSS certified** merchants.
* Used when the customer enters card details on the **merchant's own checkout page**.
* For any new payment methods introduced, merchants need to perform a **technical integration**.
* All API calls must be made over **server-to-server** communication channels.

***

## Authentication & keys

For PayDirect, download an **RSA key** from the GCC Dashboard. All PayDirect payment calls use this key to generate a **JWS token** passed in the `x-gl-token-external` header.

| Topic      | Details                                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ |
| Header     | `x-gl-token-external`                                                                                                    |
| Token type | RSA-signed JWS                                                                                                           |
| Setup      | [Key Management](/docs/key-management/overview) · [Constructing API Requests](/docs/key-management/request-construction) |

<Warning>
  Payment APIs use **RSA-signed JWS** — not the HmacSHA256 scheme used by the Merchant Onboarding API.
</Warning>

***

## Base URLs

| Environment | Base URL                       |
| ----------- | ------------------------------ |
| Production  | `https://api.payglocal.in`     |
| Sandbox     | `https://api.uat.payglocal.in` |

***

## Supported payment methods

| Method    | Domestic | International | Notes                                              |
| --------- | :------: | :-----------: | -------------------------------------------------- |
| Cards     |     ✓    |       ✓       | Send `cardData` or `tokenData` in the request body |
| Apple Pay |     —    |       ✓       | International cards only                           |

PayDirect does **not** support UPI, net banking, or global alternative payment methods. Those are available on [Checkout Flow (PayCollect)](/docs/api-reference/payments-v2/paycollect/overview).

***

## Transaction flows

**GPI**, **authorize payment**, **SI on demand**, and **SI auto debit** all use the same initiation endpoint: `POST /gl/v1/payments/initiate`. Only the request body changes.

<CardGroup>
  <Card title="GPI" icon="bolt" href="/docs/api-reference/payments-v2/paydirect/gpi">
    PayGlocal Payment Initiate — single-step sale.
  </Card>

  <Card title="Authorize payment (auth only)" icon="shield-check" href="/docs/api-reference/payments-v2/paydirect/auth-capture-authorise">
    Hold funds first; capture or reverse later.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="SI — ONDEMAND" icon="rotate" href="/docs/api-reference/payments-v2/paydirect/si-on-demand">
    Subsequent debits via SI sale (FIXED or VARIABLE).
  </Card>

  <Card title="SI — AUTO DEBIT" icon="calendar" href="/docs/api-reference/payments-v2/paydirect/si-auto-debit">
    Scheduled FIXED debits; no SI sale API.
  </Card>
</CardGroup>

### GPI (PayGlocal Payment Initiate — sale)

Single-step payment. Funds are **authorised and captured in one call**. Use this for standard e-commerce checkouts where fulfilment is immediate.

→ [GPI](/docs/api-reference/payments-v2/paydirect/gpi) (complete request payload)

### Authorize payment (auth only)

Two-step payment. Set **`captureTxn: false`** to hold funds without capturing. Capture when you are ready to settle, or reverse to release the hold. **Cards and international Apple Pay only** — UPI and net banking are not supported for auth.

→ [Authorize Payment (Auth Only)](/docs/api-reference/payments-v2/paydirect/auth-capture-authorise)

### Standing instructions (international cards)

| Model                                                                 | Subsequent debits                                                                                                                      | Amount                                |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| [ONDEMAND](/docs/api-reference/payments-v2/paydirect/si-on-demand)    | You call [SI sale](/docs/api-reference/standing-instructions/si-subsequent-payment) when you choose (weekly/monthly/etc. is up to you) | `FIXED` or `VARIABLE`; no `startDate` |
| [AUTO DEBIT](/docs/api-reference/payments-v2/paydirect/si-auto-debit) | PayGlocal scheduler (`WEEKLY`, `MONTHLY`, …) — no SI sale                                                                              | `FIXED` only; `startDate` required    |

Store **`mandateId`** from the initiate response — it is not returned on later transactions.

| After initiate      | API                                                                                                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Transaction status  | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status)                                      |
| SI sale (on-demand) | [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment)                                     |
| Mandate status      | [Check mandate status](/docs/api-reference/standing-instructions/si-status)                                                  |
| Cancel mandate      | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation)                                     |
| Capture / reversal  | [Capture](/docs/api-reference/payment/standalone-capture) · [Auth reversal](/docs/api-reference/payment/standalone-reversal) |
| Refund              | [Refund](/docs/api-reference/payment/refund) (after `SENT_FOR_CAPTURE`)                                                      |


# Standing instruction — auto debit
Source: https://payglocal.in/docs/api-reference/payments-v2/paydirect/si-auto-debit

openapi-v2-paydirect-si-auto-debit.yaml POST /gl/v1/payments/initiate
AUTO DEBIT standing instructions — scheduled FIXED debits after PayDirect mandate registration.

<span />

## AUTO DEBIT standing instructions

**AUTO DEBIT** standing instructions automatically process subsequent debits based on the configured schedule after successful mandate registration.

Registration uses the same PayDirect initiate endpoint as [GPI](/docs/api-reference/payments-v2/paydirect/gpi) with a `standingInstruction` block.

### Key points

* Register the mandate using the **Initiate API** with **`startDate`** and a scheduled **`frequency`** such as `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `HALFYEARLY`, or `YEARLY` (not `ONDEMAND`).
* After successful registration, subsequent debit transactions are **automatically initiated** according to the configured schedule.
* **No [SI sale API](/docs/api-reference/standing-instructions/si-subsequent-payment) calls** are required for subsequent debit transactions.
* The amount for subsequent debits must be **`FIXED`**.

<Warning>
  When **Auto Debit** is enabled for your MID, `ONDEMAND` frequency and `VARIABLE` type are not supported.
</Warning>

***

## Supported payment methods

| Method | Domestic | International |
| ------ | :------: | :-----------: |
| Cards  |     —    |       ✓       |

Standing instructions support **international cards** only. In **Request body** → `paymentData`, send **`cardData` only** (`tokenData` is not supported).

***

## API

|                |                                                        |
| -------------- | ------------------------------------------------------ |
| **Method**     | `POST`                                                 |
| **Path**       | `/gl/v1/payments/initiate`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

Same as [GPI](/docs/api-reference/payments-v2/paydirect/gpi).

Set `standingInstruction.data` (`amount`, scheduled `frequency`, `type: FIXED`, `startDate`) in **Request body** below.

<div>
  ## Next actions

  PayGlocal debits on your configured schedule. **Do not** call [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment) for scheduled debits.

  | Action               | API                                                                                                                    |
  | -------------------- | ---------------------------------------------------------------------------------------------------------------------- |
  | Mandate status       | [Check mandate status](/docs/api-reference/standing-instructions/si-status)                                            |
  | Cancel mandate       | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation)                               |
  | Each scheduled debit | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status) and your `merchantCallbackURL` |
</div>


# Standing instruction — on demand
Source: https://payglocal.in/docs/api-reference/payments-v2/paydirect/si-on-demand

openapi-v2-paydirect-si-on-demand.yaml POST /gl/v1/payments/initiate
On-demand SI — register a mandate on PayDirect initiate when PayGlocal has enabled on-demand SI on your MID.

<span />

## On-demand standing instructions

**On-demand SI** is a **PayGlocal MID configuration** — not a restriction that `standingInstruction.data.frequency` must be `ONDEMAND`. You can set any supported `frequency` in the request body.

Use this flow when on-demand SI is enabled for your account. Registration uses the same PayDirect initiate endpoint as [GPI](/docs/api-reference/payments-v2/paydirect/gpi) with a `standingInstruction` block.

### Key points

* Register the mandate using the **Initiate API** with `standingInstruction.data` (see **Request body**).
* **`frequency`** (`ONDEMAND`, `WEEKLY`, `MONTHLY`, etc.) is a mandate field only — PayGlocal does **not** auto-debit on that schedule for on-demand SI. You trigger **every** subsequent debit by calling the **[SI sale API](/docs/api-reference/standing-instructions/si-subsequent-payment)** (billing cadence is up to you).
* Subsequent debit amounts:
  * **`FIXED`** — same `amount` each time.
  * **`VARIABLE`** — up to `maxAmount` per debit.
* **`mandateId`** is returned in the Initiate API response (`data.mandateId`) and must be stored for future mandate operations. It is **not returned again** in later transactions.

***

## Supported payment methods

| Method | Domestic | International |
| ------ | :------: | :-----------: |
| Cards  |     —    |       ✓       |

Standing instructions support **international cards** only. In **Request body** → `paymentData`, send **`cardData` only** (`tokenData` is not supported). UPI, net banking, and domestic-only methods are not supported.

***

## API

|                |                                                        |
| -------------- | ------------------------------------------------------ |
| **Method**     | `POST`                                                 |
| **Path**       | `/gl/v1/payments/initiate`                             |
| **Production** | `https://api.payglocal.in/gl/v1/payments/initiate`     |
| **Sandbox**    | `https://api.uat.payglocal.in/gl/v1/payments/initiate` |

<Info>
  GPI, on-demand SI, auto-debit, and authorize all call this path. Only the JSON request body differs.
</Info>

***

## Headers

| Header                | Mandatory | Description                                                                                  |
| --------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `Content-Type`        | Yes       | `application/json`                                                                           |
| `x-gl-token-external` | Yes       | RSA-signed **JWS** of the request body (see [Key Management](/docs/key-management/overview)) |
| `x-gl-merchantid`     | Yes       | Your PayGlocal merchant ID (MID)                                                             |
| `x-gl-kid`            | Yes       | Key ID of the private key used to sign the JWS                                               |

Sign the JSON from **Request body** below as the JWS in `x-gl-token-external`, then POST to the URL above.

<div>
  ## Next actions

  Store **`data.mandateId`** from the initiate response — it is not returned on later calls.

  | Action                         | API                                                                                      |
  | ------------------------------ | ---------------------------------------------------------------------------------------- |
  | Subsequent debit               | [SI subsequent payment](/docs/api-reference/standing-instructions/si-subsequent-payment) |
  | Mandate status                 | [Check mandate status](/docs/api-reference/standing-instructions/si-status)              |
  | Cancel mandate                 | [Cancel standing instruction](/docs/api-reference/standing-instructions/si-cancellation) |
  | Registration / payment outcome | [Get transaction status](/docs/api-reference/payments-v2/common/get-transaction-status)  |
</div>


# Cancel Standing Instruction
Source: https://payglocal.in/docs/api-reference/standing-instructions/si-cancellation

PUT /gl/v1/payments/si/status
Revoke an active mandate to prevent future recurring debits.

## When to Use

Revoke an active standing-instruction mandate. Future scheduled or on-demand debits will not be attempted. Once revoked, the mandate cannot be reactivated — register again via [PayDirect](/docs/api-reference/payments-v2/paydirect/si-on-demand) or [PayCollect](/docs/api-reference/payments-v2/paycollect/si-on-demand) initiate. See **Standing Instruction Sale** in the API Reference sidebar.

## Common Failure Responses

**Already inactive:**

```json theme={null}
{ "status": "REQUEST_ERROR", "message": "Mandate was inactive" }
```

**Not found:**

```json theme={null}
{ "status": "REQUEST_ERROR", "message": "Mandate id not found" }
```


# Check Mandate Status
Source: https://payglocal.in/docs/api-reference/standing-instructions/si-status

POST /gl/v1/payments/si/status
Retrieve the current status, payment count, and details of a standing instruction mandate.

## When to Use

Check the current lifecycle state of a standing-instruction mandate — e.g., whether it's still active, how many debits have been processed, and how many remain. Applies to **on-demand and auto debit** mandates (PayDirect and PayCollect). See **Standing Instruction Sale** in the API Reference sidebar.

## Mandate Status Values

| Status      | Description                                               |
| ----------- | --------------------------------------------------------- |
| `ACTIVE`    | Mandate is active and can be used for subsequent payments |
| `INACTIVE`  | Mandate was revoked via API or Control Center             |
| `EXHAUSTED` | All configured payments have been processed               |

## Example Data Payloads

**Active mandate:**

```json theme={null}
{
  "mandateData": {
    "mandateStatus": "ACTIVE",
    "mandateCreateDate": "20211204",
    "maskedMandateId": "md_94fxxxxxx3e15",
    "siId": "si_cd2f0a1c-4dec-44d5-b0f3-297aee590d32",
    "numberOfPaymentsProcessed": "4",
    "numberOfPaymentsRemaining": "2"
  }
}
```

**Exhausted mandate:**

```json theme={null}
{
  "mandateData": {
    "mandateStatus": "EXHAUSTED",
    "mandateExhaustionDate": "20211209",
    "numberOfPaymentsProcessed": "6",
    "numberOfPaymentsRemaining": "0"
  }
}
```


# SI Subsequent Payment
Source: https://payglocal.in/docs/api-reference/standing-instructions/si-subsequent-payment

POST /gl/v1/payments/si/sale
Initiate a subsequent recurring payment using an existing active mandate.

## When to Use

**ONDEMAND** mandates require this API for every subsequent debit. Register with `frequency: ONDEMAND` on initiate — you then call SI sale whenever you want to charge (including weekly or monthly billing in your product; PayGlocal does not schedule ONDEMAND mandates).

**AUTO DEBIT** uses `frequency` values such as `MONTHLY` or `WEEKLY` on registration so PayGlocal runs the schedule — **no SI sale API**.

Use the **`mandateId`** from the original initiate response (it is not returned on later transactions). Applies to PayDirect and PayCollect on-demand mandates. See **Standing Instruction Sale** in the API Reference sidebar.

## FIXED vs VARIABLE

* **`type=FIXED`** — the debit amount is fixed to the amount supplied at mandate creation. Do not include `paymentData.totalAmount`.
* **`type=VARIABLE`** — the debit amount is variable but must be ≤ the `maxAmount` set when the mandate was created. `paymentData.totalAmount` is required.

## Common Failure Responses

```json theme={null}
{ "status": "REQUEST_ERROR", "message": "Mandate is not found | Mandate is inactive | Mandate is exhausted" }
```

<Note>
  If **Auto Debit** is enabled at the MID level, PayGlocal initiates subsequent payments automatically — this API is not applicable.
</Note>


# Update Authorised Signatory
Source: https://payglocal.in/docs/api-reference/update-auth-signatory

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/auth-signatory
Submits the authorised signatory details. The phone and email are used for
VKYC, DigiLocker, and T&C acknowledgement. Cannot be updated after T&C is acknowledged.


## When to Use

Submits the authorised signatory details. The signatory's phone and email are used to conduct VKYC, DigiLocker verification, and T\&C acknowledgement — so accuracy is critical.

<Warning>
  Authorised signatory details cannot be updated after the merchant has acknowledged the Terms & Conditions.
</Warning>

## Error Scenarios

| Scenario                                       | HTTP Code |
| ---------------------------------------------- | --------- |
| Required fields validation error               | `400`     |
| PAN validation failed                          | `400`     |
| Update attempted after T\&C is acknowledged    | `400`     |
| `onboardingId` does not exist                  | `404`     |
| `onboardingId` does not belong to this partner | `403`     |


# Update Bank Details
Source: https://payglocal.in/docs/api-reference/update-bank-details

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/bank-details
Submits or updates the settlement bank account. PayGlocal performs a penny drop
verification to confirm the account is active. Cannot be updated after verification
step is complete.


## When to Use

Submits or updates the settlement bank account. PayGlocal performs a **penny drop verification** to confirm the account is active and the IFSC is valid.

<Warning>
  Bank details cannot be updated after the merchant's verification step is complete. If the penny drop fails, prompt the merchant to re-enter their bank details.
</Warning>

## Notes

* If penny drop verification fails in Production, `CANCELLED_CHEQUE` is added to `documentsToBeUploaded`. Upload a cancelled cheque via [Upload Documents](/docs/api-reference/upload-documents) with `merchantDocType: CANCELLED_CHEQUE`.
* In UAT, use account number `1234567890` and IFSC `SBIN0000000` for successful verification. Any other combination triggers a `CANCELLED_CHEQUE` pendency. See [Sandbox Testing → Partner Onboarding](/docs/guides/testing#partner-onboarding-bank-verification).

## Error Scenarios

| Scenario                                             | HTTP Code |
| ---------------------------------------------------- | --------- |
| Required fields missing or empty                     | `400`     |
| Penny drop verification fails                        | `400`     |
| Update attempted after verification step is complete | `400`     |
| `onboardingId` does not exist                        | `404`     |
| `onboardingId` does not belong to this partner       | `403`     |


# Update Business Details
Source: https://payglocal.in/docs/api-reference/update-business-details

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/business-details
Submits or updates business information for a merchant. Cannot be updated after
T&C is acknowledged by the merchant.


## When to Use

Submits or updates business information for a merchant onboarding record. Must be called after [Create Onboarding](/docs/api-reference/create-onboarding).

<Warning>
  Business details cannot be updated after the merchant has acknowledged the Terms & Conditions. Ensure all information is accurate before triggering [Get Verification Redirect](/docs/api-reference/get-verification-redirect).
</Warning>

## Notes

* `address.businessOperatingAddress` is required **only when** `address.isOperatingSameAsRegistered` is `false`. When addresses differ, `OPERATING_ADDRESS_PROOF` is added to `documentsToBeUploaded`.
* `natureOfBusiness` must be a subcategory code from [Get Business Categories](/docs/api-reference/get-business-categories). State codes follow the 2-letter format — see [State Codes](/docs/reference/state-codes).
* For Partnership Firm entities, set `noPartnershipRegistrationCheck: true` when the partnership is not registered. This exempts `PARTNERSHIP_REGISTRATION_CERTIFICATE` from required documents.

## Error Scenarios

| Scenario                                       | HTTP Code |
| ---------------------------------------------- | --------- |
| Required fields missing or empty               | `400`     |
| Invalid field format                           | `400`     |
| Update attempted after T\&C is acknowledged    | `400`     |
| `onboardingId` does not exist                  | `404`     |
| `onboardingId` does not belong to this partner | `403`     |


# Upload Documents
Source: https://payglocal.in/docs/api-reference/upload-documents

PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/docs
Uploads a single compliance document. Call once per document type.
Cannot be updated after verification step is complete.


## When to Use

Uploads a single compliance document for the merchant. Call this endpoint **once per document type** required.

<Warning>
  Documents cannot be uploaded or updated after the merchant's verification step is complete.
</Warning>

<Note>
  Check `documentsToBeUploaded` in the [Get Onboarding Status](/docs/api-reference/get-status) response to see which documents are pending. After each upload, poll GET /status to confirm the list has updated. See the full [Dynamic document pendencies](/docs/guides/merchant-requirements#dynamic-document-pendencies) matrix for trigger conditions and `merchantDocType` mappings.
</Note>

## Error Scenarios

| Scenario                                             | HTTP Code |
| ---------------------------------------------------- | --------- |
| Required fields validation error                     | `400`     |
| Update attempted after verification step is complete | `400`     |
| `onboardingId` does not exist                        | `404`     |
| `onboardingId` does not belong to this partner       | `403`     |


# Authentication
Source: https://payglocal.in/docs/authentication

Authentication for the Merchant Onboarding APIs. Every request is signed with HmacSHA256 and sent via x-gl-auth + x-gl-digest headers.

<Note>
  This page covers authentication for the **Partner Merchant Onboarding** APIs (`/gcc/v2/partner/merchant/onboard/*` and `/gcc/v2/partner/merchant/verification/*`).
  The **Payment APIs** (`/gl/v1/payments/*`) use a different scheme — an RSA-signed JWS token sent in
  the `x-gl-token-external` header. See [Key Management → Overview](/docs/key-management/overview).
</Note>

## Overview

The Merchant Onboarding APIs use a two-header authentication scheme:

| Header        | Description                                                         |
| ------------- | ------------------------------------------------------------------- |
| `x-gl-auth`   | Your static API Key, generated from the PayGlocal Partner Dashboard |
| `x-gl-digest` | A per-request HMAC-SHA256 signature, Base64-encoded                 |

Both headers are **required on every Partner Onboarding API request**, including [Get Verification Redirect](/docs/api-reference/get-verification-redirect). Requests missing either header will be rejected.

***

## Credentials

Partners generate API credentials from the PayGlocal Partner Dashboard:

* **API Key** — sent in the `x-gl-auth` header. A static, non-secret identifier. Safe to store in environment variables.
* **API Secret** — used as the HMAC signing key to generate `x-gl-digest`. Treat this like a password. Never expose it in client-side code, logs, or version control.

See [Quickstart](/docs/quickstart) for credential download instructions.

<Warning>
  If your API Secret is compromised, rotate it immediately from the dashboard. PayGlocal supports multiple simultaneous active keys to allow zero-downtime rotation.
</Warning>

***

## Digest Generation

### Algorithm

```
digest = Base64( HmacSHA256( signingInput, API_SECRET ) )
```

### Signing Input Rules

| HTTP Method | Signing Input                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `GET`       | The **request URI path** (including query string if present). Do not include the host or scheme. |
| `POST`      | The **exact raw request body** (JSON string)                                                     |
| `PUT`       | The **exact raw request body** (JSON string)                                                     |

<Warning>
  For POST and PUT requests, compute the digest over the **exact same byte sequence** you send as the body. Any difference in whitespace, field ordering, or encoding will produce a mismatched digest and a `401 Unauthorized`.
</Warning>

For GET requests, sign only the path. Example for [Get Business Categories](/docs/api-reference/get-business-categories):

```
/gcc/v2/partner/merchant/onboard/business-category
```

***

## Code Examples — POST / PUT Requests

<CodeGroup>
  ```bash curl theme={null}
  #!/bin/bash
  API_KEY="your_api_key"
  API_SECRET="your_api_secret"

  BODY='{"externalOnboardingId":"partner-001","panNumber":"ABCDE1234F"}'
  DIGEST=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

  curl -X POST https://api.onboard.uat.payglocal.in/gcc/v2/partner/merchant/onboard \
    -H "Content-Type: application/json" \
    -H "x-gl-auth: $API_KEY" \
    -H "x-gl-digest: $DIGEST" \
    -d "$BODY"
  ```

  ```python Python theme={null}
  import hmac, hashlib, base64, json, requests

  API_KEY = "your_api_key"
  API_SECRET = "your_api_secret"
  BASE_URL = "https://api.onboard.uat.payglocal.in"

  def build_headers(body_str: str) -> dict:
      digest = base64.b64encode(
          hmac.new(
              API_SECRET.encode(),
              body_str.encode(),
              hashlib.sha256
          ).digest()
      ).decode()
      return {
          "Content-Type": "application/json",
          "x-gl-auth": API_KEY,
          "x-gl-digest": digest,
      }

  payload = {"externalOnboardingId": "partner-001", "panNumber": "ABCDE1234F"}
  # Use compact separators — the digest must match the exact bytes sent
  body_str = json.dumps(payload, separators=(",", ":"))

  response = requests.post(
      f"{BASE_URL}/gcc/v2/partner/merchant/onboard",
      headers=build_headers(body_str),
      data=body_str,
  )
  print(response.json())
  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;
  import java.net.http.*;
  import java.net.URI;

  public class PayGlocalAuth {
      static final String API_KEY    = "your_api_key";
      static final String API_SECRET = "your_api_secret";
      static final String BASE_URL   = "https://api.onboard.uat.payglocal.in";

      static String computeDigest(String input) throws Exception {
          Mac mac = Mac.getInstance("HmacSHA256");
          mac.init(new SecretKeySpec(API_SECRET.getBytes("UTF-8"), "HmacSHA256"));
          return Base64.getEncoder().encodeToString(mac.doFinal(input.getBytes("UTF-8")));
      }

      public static void main(String[] args) throws Exception {
          String body   = "{\"externalOnboardingId\":\"partner-001\",\"panNumber\":\"ABCDE1234F\"}";
          String digest = computeDigest(body);

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(BASE_URL + "/gcc/v2/partner/merchant/onboard"))
              .header("Content-Type", "application/json")
              .header("x-gl-auth",    API_KEY)
              .header("x-gl-digest",  digest)
              .POST(HttpRequest.BodyPublishers.ofString(body))
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());
          System.out.println(response.body());
      }
  }
  ```

  ```javascript Node.js theme={null}
  const crypto = require("crypto");
  const https  = require("https");

  const API_KEY    = "your_api_key";
  const API_SECRET = "your_api_secret";

  function computeDigest(input) {
    return crypto.createHmac("sha256", API_SECRET).update(input).digest("base64");
  }

  const payload = { externalOnboardingId: "partner-001", panNumber: "ABCDE1234F" };
  const body    = JSON.stringify(payload);
  const digest  = computeDigest(body);

  const options = {
    hostname: "api.onboard.uat.payglocal.in",
    path:     "/gcc/v2/partner/merchant/onboard",
    method:   "POST",
    headers: {
      "Content-Type":  "application/json",
      "x-gl-auth":     API_KEY,
      "x-gl-digest":   digest,
      "Content-Length": Buffer.byteLength(body),
    },
  };

  const req = https.request(options, (res) => {
    let data = "";
    res.on("data", (chunk) => (data += chunk));
    res.on("end", () => console.log(JSON.parse(data)));
  });
  req.write(body);
  req.end();
  ```
</CodeGroup>

***

## Code Examples — GET Requests

<CodeGroup>
  ```bash curl theme={null}
  #!/bin/bash
  API_KEY="your_api_key"
  API_SECRET="your_api_secret"

  # Sign the request URI path only — not the full URL
  REQUEST_URI="/gcc/v2/partner/merchant/onboard/business-category"
  DIGEST=$(echo -n "$REQUEST_URI" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

  curl -X GET "https://api.onboard.uat.payglocal.in${REQUEST_URI}" \
    -H "x-gl-auth: $API_KEY" \
    -H "x-gl-digest: $DIGEST"
  ```

  ```python Python theme={null}
  import hmac, hashlib, base64, requests

  API_KEY    = "your_api_key"
  API_SECRET = "your_api_secret"
  BASE_URL   = "https://api.onboard.uat.payglocal.in"

  def get_headers(request_uri: str) -> dict:
      digest = base64.b64encode(
          hmac.new(API_SECRET.encode(), request_uri.encode(), hashlib.sha256).digest()
      ).decode()
      return {"x-gl-auth": API_KEY, "x-gl-digest": digest}

  request_uri = "/gcc/v2/partner/merchant/onboard/pg_onboard_abc123/status"
  response = requests.get(f"{BASE_URL}{request_uri}", headers=get_headers(request_uri))
  print(response.json())
  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  import java.util.Base64;
  import java.net.http.*;
  import java.net.URI;

  public class PayGlocalGet {
      static final String API_KEY    = "your_api_key";
      static final String API_SECRET = "your_api_secret";
      static final String BASE_URL   = "https://api.onboard.uat.payglocal.in";

      static String computeDigest(String input) throws Exception {
          Mac mac = Mac.getInstance("HmacSHA256");
          mac.init(new SecretKeySpec(API_SECRET.getBytes("UTF-8"), "HmacSHA256"));
          return Base64.getEncoder().encodeToString(mac.doFinal(input.getBytes("UTF-8")));
      }

      public static void main(String[] args) throws Exception {
          String requestUri = "/gcc/v2/partner/merchant/onboard/pg_onboard_abc123/status";
          String digest     = computeDigest(requestUri);

          HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create(BASE_URL + requestUri))
              .header("x-gl-auth",   API_KEY)
              .header("x-gl-digest", digest)
              .GET()
              .build();

          HttpResponse<String> response = HttpClient.newHttpClient()
              .send(request, HttpResponse.BodyHandlers.ofString());
          System.out.println(response.body());
      }
  }
  ```

  ```javascript Node.js theme={null}
  const crypto = require("crypto");
  const https  = require("https");

  const API_KEY    = "your_api_key";
  const API_SECRET = "your_api_secret";

  const requestUri = "/gcc/v2/partner/merchant/onboard/pg_onboard_abc123/status";
  const digest     = crypto.createHmac("sha256", API_SECRET).update(requestUri).digest("base64");

  const options = {
    hostname: "api.onboard.uat.payglocal.in",
    path:     requestUri,
    method:   "GET",
    headers: { "x-gl-auth": API_KEY, "x-gl-digest": digest },
  };

  https.request(options, (res) => {
    let data = "";
    res.on("data", (c) => (data += c));
    res.on("end", () => console.log(JSON.parse(data)));
  }).end();
  ```
</CodeGroup>

***

## Common Mistakes

| Mistake                                                                               | Result             |
| ------------------------------------------------------------------------------------- | ------------------ |
| Using the API Key (not the Secret) as the HMAC key                                    | `401 Unauthorized` |
| Computing digest over parsed/re-serialized JSON instead of the raw body               | `401 Unauthorized` |
| Using the full URL (with host) for GET request digest instead of the request URI path | `401 Unauthorized` |
| Using the body for GET request digest instead of the request URI path                 | `401 Unauthorized` |
| Not Base64-encoding the HMAC output                                                   | `401 Unauthorized` |
| Sending the digest as hex instead of Base64                                           | `401 Unauthorized` |

***

## Key Management

* Keys can be generated and rotated from the PayGlocal Partner Dashboard.
* PayGlocal supports **multiple simultaneous active keys** — activate the new key before deactivating the old one for zero-downtime rotation.
* Key expiration policies are configured in accordance with RBI regulations.

<CardGroup>
  <Card title="Create Onboarding" icon="building-columns" href="/docs/api-reference/create-onboarding">
    Your first authenticated API call.
  </Card>

  <Card title="Sandbox Testing" icon="flask" href="/docs/guides/testing">
    Test your auth setup with Sandbox credentials.
  </Card>

  <Card title="FAQ — 401 Errors" icon="circle-question" href="/docs/reference/faq#authentication">
    Diagnose and fix authentication failures.
  </Card>
</CardGroup>


# Key & Credential Management
Source: https://payglocal.in/docs/getting-started/dashboard-and-key-management

Understand what credentials PayGlocal needs, why each one matters, and how to get them from your GCC dashboard.

<Note>
  Not logged into GCC yet? Start at [PayGlocal Dashboards](/docs/getting-started/payglocal-dashboards) first.
</Note>

## Why Do You Need Credentials?

PayGlocal uses a **JWT token-based integration model** for every API call. Before your payment request reaches PayGlocal's servers, it goes through two steps:

<Steps>
  <Step title="Encrypt your payload (JWE)">
    Your payment data is encrypted using **PayGlocal's public key** so only PayGlocal can read it.

    This produces a **JWE token** — a 5-part encrypted blob in the format `header.encryptedKey.iv.ciphertext.tag`.
  </Step>

  <Step title="Sign the encrypted payload (JWS)">
    The JWE is then signed using **your private key** to prove the request came from you.

    This produces a **JWS token** — a 3-part signed token in the format `header.payload.signature`.
  </Step>

  <Step title="Send the request">
    The JWS goes into the `x-gl-token-external` header. The JWE goes in the request body.

    PayGlocal verifies your signature, decrypts the payload, and processes the payment.
  </Step>
</Steps>

**This is why credentials exist.** Each of the five values plays a specific role in this flow:

| Credential                 | Role in the flow                                               |
| -------------------------- | -------------------------------------------------------------- |
| **PayGlocal's Public Key** | Encrypts your payload → only PayGlocal can decrypt             |
| **Your Private Key**       | Signs the request → proves it came from you                    |
| **Public Key ID (KID)**    | Tells PayGlocal which key was used to encrypt                  |
| **Private Key ID (KID)**   | Tells PayGlocal which key pair to verify the signature against |
| **Merchant ID (MID)**      | Identifies your merchant account on every API call             |

<Warning>
  Your **private key is downloaded once** and is not stored by PayGlocal. Keep it in a secrets manager — never commit it to source control or send it over email. If lost, you must regenerate a new key pair and update all integrations.
</Warning>

<Warning>
  Credentials are **environment-specific**. Generate and copy a separate set in **UAT** and in **Production** — keys, Key IDs, and Merchant ID from one environment do not work in the other.
</Warning>

***

## How to Get Each Credential

### Merchant ID (MID)

<Steps>
  <Step title="Log in to your GCC dashboard">
    Open [GCC UAT](https://gcc.uat.payglocal.in) or [GCC Production](https://gcc.prod.payglocal.in).
  </Step>

  <Step title="Open My Account and go to TID Details">
    Click your profile icon in the top-right corner of the dashboard, then click **My Account**.

    <Frame>
      <img alt="Open profile menu and select My Account" />
    </Frame>

    From the headings, click **TID Details**.

    <Frame>
      <img alt="Open TID Details" />
    </Frame>
  </Step>

  <Step title="Copy your Merchant ID">
    Under the **Payment Gateway** section, your **Merchant ID (MID)** is displayed. Copy it.
  </Step>
</Steps>

***

### Public Key & Private Key

Both keys are managed from the Key Management System in GCC. You'll download PayGlocal's public key first, then generate and download your own private key.

#### Downloading Public Key

<Steps>
  <Step title="Navigate to Key Management System">
    In the **left sidebar**, click **Configure**.

    <Frame>
      <img alt="Open Configure in the left sidebar" />
    </Frame>

    Then click **Key Management System**.
  </Step>

  <Step title="Download PayGlocal's Public Key">
    Find **PayGlocal Common Certificate** in the list and click **Download**.

    <Frame>
      <img alt="Download the PayGlocal Common Certificate" />
    </Frame>

    <Note>
      This is **PayGlocal's public key** — you'll use it to encrypt your JWE payload so only PayGlocal can decrypt it.
    </Note>
  </Step>
</Steps>

#### Downloading Private Key

<Steps>
  <Step title="Filter by Key Type">
    In the same Key Management screen, click the **Key Type** dropdown filter.

    <Frame>
      <img alt="Open the Key Type filter" />
    </Frame>
  </Step>

  <Step title="Select RSA">
    From the dropdown menu, select **RSA**.

    <Frame>
      <img alt="Select RSA from the dropdown" />
    </Frame>

    Then click **Apply**.
  </Step>

  <Step title="Generate RSA Key">
    Click the **Generate RSA Key** button in the top-right corner. This creates a new RSA key pair.

    <Frame>
      <img alt="Generate a new RSA key pair" />
    </Frame>
  </Step>

  <Step title="Download Your Private Key">
    Once the key is generated, you'll see it in the table. Click the **Download** icon to save your private key.

    <Frame>
      <img alt="Download your private key" />
    </Frame>

    <Warning>
      **This is your only chance to download the private key.** PayGlocal does not store it. If you lose it, regenerate a new key pair and update all your integrations.
    </Warning>
  </Step>
</Steps>

***

### Key IDs (Public KID & Private KID)

You don't have to hunt for Key IDs separately — each is embedded in the filename of the file you downloaded. The Private Key ID is also shown directly in GCC.

#### Fetching Public Key ID

The Public Key ID is embedded in the filename of **PayGlocal's certificate** you downloaded from GCC.

<Steps>
  <Step title="Go to your Downloads folder">
    Navigate to the folder where the **PayGlocal public key** was downloaded (usually your Downloads folder).
  </Step>

  <Step title="View the filename">
    Look at the filename of the downloaded `.pem` file. It follows this pattern:

    ```
    [PUBLIC_KEY_ID]_[rest-of-filename].pem
    ```

    <Frame>
      <img alt="Public Key ID in the certificate filename" />
    </Frame>
  </Step>

  <Step title="Copy everything before the first underscore">
    The **Public Key ID** is everything before the first underscore (`_`).

    **Example:**

    * Full filename: `834hinrh-8r0n-4657-34nn-fnjhjre33uur_glocal.pem`
    * Public Key ID (KID): `834hinrh-8r0n-4657-34nn-fnjhjre33uur`

    <Note>
      **Pro tip:** Right-click the file → Rename → copy just the Key ID part (everything before the first `_`), then press Escape so you don't actually rename the file.
    </Note>
  </Step>
</Steps>

#### Fetching Private Key ID

Unlike the Public Key ID, your **Private Key ID can be fetched directly from the GCC dashboard** where you generated the RSA key.

<Steps>
  <Step title="Go to Key Management (RSA section)">
    Navigate back to **Configure → Key Management System** and filter by **RSA** (where you generated your private key).
  </Step>

  <Step title="Copy the Key ID from the table">
    In the Key Management table, you'll see your generated RSA key listed with its **Key ID** in the first column.

    <Frame>
      <img alt="Private Key ID in the Key Management table" />
    </Frame>

    Copy the **Key ID** displayed in the table — this is your **Private Key ID**.

    <Note>
      You can also extract it from the downloaded filename, which follows the pattern `<kid>_<mid>.pem`: the part **before** the first `_` is your Private Key ID, and the part **after** it is your Merchant ID (MID). The dashboard method is easier since the Key ID is already displayed.
    </Note>
  </Step>
</Steps>

<CardGroup>
  <Card title="Public Key ID Example" icon="key">
    **Filename:**

    ```
    834hinrh-8r0n-4657-34nn-fnjhjre33uur_glocal.pem
    ```

    **Public Key ID:**

    ```
    834hinrh-8r0n-4657-34nn-fnjhjre33uur
    ```

    ✅ Everything before the first `_`
  </Card>

  <Card title="Private Key ID Example" icon="key">
    **Filename:**

    ```
    884hiurh-8e0b-4907-38nn-fuerikejr89_paygmerchant.pem
    ```

    **Private Key ID:**

    ```
    884hiurh-8e0b-4907-38nn-fuerikejr89
    ```

    ✅ Everything before the first `_`
  </Card>
</CardGroup>

***

## Quick Reference

| # | Credential     | Where to get it                                                                      |
| - | -------------- | ------------------------------------------------------------------------------------ |
| 1 | Merchant ID    | GCC → Profile icon → My Account → TID Details → Payment Gateway                      |
| 2 | Public Key     | GCC → Configure → Key Management → PayGlocal Common Certificate                      |
| 3 | Private Key    | GCC → Configure → Key Management → Generate RSA Key                                  |
| 4 | Public Key ID  | Public key `.pem` filename — text before the first `_`                               |
| 5 | Private Key ID | GCC Key Management table, or private key `.pem` filename — text before the first `_` |

***

## Next Steps

<CardGroup>
  <Card title="Key Management Deep Dive" icon="key" href="/docs/key-management/overview">
    JWS signing mechanics, key rotation, and environments.
  </Card>

  <Card title="Choose for Integration" icon="map" href="/docs/integration/overview">
    Choose between No-Code and API integration based on how your business collects payments.
  </Card>
</CardGroup>

Questions? Reach out at [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).


# PayGlocal Dashboards
Source: https://payglocal.in/docs/getting-started/payglocal-dashboards

Learn about the Glocal Command Center (GCC) — PayGlocal's merchant dashboard — and how to access each environment.

## What is GCC?

At PayGlocal, the merchant dashboard is called the **Glocal Command Center (GCC)**. Use it to:

* Track transactions and download reports
* Manage cryptographic keys and credentials
* Configure payment products and settings
* Monitor recent transaction and API activity

You'll need GCC access before you can complete any PayGlocal integration.

***

## Two GCC Environments

PayGlocal operates **two separate GCC instances** — one for testing, one for live operations. Use the environment that matches what you're doing — building/testing or going live.

<CardGroup>
  <Card title="GCC UAT" icon="flask">
    **For sandbox testing.**
    No real money moves. Use this environment while building and testing your integration.

    **URL:** [gcc.uat.payglocal.in](https://gcc.uat.payglocal.in)
  </Card>

  <Card title="GCC Production" icon="building-columns">
    **For live operations.**
    Real transactions. Switch here only after completing sandbox testing and receiving go-live approval.

    **URL:** [gcc.prod.payglocal.in](https://gcc.prod.payglocal.in)
  </Card>
</CardGroup>

<Warning>
  Never mix UAT credentials with Production. Each environment has its own separate username, password, keys, and Merchant ID.
</Warning>

<Note>
  These are **dashboard** URLs for logging in — not the API base endpoints your code calls. For API base URLs, see [Authentication](/docs/authentication).
</Note>

<Note>
  Your account manager may reference alternate hostnames such as `merchant.uat.payglocal.in` or `merchant.payglocal.in`. Use whichever URL you were given during onboarding — each points to the same environment as its matching GCC URL.
</Note>

***

## How to Log In

<Steps>
  <Step title="Open the correct GCC URL">
    Go to the GCC URL for your environment — **UAT** for testing, **Production** for live. Use the links in the cards above.
  </Step>

  <Step title="Enter your credentials">
    Sign in with the **username and password** issued by PayGlocal during onboarding.
  </Step>

  <Step title="Complete second-factor authentication">
    Complete any **second factor** (OTP) if your account requires it.
  </Step>
</Steps>

<Frame>
  <img alt="PayGlocal GCC Login Page" />
</Frame>

<Note>
  If you do not have credentials yet, contact your **PayGlocal account manager** or reach out at [sales@payglocal.in](mailto:sales@payglocal.in).
</Note>

***

## Business Overview Dashboard

After you log in, you'll land on the **Business Overview** page, where you can:

* View successful payments and settlements
* Track funds on hold and open disputes
* Access quick actions like creating payment links and viewing API keys
* Monitor recent transaction activity

<Frame>
  <img alt="GCC Business Overview Dashboard" />
</Frame>

***

## Next Steps

Once you are logged in, your next task is to set up your cryptographic keys and copy the credentials needed for API calls.

<Card title="Key & Credential Management" icon="key" href="/docs/getting-started/dashboard-and-key-management">
  Generate your private key, copy your Merchant ID and Key IDs from GCC, and prepare for API integration.
</Card>


# API Flow Overview
Source: https://payglocal.in/docs/guides/api-flow-overview

Understand the complete merchant onboarding sequence before writing a single line of code.

## Onboarding Lifecycle

Merchant onboarding on PayGlocal is a **sequential, stateful process**. Each API call enriches the merchant record, and PayGlocal validates completeness before allowing the final verification step.

```
Partner System                          PayGlocal API
      │                                       │
      │  POST /onboard  ─────────────────────▶│  Creates merchant record
      │◀───────────────  onboardingId  ───────│  Returns onboardingId
      │                                       │
      │  PUT /business-details ──────────────▶│  Stores business info
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /beneficial-owner ──────────────▶│  Stores UBOs
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /bank-details ──────────────────▶│  Penny drop validation
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /auth-signatory ────────────────▶│  Stores signatory details
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /docs (repeat per doc) ─────────▶│  Uploads compliance docs
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /products ──────────────────────▶│  Configures products & fees
      │◀─────────────────────────────────────│  200 OK
      │                                       │
      │  PUT /verification/{id}/redirect ──────▶│  Generates verification URL
      │◀──────────────── redirectLink ──────────│  Merchant completes VKYC
      │                                       │
      │  GET /status ────────────────────────▶│  Confirm final status
      │◀─────────────────────────────────────│  vkyc & digiLocker COMPLETE
```

## Step-by-Step Breakdown

<Steps>
  <Step title="Create Onboarding Record">
    `POST /gcc/v2/partner/merchant/onboard`

    Initiate the onboarding with the merchant's PAN and your internal `externalOnboardingId`. This is the entry point — all subsequent calls reference the `onboardingId` returned here.

    **Key output:** `onboardingId` (a PayGlocal-generated ID for this merchant's onboarding session)
  </Step>

  <Step title="Submit Business Details">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/business-details`

    Provide entity type, GST number, nature of business (from the [Business Categories](/docs/reference/business-categories) reference), website URL, expected monthly transaction volume, and registered/operating address.

    Use the [State Codes](/docs/reference/state-codes) reference for `stateCode` fields.
  </Step>

  <Step title="Add Beneficial Owners">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/beneficial-owner`

    Submit all Ultimate Beneficial Owners (UBOs) holding ≥10% ownership. The array in the request **completely replaces** the existing beneficial owner list — always send all UBOs together.
  </Step>

  <Step title="Add Bank Details">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/bank-details`

    Submit the settlement bank account. PayGlocal performs a **penny drop verification** to confirm the account is active and the IFSC code is valid. The account must be either CURRENT or SAVINGS type.
  </Step>

  <Step title="Add Authorised Signatory">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/auth-signatory`

    Submit the details of the individual authorized to sign on behalf of the business. This person's phone and email are used during VKYC and DigiLocker verification, so accuracy is critical.
  </Step>

  <Step title="Upload Documents">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/docs`

    Upload each required compliance document as a separate API call. The `merchantDocType` field specifies the document category (e.g., `PAN`, `COI_DOCUMENT`, `OPERATING_ADDRESS_PROOF`). See the [Upload Documents](/docs/api-reference/upload-documents) reference for the full list.
  </Step>

  <Step title="Configure Products and Fees">
    `PUT /gcc/v2/partner/merchant/onboard/{onboardingId}/products`

    Specify which payment products to enable for the merchant (`GLOBAL_FUND_TRANSFER`, `INTERNATIONAL_CARDS_AND_ALT_PAYS`, `DOMESTIC_CARDS_UPI_AND_INB`) and configure per-product fee structures.
  </Step>

  <Step title="Trigger Merchant Verification">
    `PUT /gcc/v2/partner/merchant/verification/{onboardingId}/redirect`

    Generates a unique `redirectLink` for the merchant to complete VKYC, DigiLocker document verification, and T\&C acknowledgement. Embed this URL in an iFrame — see the [iFrame Integration](/docs/guides/iframe-integration) guide.

    Authenticate with `x-gl-auth` and `x-gl-digest` (sign the request body). Call only after all pre-verification checklist steps are complete.
  </Step>

  <Step title="Confirm Final Status">
    `GET /gcc/v2/partner/merchant/onboard/{onboardingId}/status`

    After the merchant completes the verification flow and is redirected to your `callBackUrl`, always perform a server-to-server status check to confirm the VKYC and DigiLocker checklist statuses are `COMPLETE`.

    Never rely solely on the callback URL redirect to determine completion.
  </Step>
</Steps>

## State Transitions

| `onboardingStatus`     | Meaning                                              |
| ---------------------- | ---------------------------------------------------- |
| `INITIATED`            | Onboarding record created, details not yet submitted |
| `IN_PROGRESS`          | One or more detail sections submitted                |
| `PENDING_VERIFICATION` | All details submitted, awaiting merchant VKYC        |
| `PENDING_REVIEW`       | VKYC complete, under PayGlocal compliance review     |
| `APPROVED`             | Merchant fully onboarded and activated               |
| `REJECTED`             | Onboarding rejected after review                     |
| `RFI`                  | Request for Information — additional data required   |

## Important Constraints

* **Business details and authorised signatory** cannot be updated after the merchant has acknowledged the T\&C.
* **Beneficial owner and bank details** cannot be updated after the verification step is complete.
* Attempting to call the verification redirect endpoint before all required steps are complete returns `400 Bad Request`.
* The `externalOnboardingId` must be unique per merchant in your system — it cannot be reused.


# iFrame Integration
Source: https://payglocal.in/docs/guides/iframe-integration

Embed the PayGlocal Verification Suite — VKYC, DigiLocker, and T&C acknowledgement — directly inside your partner dashboard.

Partners can embed the PayGlocal Verification Suite directly into their existing dashboard so merchants can complete identity verification without leaving the partner platform.

The verification suite covers:

* **VKYC** — Video-based KYC using the merchant's live camera
* **DigiLocker** — Government document verification via DigiLocker
* **T\&C Acknowledgement** — Merchant accepts PayGlocal terms and conditions

***

## Step 1: Domain Whitelisting (Action Required)

<Warning>
  Your iFrame **will not render** until your domain is whitelisted by PayGlocal. This step must be completed before testing the iFrame in any environment.
</Warning>

PayGlocal uses a strict **Content Security Policy (CSP)** with `frame-ancestors` directives to prevent Clickjacking attacks. Browsers will display a `frame-ancestors violation` console error and block the iFrame until your domain is authorized.

**To request whitelisting**, contact your assigned PayGlocal Account Manager with:

| Field            | Value                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------- |
| **Partner Name** | Your legal entity name                                                                  |
| **Environment**  | Sandbox, Production, or both                                                            |
| **Domain URLs**  | Exact URLs where the iFrame will be hosted (e.g., `https://onboarding.yourcompany.com`) |

Allow 1–2 business days for the PayGlocal team to activate the CSP allowance.

***

## Step 2: Integration Workflow

<Steps>
  <Step title="Initialize — Generate the verification session URL">
    Before rendering the iFrame, call the [Get Verification Redirect API](/docs/api-reference/get-verification-redirect) from your **backend** to generate a session URL for the merchant.

    ```bash theme={null}
    BODY='{"callBackUrl":"https://your-domain.com/onboarding-success"}'
    DIGEST=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

    curl -X PUT "https://api.onboard.uat.payglocal.in/gcc/v2/partner/merchant/verification/{onboardingId}/redirect" \
      -H "Content-Type: application/json" \
      -H "x-gl-auth: $API_KEY" \
      -H "x-gl-digest: $DIGEST" \
      -d "$BODY"
    ```

    Response:

    ```json theme={null}
    {
      "gid": "gl_9c2645ed09edb22e",
      "timestamp": "10/01/2026 15:00:00",
      "reasonCode": "",
      "message": "digilocker redirect url generated successfully",
      "data": {
        "redirectLink": "https://uat.dashboard.payglocal.in/app/partner-onboarding?token=abc123&onboardingId=pg_onboard_abc123",
        "onboardingId": "pg_onboard_abc123"
      }
    }
    ```

    Save the `data.redirectLink` value — this is the `src` for your iFrame. The URL includes a single-use session token valid for 24 hours.

    <Note>
      The `callBackUrl` is stored on the merchant record and used as the redirect target after verification completes. It must be a full HTTPS URL on your whitelisted domain.
    </Note>
  </Step>

  <Step title="Embed — Load the redirectLink in an iFrame">
    Inject the `redirectLink` as the `src` of an iFrame on your page. The `allow` attributes below are **mandatory** — without them, the browser will block camera and microphone access during VKYC.

    ```html theme={null}
    <div id="pg-iframe-wrapper" style="width: 100%; max-width: 1000px; height: 800px; margin: auto;">
      <iframe
        id="payglocal-onboarding-ui"
        src="INSERT_REDIRECT_LINK_HERE"
        width="100%"
        height="700px"
        allow="camera; microphone; geolocation"
        frameborder="0"
        style="border: 1px solid #e0e0e0; border-radius: 8px;">
      </iframe>
    </div>
    ```

    ```javascript theme={null}
    // Dynamically set the src after fetching the redirectLink from your backend
    const iframe = document.getElementById("payglocal-onboarding-ui");
    iframe.src = redirectLink; // value returned by the Get Verification Redirect API
    ```
  </Step>

  <Step title="Handle Callback — Listen for completion">
    PayGlocal signals completion in two ways:

    **Option A — postMessage (recommended for real-time UX)**

    Listen for `message` events from the iFrame. When verification completes, PayGlocal posts `PARTNER_MERCHANT_VERIFICATION_COMPLETE`.

    ```javascript theme={null}
    window.addEventListener("message", function(event) {
      // Validate origin — UAT or Production dashboard domain
      const allowedOrigins = [
        "https://uat.dashboard.payglocal.in",
        "https://dashboard.payglocal.in"
      ];
      if (!allowedOrigins.includes(event.origin)) return;

      if (event.data === "PARTNER_MERCHANT_VERIFICATION_COMPLETE") {
        console.log("Merchant verification completed.");
        // Trigger server-side GET /status to confirm final state
      }
    }, false);
    ```

    During intermediate steps (e.g. DigiLocker redirect), the iFrame may also post structured events such as `PARTNER_MERCHANT_VERIFICATION_REDIRECT`. See [Partner Onboarding Events](/docs/guides/partner-onboarding-events) for the full event reference.

    **Option B — callBackUrl redirect**

    After the merchant finishes, PayGlocal redirects the iFrame to the `callBackUrl` you provided. Your page at that URL can render a completion screen.

    <Warning>
      After the iFrame callback, **always perform a server-to-server status check** by calling `GET /gcc/v2/partner/merchant/onboard/{onboardingId}/status` to confirm that `vkyc` and `digiLocker` statuses are `COMPLETE`. Do not rely on the callback redirect alone to confirm completion.
    </Warning>
  </Step>
</Steps>

***

## Technical Requirements and Best Practices

<Warning>
  The parent page hosting the iFrame **must be served over HTTPS**. Modern browsers block camera and microphone access on insecure (HTTP) origins, which will break VKYC.
</Warning>

| Requirement                   | Detail                                                                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTPS**                     | Parent page must use HTTPS. HTTP origins will block camera/microphone access.                                                         |
| **Minimum height**            | Set the iFrame container to at least **700px** height to prevent internal scrollbars during the VKYC video call.                      |
| **Permissions Policy header** | Ensure your server does not send a `Permissions-Policy: camera=()` or similar header that conflicts with iFrame permissions.          |
| **Origin validation**         | Validate `event.origin` against `https://uat.dashboard.payglocal.in` (UAT) or `https://dashboard.payglocal.in` (Production).          |
| **Server-side confirmation**  | After callback, always call `GET /status` server-to-server to confirm the final merchant state.                                       |
| **Token expiry**              | Session tokens in `redirectLink` expire after 24 hours. Generate a fresh link if the merchant does not complete verification in time. |
| **Responsive design**         | The verification suite is mobile-responsive. Your container should be flexible-width with a fixed minimum height.                     |

***

## Complete Frontend Example

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Merchant Verification</title>
  <style>
    #pg-iframe-wrapper {
      width: 100%;
      max-width: 1000px;
      height: 800px;
      margin: 0 auto;
    }
    #payglocal-onboarding-ui {
      width: 100%;
      height: 700px;
      border: 1px solid #e0e0e0;
      border-radius: 8px;
    }
  </style>
</head>
<body>
  <div id="pg-iframe-wrapper">
    <iframe
      id="payglocal-onboarding-ui"
      allow="camera; microphone; geolocation"
      frameborder="0">
    </iframe>
  </div>

  <script>
    const ALLOWED_ORIGINS = [
      "https://uat.dashboard.payglocal.in",
      "https://dashboard.payglocal.in"
    ];

    // Step 1: Fetch the redirectLink from your backend (which calls the PayGlocal redirect API)
    fetch("/api/get-verification-url?onboardingId=YOUR_ONBOARDING_ID")
      .then(res => res.json())
      .then(data => {
        document.getElementById("payglocal-onboarding-ui").src = data.redirectLink;
      });

    // Step 2: Listen for completion signal from PayGlocal
    window.addEventListener("message", function(event) {
      if (!ALLOWED_ORIGINS.includes(event.origin)) return;

      if (event.data === "PARTNER_MERCHANT_VERIFICATION_COMPLETE") {
        // Step 3: Trigger a server-side status check before updating UI
        fetch("/api/check-onboarding-status?onboardingId=YOUR_ONBOARDING_ID")
          .then(res => res.json())
          .then(status => {
            if (status.vkyc === "COMPLETE" && status.digiLocker === "COMPLETE") {
              console.log("Verification complete. Redirecting...");
              window.location.href = "/onboarding-success";
            }
          });
      }
    }, false);
  </script>
</body>
</html>
```


# Merchant Requirements
Source: https://payglocal.in/docs/guides/merchant-requirements

Who you can onboard and what documents you'll need to collect from them.

Before you start onboarding, know these three axes that determine what you need to collect from a merchant:

1. **Entity type** — drives the core KYC + business document set.
2. **Business category** — some categories (jewelry, insurance, F\&B, travel) need an extra regulatory certificate.
3. **Products you enable** — enabling cards adds a website due-diligence check.

This page covers all three.

***

## Eligible entity types

PayGlocal onboards the following 6 entity types. Anything else is not eligible.

| Entity type                         | `entityType` enum value |
| ----------------------------------- | ----------------------- |
| Freelancer (Individual)             | `INDIVIDUAL`            |
| Sole Proprietor                     | `PROPRIETOR`            |
| Partnership                         | `PARTNERSHIP_FIRM`      |
| LLP (Limited Liability Partnership) | `LLP_FIRM`              |
| Private Limited Company             | `PVT_LTD_COMPANY`       |
| Public Limited Company              | `PUBLIC_LTD_COMPANY`    |

Send the enum value in the `entityType` field on [Update Business Details](/docs/api-reference/update-business-details).

***

## Documents by entity type

Click your merchant's entity type to see the exact list.

<Tabs>
  <Tab title="Freelancer">
    **Identity & verification**

    * PAN of the individual
    * Bank account details (penny-drop verification runs automatically)
    * DigiLocker identity verification
    * VKYC of the individual

    **Business**

    * GST details (where applicable)
    * Declaration of line of business + projected monthly transaction volume
  </Tab>

  <Tab title="Sole Proprietor">
    **Identity & verification**

    * PAN of the individual
    * Bank account details (penny-drop verification runs automatically)
    * DigiLocker identity verification
    * VKYC of the individual

    **Business**

    * GST details (where applicable)
    * Declaration of line of business + projected monthly transaction volume
    * **Business proof** — any one of:
      * Import Export Code (IEC)
      * GST Registration Certificate
      * Utility Bill
      * Income Tax Return (ITR)
      * Udyam Registration Certificate
      * Shop and Establishment Certificate
  </Tab>

  <Tab title="Partnership">
    **Entity**

    * PAN of the firm
    * Entity bank account (verified automatically)
    * GST details (where applicable)
    * Line of business, website, and projected volume declaration
    * List of partners with PAN and shareholding details
    * **Partnership Deed**

    **Authorized Signatory (AS)**

    * AS must be one of the partners; otherwise, an **Authorization Letter on firm letterhead** appointing the AS is required
    * KYC on the AS: PAN verification, DigiLocker, VKYC
  </Tab>

  <Tab title="LLP">
    **Entity**

    * PAN of the firm
    * Entity bank account (verified automatically)
    * GST details (where applicable)
    * Line of business, website, and projected volume declaration
    * List of partners with PAN and shareholding details
    * **LLP Deed** + **Certificate of Incorporation**

    **Authorized Signatory (AS)**

    * AS must be one of the partners; otherwise, an **Authorization Letter on firm letterhead** appointing the AS is required
    * KYC on the AS: PAN verification, DigiLocker, VKYC
  </Tab>

  <Tab title="Private Limited">
    **Entity**

    * PAN of the company
    * Entity bank account (verified automatically)
    * GST details (where applicable)
    * Line of business, website, and projected volume declaration
    * List of directors and **beneficial owners** (equity holders above 10%) with PAN and shareholding
    * **MOA**, **AOA**, **COI**

    **Authorized Signatory (AS)**

    * AS must be one of the directors; otherwise, a **Board Resolution on company letterhead** appointing the AS is required
    * KYC on the AS: PAN verification, DigiLocker, VKYC

    <Note>
      Where feasible, PayGlocal auto-fetches MOA, AOA, and COI directly from government sources. You only need to upload these manually if the auto-fetch is unsuccessful.
    </Note>
  </Tab>

  <Tab title="Public Limited">
    **Entity**

    * PAN of the company
    * Entity bank account (verified automatically)
    * GST details (where applicable)
    * Line of business, website, and projected volume declaration
    * List of directors and **beneficial owners** (equity holders above 10%) with PAN and shareholding
    * **MOA**, **AOA**, **COI**

    **Authorized Signatory (AS)**

    * AS must be one of the directors; otherwise, a **Board Resolution on company letterhead** appointing the AS is required
    * KYC on the AS: PAN verification, DigiLocker, VKYC

    <Note>
      Where feasible, PayGlocal auto-fetches MOA, AOA, and COI directly from government sources. You only need to upload these manually if the auto-fetch is unsuccessful.
    </Note>
  </Tab>
</Tabs>

<Note>
  Document types map to the `merchantDocType` enum on [Upload Documents](/docs/api-reference/upload-documents) — for example, `PARTNERSHIP_DEED`, `LLP_AGREEMENT`, `MOA`, `AOA`, `COI`, `IEC`.
</Note>

***

## Category-specific compliance

Merchants in certain regulated sectors must provide an additional certificate. This applies **on top of** the entity-type requirements above.

| Business category    | Mandatory certificate                                |
| -------------------- | ---------------------------------------------------- |
| Jewelry              | Bureau of Indian Standards / Hallmarking Certificate |
| Insurance            | IRDAI License                                        |
| Food & Beverages     | FSSAI License                                        |
| International Travel | IATA Certification                                   |

<Warning>
  If the merchant exports physical goods internationally, **Import Export Code (IEC)** is mandatory regardless of entity type.
</Warning>

This list is indicative and may be updated based on regulatory developments. When in doubt, contact [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).

***

## Website due diligence

If the merchant wants to enable the **cards** product, the merchant's website must satisfy the following before the verification step:

* Valid **privacy policy**, **refund policy**, **terms and conditions**, and **shipping policy** pages
* Clear display of **products sold and their pricing**
* Merchant's **trade name or registered name** clearly visible

Gaps here will block the compliance review even after VKYC succeeds.

***

## What PayGlocal auto-fetches

For Partnerships, LLPs, and Companies, PayGlocal attempts to auto-fetch the following from government sources:

* Partnership Deed / LLP Deed
* MOA, AOA, COI
* Udyam Registration (where available)

If the auto-fetch fails, PayGlocal will flag the onboarding with status `RFI` and request manual upload via [Upload Documents](/docs/api-reference/upload-documents).

***

## Dynamic document pendencies

Every onboarding API response includes `documentsToBeUploaded` in the checklist status. This array tells you exactly which documents are still required for the current merchant state. Poll [Get Onboarding Status](/docs/api-reference/get-status) after each step to get the updated list.

| Trigger                                                              | `documentsToBeUploaded` key                                | `merchantDocType` for upload                                                                                                                                        |
| -------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operating address ≠ registered address                               | `OPERATING_ADDRESS_PROOF`                                  | `OPERATING_ADDRESS_PROOF`                                                                                                                                           |
| Sole Proprietor                                                      | `SOLE_PROP_DOC_1_UPLOAD`, `SOLE_PROP_DOC_2_UPLOAD`         | Any value from `solePropDocs` in the response: `UDYAM`, `UTILITY_BILL`, `ITR`, `SHOP_ESTABLISHMENT_CERTIFICATE`, `IEC`, `GST_SUPPORTING_CERTIFICATE`                |
| PVT LTD / Partnership — beneficial owner Aadhaar                     | `{PAN}_{NAME}_AADHAR`                                      | Dynamic per BO (e.g. `ABCDE1234F_JOHN_DOE_AADHAR`)                                                                                                                  |
| Auth signatory is not a beneficial owner                             | `REPRESENTATIVE_DOC`                                       | `REPRESENTATIVE_DOC`                                                                                                                                                |
| Partnership Firm                                                     | `PARTNERSHIP_DEED`, `PARTNERSHIP_REGISTRATION_CERTIFICATE` | `PARTNERSHIP_DEED`, `PARTNERSHIP_REGISTRATION_CERTIFICATE`                                                                                                          |
| Partnership — unregistered firm                                      | —                                                          | Set `noPartnershipRegistrationCheck: true` in [Update Business Details](/docs/api-reference/update-business-details) to skip `PARTNERSHIP_REGISTRATION_CERTIFICATE` |
| LLP (Firm)                                                           | `LLP_AGREEMENT`                                            | `LLP_AGREEMENT`                                                                                                                                                     |
| Individual + website contains linkedin/instagram + Services business | `FREELANCER_DOC_UPLOAD`                                    | `ITR`, `SERVICE_LEVEL_AGREEMENT`, or `BANK_STATEMENT`                                                                                                               |
| Regulated line of business                                           | `LOB_DOCUMENT`                                             | `LOB_DOCUMENT`                                                                                                                                                      |
| Penny drop verification fails (Production)                           | `CANCELLED_CHEQUE`                                         | `CANCELLED_CHEQUE`                                                                                                                                                  |

<Note>
  In UAT, use bank account `1234567890` and IFSC `SBIN0000000` for successful penny drop. Any other combination triggers a `CANCELLED_CHEQUE` pendency. See [Sandbox Testing](/docs/guides/testing#partner-onboarding-bank-verification).
</Note>

***

<CardGroup>
  <Card title="API Flow Overview" icon="diagram-project" href="/docs/guides/api-flow-overview">
    End-to-end sequence of all 10 onboarding endpoints.
  </Card>

  <Card title="Events & Webhooks" icon="bell" href="/docs/guides/partner-onboarding-events">
    Track merchant progress via postMessage and webhooks.
  </Card>
</CardGroup>


# Partner Onboarding Events
Source: https://payglocal.in/docs/guides/partner-onboarding-events

How PayGlocal notifies your platform when a merchant progresses through the onboarding journey — iFrame postMessage events and server-side webhooks.

PayGlocal provides two channels for partners to track merchant onboarding progress:

| Channel                     | Delivery               | Best for                                           |
| --------------------------- | ---------------------- | -------------------------------------------------- |
| **UI Events (postMessage)** | Browser → parent page  | Real-time UX updates while the iFrame is open      |
| **Webhooks**                | Server → your endpoint | Reliable async notifications for backend workflows |

<Warning>
  Always confirm the final onboarding state with a server-side [Get Onboarding Status](/docs/api-reference/get-status) call. Neither UI events nor webhooks alone should be treated as the source of truth for go-live decisions.
</Warning>

***

## UI Events (iFrame postMessage)

When you embed the PayGlocal verification iFrame, the verification page communicates with your parent page using the browser's `postMessage` API.

### Listening for completion

```javascript theme={null}
window.addEventListener("message", (event) => {
  const allowedOrigins = [
    "https://uat.dashboard.payglocal.in",
    "https://dashboard.payglocal.in"
  ];
  if (!allowedOrigins.includes(event.origin)) return;

  console.log("Message received:", event.data);

  if (event.data === "PARTNER_MERCHANT_VERIFICATION_COMPLETE") {
    console.log("Onboarding verification completed!");
    // Trigger server-side GET /status to confirm final state
  }
});
```

| Event value                              | Meaning                                                                   |
| ---------------------------------------- | ------------------------------------------------------------------------- |
| `PARTNER_MERCHANT_VERIFICATION_COMPLETE` | Merchant has finished the full verification flow (T\&C, DigiLocker, VKYC) |

During intermediate steps, the iFrame may also emit structured events:

```javascript theme={null}
{
  eventName: "PARTNER_MERCHANT_VERIFICATION_REDIRECT",
  eventData: {
    uri: "https://...",
    stepName: "DIGILOCKER",
    subStepId: "CONSENT_PROCEED"
  }
}
```

### Best practices

* **Validate `event.origin`** — only accept messages from `https://uat.dashboard.payglocal.in` (UAT) or `https://dashboard.payglocal.in` (Production). The iFrame loads the PayGlocal dashboard partner onboarding experience, not a separate verify subdomain.
* **Follow with GET /status** — the postMessage signals UI completion; confirm `vkyc`, `digiLocker`, and `onboardingStatus` server-side before updating your merchant record.
* See [iFrame Integration](/docs/guides/iframe-integration) for the full embed workflow.

***

## Webhook Events

PayGlocal sends server-side webhook notifications to URLs configured in your PayGlocal Partner Dashboard. Webhooks fire for **partner-assisted** merchant onboardings only.

Configure which events you receive via `POST /gcc/v2/partner/{resellerMid}/webhook`. List available event types with `GET /gcc/v2/partner/webhook`.

### Supported events

| Event                                        | When fired                                | Description                                |
| -------------------------------------------- | ----------------------------------------- | ------------------------------------------ |
| `MERCHANT_DIGILOCKER_CKYC_COMPLETED`         | DigiLocker or CKYC verification completes | Identity verification step finished        |
| `MERCHANT_TERMS_AND_CONDITIONS_ACKNOWLEDGED` | Merchant accepts T\&C                     | Terms and conditions acknowledged          |
| `MERCHANT_VKYC_COMPLETED`                    | VKYC session completes                    | Video KYC finished                         |
| `MERCHANT_STATUS_ACCEPTED`                   | Merchant is activated                     | Onboarding approved and merchant goes live |
| `MERCHANT_PENDENCY_STATUS_UPDATED`           | Pendency status changes                   | Document or compliance pendency updated    |

<Note>
  System-created pendencies with status `UNDER_REVIEW` are **not** sent to partners. Only partner-visible pendency updates trigger this webhook.
</Note>

***

## Webhook Payload Structure

All onboarding webhook payloads are flat key-value maps (`Map<String, String>`).

### Common fields (all events)

| Field               | Type   | Description                                          |
| ------------------- | ------ | ---------------------------------------------------- |
| `onboarding_id`     | string | PayGlocal onboarding ID                              |
| `onboarding_status` | string | Current `NewOnboardingStatus` value                  |
| `event_timestamp`   | string | Unix epoch milliseconds when the event was generated |
| `status`            | string | Event type name (matches the event enum)             |

### Event-specific fields

**`MERCHANT_STATUS_ACCEPTED`**

| Field             | Description                                       |
| ----------------- | ------------------------------------------------- |
| `merchant_id`     | Activated merchant ID (UCIC)                      |
| `event_timestamp` | Go-live timestamp (overwritten with go-live time) |

**`MERCHANT_TERMS_AND_CONDITIONS_ACKNOWLEDGED`**

| Field                               | Description |
| ----------------------------------- | ----------- |
| `terms_and_conditions_acknowledged` | `"true"`    |

**`MERCHANT_VKYC_COMPLETED`**

| Field            | Description |
| ---------------- | ----------- |
| `vkyc_completed` | `"true"`    |

**`MERCHANT_DIGILOCKER_CKYC_COMPLETED`**

| Field                       | Description |
| --------------------------- | ----------- |
| `digilocker_ckyc_completed` | `"true"`    |

**`MERCHANT_PENDENCY_STATUS_UPDATED`**

| Field                                   | Description                                 |
| --------------------------------------- | ------------------------------------------- |
| `pendency_info_category`                | Pendency category                           |
| `pendency_info_sub_category`            | Pendency sub-category                       |
| `pendency_info_reason`                  | Reason for the pendency                     |
| `pendency_info_status`                  | Current pendency status                     |
| `pendency_info_creation_time`           | When the pendency was created               |
| `pendency_info_cards_approval_blocking` | `"true"` / `"false"` — blocks card approval |
| `pendency_info_mca_approval_blocking`   | `"true"` / `"false"` — blocks MCA approval  |

### Example payload — VKYC completed

```json theme={null}
{
  "onboarding_id": "pg_onboard_abc123",
  "onboarding_status": "UNDER_REVIEW",
  "event_timestamp": "1717238400000",
  "status": "MERCHANT_VKYC_COMPLETED",
  "vkyc_completed": "true"
}
```

### Example payload — Merchant accepted

```json theme={null}
{
  "onboarding_id": "pg_onboard_abc123",
  "onboarding_status": "ACCEPTED",
  "event_timestamp": "1717324800000",
  "status": "MERCHANT_STATUS_ACCEPTED",
  "merchant_id": "merchant_xyz789"
}
```

***

## Recommended Integration Pattern

```
1. Partner completes onboard API steps (business details → products)
2. Partner calls GET Verification Redirect → embeds iFrame
3. Parent page listens for PARTNER_MERCHANT_VERIFICATION_COMPLETE postMessage
4. Partner backend receives webhook events asynchronously
5. Partner backend calls GET /status to confirm final state
6. Partner updates merchant record in their system
```

<CardGroup>
  <Card title="iFrame Integration" icon="browser" href="/docs/guides/iframe-integration">
    Embed the verification flow and handle postMessage events.
  </Card>

  <Card title="Get Onboarding Status" icon="circle-check" href="/docs/api-reference/get-status">
    Confirm final merchant state server-side.
  </Card>

  <Card title="API Flow Overview" icon="diagram-project" href="/docs/guides/api-flow-overview">
    End-to-end onboarding sequence.
  </Card>
</CardGroup>


# How API Integration Works
Source: https://payglocal.in/docs/integration/api-overview

Understand PayGlocal's two API integration modes — Checkout Flow (PayCollect) and Seamless Flow (PayDirect) — and the payment types that work with both.

With API integration, your backend calls PayGlocal's APIs, and PayGlocal handles processing, 3DS authentication, and security. Building an integration means two independent choices:

<CardGroup>
  <Card title="1. Integration mode" icon="shuffle">
    **How you collect card details** — on PayGlocal's hosted page (**Checkout Flow / PayCollect**) or in your own UI (**Seamless Flow / PayDirect**).
  </Card>

  <Card title="2. Payment type" icon="layer-group">
    **What kind of payment you run** — Regular, Recurring, Auth & Capture, or CodeDrop. These work with **either** mode.
  </Card>
</CardGroup>

The two axes are independent: pick the mode that matches your PCI status, then implement whichever payment types your business needs.

***

## Step 1 — Choose an Integration Mode

The deciding question: **who collects the card details — you or PayGlocal?**

<CardGroup>
  <Card title="Checkout Flow (PayCollect)" icon="window" href="/docs/merchant/paycollect/overview">
    **PayGlocal collects card details** on a secure hosted page. You send a request and never touch card data.

    → No PCI DSS certification needed.

    [Checkout Flow (PayCollect) details →](/docs/merchant/paycollect/overview)
  </Card>

  <Card title="Seamless Flow (PayDirect)" icon="code" href="/docs/merchant/paydirect/overview">
    **You collect card details** in your own checkout UI and send them to PayGlocal. No redirect.

    → Requires PCI DSS certification.

    [Seamless Flow (PayDirect) details →](/docs/merchant/paydirect/overview)
  </Card>
</CardGroup>

***

## Step 2 — Choose Your Payment Types

Payment types are **mode-agnostic** — each works with Checkout Flow (PayCollect) or Seamless Flow (PayDirect).

<CardGroup>
  <Card title="Regular Payment" icon="credit-card" href="/docs/merchant/regular-payment">
    One-time, immediate payments — status tracking and refunds.
  </Card>

  <Card title="Recurring Payment" icon="rotate" href="/docs/merchant/recurring-payment">
    Standing Instructions — Auto Debit and On-Demand mandate flows.
  </Card>

  <Card title="Auth & Capture" icon="shield-check" href="/docs/merchant/auth-capture-guide">
    Hold funds now, capture when you're ready to fulfill.
  </Card>

  <Card title="CodeDrop" icon="square-code" href="/docs/merchant/paycollect/codedrop">
    Embed the payment form on your page — no full-page redirect.
  </Card>
</CardGroup>

***

## How the Two Axes Fit Together

Any payment type can run on either mode:

| Payment type    | Checkout Flow (PayCollect) | Seamless Flow (PayDirect) |
| --------------- | :------------------------: | :-----------------------: |
| Regular Payment |              ✓             |             ✓             |
| Recurring (SI)  |              ✓             |             ✓             |
| Auth & Capture  |              ✓             |             ✓             |
| CodeDrop        |              ✓             |             ✓             |

<Note>
  New here? Start with [Choose Your Integration](/docs/integration/overview) for a high-level comparison of No-Code vs API, then come back to pick a mode and payment types.
</Note>

***

Questions? Contact [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).


# Choose Your Integration
Source: https://payglocal.in/docs/integration/overview

Choose between No-Code and API integration based on how your business collects payments.

PayGlocal supports three ways to accept payments. The right one depends on how you want to collect money — and, if it's on your own site, who handles the card details.

<CardGroup>
  <Card title="No-Code" icon="sparkles" href="/docs/no-code/overview">
    **Collect without writing code.** Create Payment Links, Invoice Links, and Payment Buttons from the GCC dashboard. PayGlocal hosts the checkout.
  </Card>

  <Card title="Checkout Flow (PayCollect)" icon="window" href="/docs/merchant/paycollect/overview">
    **API — PayGlocal-hosted checkout.** Your backend sends a request; PayGlocal collects the card details on a secure hosted page. No PCI DSS certification needed.
  </Card>

  <Card title="Seamless Flow (PayDirect)" icon="code" href="/docs/merchant/paydirect/overview">
    **API — your own checkout.** You collect card details in your own UI and send them to PayGlocal. Requires PCI DSS certification.
  </Card>
</CardGroup>

<Note>
  **Checkout Flow (PayCollect)** and **Seamless Flow (PayDirect)** are the two modes of API integration. See the [API Integration overview](/docs/integration/api-overview) to compare them in detail.
</Note>

***

## Still Deciding?

Follow the path that matches how you want to accept payments:

```mermaid theme={null}
graph TD
    A[How do you want to accept payments?] --> B[From the GCC dashboard only]
    A --> C[From your own website or app]
    B --> D[No-Code Integration<br/>Payment Link / Invoice / Button]
    C --> E{PCI DSS certified?}
    E -->|No| F[Checkout Flow PayCollect<br/>PayGlocal hosts the payment page]
    E -->|Yes| G[Seamless Flow PayDirect<br/>You collect card data on your own page]
```

<Note>
  No-Code and API integration aren't mutually exclusive. Many merchants use Payment Links for quick ad-hoc collections while their checkout runs on Checkout Flow (PayCollect) or Seamless Flow (PayDirect).
</Note>

***

## Next Steps

<CardGroup>
  <Card title="No-Code Integration" icon="sparkles" href="/docs/no-code/overview">
    Payment Link, Invoice Link, and Payment Button — all dashboard-driven.
  </Card>

  <Card title="API Integration" icon="code" href="/docs/integration/api-overview">
    Compare Checkout Flow (PayCollect) and Seamless Flow (PayDirect), then build payments into your own product.
  </Card>
</CardGroup>

***

Questions? Contact [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).


# Introduction
Source: https://payglocal.in/docs/introduction

PayGlocal — RBI-licensed payment gateway for global businesses. Secure, scalable, and trusted by thousands of merchants worldwide.

PayGlocal is a focused platform for global payments — built for high approval rates, fraud reduction, customized flows, recurring payments, and dynamic currency conversion.

<CardGroup>
  <Card title="Start Onboarding" icon="rocket" href="/docs/onboarding/overview">
    Onboard your sub-merchants programmatically — requirements, the onboarding API flow, and authentication.
  </Card>

  <Card title="Start Integration" icon="code" href="/docs/integration/overview">
    Find the integration that's right for you — No-Code or API — and start building.
  </Card>
</CardGroup>

***

## Platform overview

<CardGroup>
  <Card title="A focused platform for global payments" icon="globe">
    PayGlocal streamlines global payments with advanced technology for high approval rates, fraud reduction, customized flows, recurring payments, and dynamic currency conversion.
  </Card>

  <Card title="All-in-one acceptance" icon="credit-card">
    Receive payments in any mode on one platform — **130+ currencies**, **20+ payment methods**, **10+ integration options**, and major debit and credit cards.
  </Card>

  <Card title="Client-first approach" icon="headset">
    Tailored payment solutions with a customizable payment flow and round-the-clock support via phone, email, and a dedicated account manager.
  </Card>

  <Card title="Secure by design" icon="shield-check">
    Zero-trust architecture with end-to-end encryption, multi-factor authentication, and custom data control — so every payment stays protected.
  </Card>

  <Card title="Multi-currency account" icon="building-columns">
    Collect foreign funds through a multi-currency account — operate globally like a local entity, with hassle-free setup, quick settlement, and lower conversion costs.
  </Card>

  <Card title="Local payment methods" icon="earth-americas">
    Offer locally prominent payment methods in your target markets — familiar methods, increased trust, and less checkout friction.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="130+" icon="coins">
    **Currencies** supported
  </Card>

  <Card title="20+" icon="wallet">
    **Local payment** methods
  </Card>

  <Card title="10+" icon="puzzle-piece">
    **Integration** options
  </Card>
</CardGroup>

***

## Built for global commerce

PayGlocal is built with the vision to foster global commerce. You are at the forefront of growth beyond borders — and we are built to back you.

<CardGroup>
  <Card title="Payments platform for cross border" icon="globe">
    Built to securely process international payments with high approval rates while minimizing fraud.
  </Card>

  <Card title="Easy setup and integration" icon="bolt" href="/docs/integration/overview">
    Access payment methods and features through a single, one-time integration.
  </Card>

  <Card title="Competitive pricing" icon="tags">
    Pay for what you process, as you go — everything you need at competitive pricing.
  </Card>

  <Card title="Dedicated support" icon="headset">
    Dedicated account manager plus 24×7 email, phone, and ticket support from payment experts.
  </Card>

  <Card title="Customisations on demand" icon="sliders">
    Have a specific payment requirement? At scale, complexity grows — PayGlocal can build bespoke solutions tailored to your business.
  </Card>
</CardGroup>

### Easily manage global payments

<CardGroup>
  <Card title="Accept" icon="hand-holding-dollar">
    Take payments across cards, wallets, and local methods.
  </Card>

  <Card title="Collect" icon="money-bill-transfer">
    Receive cross-border funds in multiple currencies.
  </Card>

  <Card title="Automate" icon="rotate" href="/docs/merchant/recurring-payment">
    Standing Instructions and recurring billing flows.
  </Card>

  <Card title="Manage" icon="chart-line" href="/docs/getting-started/payglocal-dashboards">
    Track status, settlements, and risk from a single dashboard.
  </Card>
</CardGroup>

Track and manage all your payments through one dashboard — transaction status, daily settlement reports, and risk analysis on your payments.

***

## Built for developers

<CardGroup>
  <Card title="RBI Licensed" icon="building-columns">
    Online payment aggregator license from the Reserve Bank of India.
  </Card>

  <Card title="Flexible Compliance" icon="shield-check">
    Support for both PCI DSS-compliant and non-PCI DSS merchants.
  </Card>

  <Card title="Advanced Fraud Detection" icon="shield">
    Dedicated risk engine to identify fraudulent transactions.
  </Card>

  <Card title="Easy Integration" icon="code" href="/docs/integration/overview">
    SDKs for major platforms, plus Checkout Flow (PayCollect) and Seamless Flow (PayDirect) API flows.
  </Card>
</CardGroup>

Questions? Contact [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).


# Fetching Account Details
Source: https://payglocal.in/docs/mca/account-fetch

How to retrieve the global virtual accounts assigned to an activated merchant.

## Overview

Once a merchant completes onboarding and is activated by PayGlocal, one or more **global virtual accounts** are provisioned for them — one per enabled currency. These accounts are what the merchant shares with their overseas customers to receive payments.

As a partner, you call the Account Fetch API to retrieve these details and surface them in your own dashboard or send them to the merchant.

***

## When to Call This

* After you receive confirmation that a merchant's onboarding status is `APPROVED`
* When a merchant requests to view or refresh their account details
* When you need to display account details in your partner dashboard

<Note>
  Calling this endpoint for a merchant whose onboarding is still in progress will return HTTP 401. Only call it once you have confirmed the merchant is activated.
</Note>

***

## What You Get Back

The response is organised by **collection label** (a label PayGlocal assigns during provisioning, for example `general`) and within each label by **currency code**.

For each account you receive:

| Detail                            | What to show the merchant                                              |
| --------------------------------- | ---------------------------------------------------------------------- |
| `accountNumber`                   | The account number to share with their customer                        |
| `accountHolderName`               | The name their customer should address the transfer to                 |
| `bankName` + `bankAddress`        | The bank receiving the funds                                           |
| `routingCode` + `routingCodeType` | The routing number (ABA for USD, BSB for AUD, Sort Code for GBP, etc.) |
| `currency`                        | The currency of this account                                           |

***

## Example: Displaying USD Account Details

If your merchant has a USD collection account, the account block looks like this:

```json theme={null}
{
  "accountNumber": "XXXXXXXXXX4490",
  "accountHolderName": "Acme Exports",
  "bankName": "Citibank, N.A.",
  "bankAddress": "One Penns Way, New Castle, DE 19720",
  "bankCountry": "US",
  "currency": "USD",
  "routingCode": "31100209",
  "routingCodeType": "ABA Number"
}
```

Your merchant would share this with a US-based customer who can then initiate a domestic ACH or wire transfer.

***

## Routing Codes by Currency

Different currencies use different routing code types. Here is what to expect:

| Currency | Routing Code Type | Example   |
| -------- | ----------------- | --------- |
| USD      | ABA Number        | 031100209 |
| GBP      | Sort Code         | 20-00-00  |
| EUR      | BIC / IBAN        | CITIUS33  |
| AUD      | BSB Number        | 252000    |

***

## What to Do with This Data

1. **Store it** — Cache the account details in your system so you can display them without making a live API call every time.
2. **Display it** — Show the merchant their collection accounts per currency in a readable format.
3. **Refresh on demand** — Allow merchants to refresh in case details change (account provisioning updates).

For the full API spec and interactive playground, see [Fetch Virtual Accounts](/docs/api-reference/mca/account-fetch).


# Uploading Transaction Documents
Source: https://payglocal.in/docs/mca/document-upload

How to attach a supporting invoice to an MCA transaction using the presigned upload flow.

## Overview

When funds arrive in a merchant's virtual account, PayGlocal requires a supporting document — typically an invoice — before initiating compliance. You provide this document via a **single-call presigned URL flow**:

1. **Host** the file yourself and generate a presigned URL for it from your own storage (e.g. an S3 bucket you control)
2. **Call** PayGlocal's upload endpoint with that `presignedUrl` in the request body — PayGlocal fetches the file from it and stores it for the transaction

There is no separate "get a URL, then PUT the file" round trip — the presigned URL is yours to begin with, and PayGlocal is the one downloading from it, not the one issuing it.

***

## When to Trigger This

Call the upload endpoint as soon as you receive an `MCA_FUND_RECEIVED` webhook with status `DOCUMENT_PENDING`. Extract the `gid` from the webhook payload — that is what you pass in the path.

```
MCA_FUND_RECEIVED webhook received
         │
         ▼
  Extract gid from payload
         │
         ▼
  Host the file at a presigned URL you control
         │
         ▼
  POST /gcc/v1/ffms/external/transaction/{gid}/upload-presigned
  with presignedUrl in the request body
         │
         ▼
  PayGlocal fetches the file from presignedUrl and stores it
         │
         ▼
  Upload complete — PayGlocal initiates compliance check
```

***

## Request the Upload

Make a single POST request with the transaction, invoice, and presigned URL details. The required fields are:

| Field          | What to send                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------- |
| `gid`          | From the path — the transaction ID from the webhook                                          |
| `amount`       | The transaction amount from the webhook                                                      |
| `currency`     | The transaction currency from the webhook                                                    |
| `merchantId`   | The merchant's ID — must match the transaction                                               |
| `invoiceType`  | The type of document you are uploading (e.g. `INVOICE`)                                      |
| `paymentType`  | The payment type (e.g. `CARD`)                                                               |
| `fileName`     | The file name including extension (e.g. `invoice_001.pdf`)                                   |
| `presignedUrl` | A URL you control that PayGlocal can fetch the file from — must be reachable at request time |

Optional fields like `invoiceNumber`, `customerFullName`, `purposeCode`, and `fxRate` provide additional context that helps PayGlocal's compliance processing.

**Example request body:**

```json theme={null}
{
  "amount": "1000.00",
  "currency": "USD",
  "invoiceType": "INVOICE",
  "paymentType": "CARD",
  "merchantId": "<merchant_id>",
  "invoiceNumber": "INV-2026-00321",
  "customerFullName": "John Doe",
  "purposeCode": "P0102",
  "fxRate": "83.12",
  "fileName": "invoice_INV-2026-00321.pdf",
  "presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
```

A `200 OK` response confirms PayGlocal has fetched and stored the file.

<Warning>
  The `presignedUrl` you provide must be reachable at the time of the request — PayGlocal fetches it immediately during this call. It is not stored or reused afterward, so don't send a URL that expires before the request completes.
</Warning>

***

## File Naming Tips

* Use the invoice number in the filename so it is traceable (e.g. `invoice_INV-2026-00321.pdf`)
* Keep the file extension to 10 characters or fewer
* Supported formats: PDF is recommended for invoices

***

## After the Upload

Once the file is fetched, PayGlocal will:

1. Validate the invoice against the transaction
2. Send you a `TXN_SENT_FOR_SETTLEMENT` webhook when processing begins
3. Send you a `TXN_SETTLED` webhook when funds hit the merchant's account
4. Send you a `FIRC_RECEIVED` webhook with the compliance certificate

You do not need to call any further API — just listen for the subsequent webhooks.

For the full API spec and interactive playground, see [Get Upload Presigned URL](/docs/api-reference/mca/document-upload).


# MCA Overview
Source: https://payglocal.in/docs/mca/overview

What Merchant Collection Accounts are, how they work, and how to integrate them.

## What is MCA?

**Merchant Collection Accounts (MCA)** are virtual bank accounts provisioned by PayGlocal that allow merchants to receive international payments in multiple currencies — USD, EUR, GBP, AUD, and more — directly into accounts held in those countries.

Instead of asking foreign customers to make a cross-border wire, your merchant shares a local bank account in the customer's currency and country. The customer pays locally; PayGlocal handles settlement back to the merchant in INR.

***

## How It Works

<CardGroup>
  <Card title="1. Global Accounts Assigned" icon="bank">
    After a merchant is fully onboarded and activated, PayGlocal assigns virtual bank accounts across enabled currencies. Each account has local routing details (ABA, BSB, Sort Code, etc.).
  </Card>

  <Card title="2. Merchant Shares Details" icon="share-nodes">
    The merchant shares the relevant account details with their overseas buyer. The buyer sends a local bank transfer — no SWIFT fees, no cross-border friction.
  </Card>

  <Card title="3. PayGlocal Settles" icon="arrows-rotate">
    PayGlocal receives the funds, collects a supporting invoice from the partner, and settles the INR equivalent to the merchant's bank account.
  </Card>
</CardGroup>

***

## Integration Overview

As a partner, your integration involves three surfaces:

| Surface             | What you do                                                                                                                    |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Account Fetch**   | After merchant activation, call the API to retrieve their assigned virtual account details and surface them in your dashboard. |
| **Webhooks**        | Listen for lifecycle events — fund receipt, settlement, FIRC — to keep your system in sync without polling.                    |
| **Document Upload** | When funds arrive, upload the supporting invoice so PayGlocal can process settlement.                                          |

***

## Transaction Lifecycle

```
Customer sends funds to virtual account
              │
              ▼
    DOCUMENT_PENDING ──── partner uploads invoice
              │
              ▼
    SENT_FOR_SETTLEMENT
              │
              ▼
           SETTLED
              │
              ▼
       FIRC_RECEIVED
```

| Status                | What it means                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `DOCUMENT_PENDING`    | Funds received into the virtual account; PayGlocal is waiting for the supporting invoice |
| `SENT_FOR_SETTLEMENT` | Invoice accepted; transaction is being processed for settlement                          |
| `SETTLED`             | Funds settled to the merchant's INR bank account                                         |
| `FIRC_RECEIVED`       | Foreign Inward Remittance Certificate generated and available                            |

***

## Guides

<CardGroup>
  <Card title="Fetch Account Details" icon="bank" href="/docs/mca/account-fetch">
    Retrieve the virtual account details assigned to an onboarded merchant.
  </Card>

  <Card title="Webhook Events" icon="bell" href="/docs/mca/webhooks">
    Handle lifecycle notifications for fund receipt, settlement, and FIRC.
  </Card>

  <Card title="Upload Documents" icon="file-arrow-up" href="/docs/mca/document-upload">
    Generate a presigned URL and upload the supporting invoice.
  </Card>
</CardGroup>


# MCA Webhook Events
Source: https://payglocal.in/docs/mca/webhooks

Understanding and handling PayGlocal's MCA lifecycle notifications.

## Overview

PayGlocal sends webhook notifications to your configured endpoint at every stage of an MCA transaction. You do not need to poll for status — PayGlocal calls you.

Each notification is a **HTTP POST** with a JSON body. Your endpoint must respond with **HTTP 200** immediately. Process any business logic after acknowledging.

***

## Setting Up Your Webhook Endpoint

Your webhook endpoint is a publicly accessible POST endpoint on your backend. Share the URL with your PayGlocal account manager to have it configured against your partner account.

**Rules for a valid webhook URL:**

* Must be HTTPS
* Must be publicly reachable (no localhost or private IPs)
* Must accept HTTP POST requests
* Must return HTTP 200 within a few seconds of receiving the request

***

## The Eight Events

### `VIRTUAL_ACCOUNT_PROVISIONED`

Fired once a merchant's virtual accounts have been successfully provisioned across all applicable acquirers. This is your signal that the merchant is ready to start receiving funds.

```json theme={null}
{
  "onboarding_id": "ONB123456",
  "onboarding_status": "ACCEPTED",
  "event_timestamp": "1752480000000",
  "status": "VIRTUAL_ACCOUNT_PROVISIONED",
  "merchant_id": "M1000234",
  "ucic_id": "UCIC7890",
  "virtual_account_provisioned": "true"
}
```

**What to do:** Mark the merchant as ready in your system. This event does not include individual account/currency details — the merchant's virtual account details are available through your fetch account details API.

<Note>
  This event fires only once per merchant, after virtual account provisioning is fully complete across all acquirers. It must be explicitly enabled for your partner account before you'll receive it.
</Note>

***

### `MERCHANT_MCA_ACCEPTED`

Fired when a merchant's onboarding application is accepted for the **MCA** product specifically.

```json theme={null}
{
  "onboarding_status": "ACCEPTED",
  "onboarding_id": "a2230a44bdb2693a",
  "merchant_id": "madhavsh317311",
  "event_timestamp": "1785233067777",
  "status": "MERCHANT_MCA_ACCEPTED"
}
```

***

### `MERCHANT_CARDS_ACCEPTED`

Fired when a merchant's onboarding application is accepted for the **Cards** product specifically.

```json theme={null}
{
  "onboarding_status": "ACCEPTED",
  "onboarding_id": "a2230a44bdb2693a",
  "merchant_id": "madhavsh317311",
  "event_timestamp": "1785233149987",
  "status": "MERCHANT_CARDS_ACCEPTED"
}
```

<Note>
  A merchant onboarding for multiple products fires one `MERCHANT_<PRODUCT>_ACCEPTED` event per product as each is approved. Track product-level acceptance independently rather than assuming one event means the merchant is fully accepted across the board.
</Note>

***

### `MCA_FUND_RECEIVED`

Fired when funds land in the merchant's virtual account. This is your trigger to upload the supporting invoice.

```json theme={null}
{
  "gid": "glm123456789",
  "paymentRail": "ACH",
  "merchantId": "<merchant_id>",
  "amount": "1000.00",
  "currency": "USD",
  "sender_name": "John D***",
  "sender_address": "New York, USA",
  "sender_country": "US",
  "sender_accountno": "XXXX1234",
  "timestamp": "2024-10-21T10:15:30Z",
  "status": "DOCUMENT_PENDING"
}
```

**What to do:** Extract the `gid` and trigger your invoice upload flow. See [Uploading Documents](/docs/mca/document-upload).

***

### `TXN_SENT_FOR_SETTLEMENT`

Fired when PayGlocal has accepted the invoice and submitted the transaction for settlement. No action required from your side.

```json theme={null}
{
  "gid": "glm123456789",
  "merchantId": "<merchant_id>",
  "amount": "1000.00",
  "currency": "USD",
  "sender_name": "John D***",
  "sender_country": "US",
  "timestamp": "2024-10-21T10:15:30Z",
  "status": "SENT_FOR_SETTLEMENT"
}
```

**What to do:** Update the transaction status in your system. Notify the merchant that settlement is in progress.

***

### `TXN_SETTLED`

Fired when the funds have been settled to the merchant's INR bank account.

```json theme={null}
{
  "gid": "glm123456789",
  "ucicId": "<ucic_id>",
  "merchantId": "<merchant_id>",
  "transaction_amount": "1000.00",
  "transaction_currency": "USD",
  "settled_at": "2024-10-23",
  "settlement_amount": "998.00",
  "settlement_currency": "USD",
  "gstAmount": "17.96",
  "fxRate": "91.39",
  "fxRateBookedAt": "2024-10-22T14:30:00Z",
  "status": "SETTLED"
}
```

**What to do:** Mark the transaction as complete. Notify the merchant with settlement details including the FX rate applied, when that rate was booked, the GST amount, and the final settled amount.

***

### `FIRC_RECEIVED`

Fired when the Foreign Inward Remittance Certificate (FIRC) document is ready. The FIRC is the official proof of receipt for cross-border payments and is required for compliance.

```json theme={null}
{
  "gid": "glm123456789",
  "merchantId": "<merchant_id>",
  "transaction_amount": "1000.00",
  "transaction_currency": "USD",
  "settled_at": "2024-10-23",
  "settlement_amount": "998.00",
  "settlement_currency": "USD",
  "fircUrl": "https://<bucket>.s3.amazonaws.com/FIRC.pdf",
  "status": "FIRC_RECEIVED"
}
```

**What to do:** Download the FIRC immediately from `fircUrl` and store it in your own system. The URL expires after 10 minutes.

<Warning>
  The `fircUrl` is valid for **10 minutes only**. Download and store the document as soon as you receive this webhook — do not save the URL and fetch later.
</Warning>

***

### `INVOICE_GENERATED`

Fired when PayGlocal generates the monthly GST invoice for a reseller's MCA business. This is a **reseller-level** notification (keyed by `resellerMid`), separate from the merchant-level lifecycle events above.

```json theme={null}
{
  "resellerMid": "<reseller_mid>",
  "servicePeriod": "202606",
  "MONTH": "May",
  "product": "MCA",
  "YEAR": "2026",
  "merchantId": "<merchant_id>",
  "invoiceUrl": "https://<bucket>.s3.amazonaws.com/backfill/reseller_details/invoice.pdf?X-Amz-Expires=900&X-Amz-Signature=<signature>",
  "invoiceNumber": "1274376",
  "type": "MERCHANT_INVOICE_RESELLER_WEBHOOK",
  "notificationEvent": "INVOICE_GENERATED",
  "status": "INVOICE_GENERATED"
}
```

**What to do:** Download the GST invoice immediately from `invoiceUrl` and store it in your own system, keyed by `resellerMid` and `servicePeriod`.

<Warning>
  The `invoiceUrl` is a presigned URL valid for **15 minutes only** (`X-Amz-Expires=900`). Download and store the document as soon as you receive this webhook — do not save the URL and fetch later.
</Warning>

***

## Event Summary

| Event                               | Status                        | Your Action                             |
| ----------------------------------- | ----------------------------- | --------------------------------------- |
| `VIRTUAL_ACCOUNT_PROVISIONED`       | `VIRTUAL_ACCOUNT_PROVISIONED` | Mark merchant as ready                  |
| `MERCHANT_MCA_ACCEPTED`             | `MERCHANT_MCA_ACCEPTED`       | Mark MCA as approved for the merchant   |
| `MERCHANT_CARDS_ACCEPTED`           | `MERCHANT_CARDS_ACCEPTED`     | Mark Cards as approved for the merchant |
| `MCA_FUND_RECEIVED`                 | `DOCUMENT_PENDING`            | Upload the invoice                      |
| `TXN_SENT_FOR_SETTLEMENT`           | `SENT_FOR_SETTLEMENT`         | Update status, notify merchant          |
| `TXN_SETTLED`                       | `SETTLED`                     | Mark complete, share settlement details |
| `FIRC_RECEIVED`                     | `FIRC_RECEIVED`               | Download and store the FIRC document    |
| `MERCHANT_INVOICE_RESELLER_WEBHOOK` | `INVOICE_GENERATED`           | Download and store the GST invoice      |

***

## Handling Best Practices

**Respond first, process second**

Return HTTP 200 immediately before running any business logic. Long-running operations in the webhook handler will cause timeouts.

```
→ Receive POST
→ Return HTTP 200
→ Queue or async: process event
```

**Make your handler idempotent**

The same event may be retried if your endpoint did not acknowledge in time. Use the `gid` as an idempotency key — check whether you have already processed that event before acting on it.

**Verify the merchantId**

Always confirm that the `merchantId` in the payload belongs to your partner account before acting on the event.

**Store the FIRC immediately**

Do not cache the `fircUrl` — download the file to your own storage (S3, GCS, etc.) the moment you receive the `FIRC_RECEIVED` event.

**Store the GST invoice immediately**

Do not cache the `invoiceUrl` — download the file to your own storage the moment you receive the `INVOICE_GENERATED` event. It expires in 15 minutes.


# Auth & Capture
Source: https://payglocal.in/docs/merchant/auth-capture-guide

Two-step payment flow: authorize funds first, capture when ready to fulfill.

## What is Auth & Capture?

**Auth & Capture** is a two-step payment flow where the payment is first **authorized** (funds are held/reserved) and later **captured** (money is actually charged).

This payment flow is useful for businesses where the final confirmation, product shipment, or service fulfillment happens **after** the customer places the order.

<CardGroup>
  <Card title="Step 1: Authorization" icon="shield-check">
    **Verify & Hold**

    * Verify the payment method
    * Check sufficient funds
    * Temporarily block the amount
    * **Do NOT deduct money yet**
  </Card>

  <Card title="Step 2: Capture" icon="circle-check">
    **Confirm & Charge**

    * Merchant confirms transaction
    * Actual deduction happens
    * Money gets settled to merchant
    * After shipment/fulfillment
  </Card>
</CardGroup>

***

## How It Works

Instead of charging the customer immediately:

1. **First:** Merchant authorizes the payment
2. **Then:** Bank temporarily blocks the amount on the customer's card/account
3. **Next:** Once product/service is confirmed, merchant captures the payment
4. **Finally:** Funds are transferred successfully

<Note>
  At the authorization stage, the customer sees the amount as "held" or "pending". The merchant has assurance that funds are available, but no actual settlement happens yet.
</Note>

***

## Why Businesses Use Auth & Capture

This flow is ideal when:

* Delivery confirmation is required
* Inventory may change
* Final amount may vary
* Services are fulfilled later
* Merchant wants fraud protection
* Merchant wants payment assurance before fulfillment

***

## Real-World Examples

<Card title="Airlines" icon="plane">
  **When a customer books a flight:**

  1. Payment is authorized first
  2. Airline confirms seat allocation
  3. Payment is captured after ticket confirmation

  **Useful because:**

  * Fare availability may change
  * Seat confirmation may fail
  * Final booking validation needed
</Card>

***

## Key Benefits

### Payment Assurance

Merchant knows customer has sufficient funds before fulfillment.

### Better Customer Experience

Customer is charged **only when** order/service is confirmed.

### Reduced Refunds

Since money is not immediately captured, failed orders may simply release authorization instead of processing refunds.

### Flexible Fulfillment

Merchant can:

* Capture full amount
* Capture partial amount
* Reverse authorization
* Perform multiple captures (if supported)

***

## Auth & Capture Lifecycle

### Step 1 — Payment Authorization

Customer initiates payment.

**Merchant sends:**

* Amount
* Card/payment details
* Authorization request

**Bank:**

* Validates payment method
* Checks available balance
* Places hold on funds

**Result:** Payment status becomes `AUTHORIZED`

***

### Step 2 — Hold Period

Funds remain reserved for a limited duration.

**Typical authorization validity:**

* 5 to 7 days
* Sometimes up to 30 days depending on card network

**During this period, merchant can:**

* Capture payment (full or partial)
* Reverse authorization
* Wait for fulfillment confirmation

<Warning>
  If authorization expires before capture, the hold is automatically released and the transaction becomes invalid.
</Warning>

***

### Step 3 — Capture

Merchant captures the payment after confirmation.

**Examples of when to capture:**

* Product shipped
* Hotel checkout completed
* Flight ticket confirmed
* Service delivered

**Result:** Payment status becomes `CAPTURED`

Actual settlement starts here — funds are transferred to merchant's account.

***

### Step 4 — Reversal (Optional)

If order/service is cancelled, merchant can reverse authorization.

**What happens:**

* Held amount gets released back to customer
* No actual charge occurs
* Payment status becomes `REVERSED` or `CANCELLED`

**When to use reversal:**

* Order cancelled by customer
* Stock unavailable
* Booking failed
* Fraud detected

<Note>
  Auth reversal avoids unnecessary refunds since the money was never actually charged.
</Note>

***

## Partial Capture

Merchant may capture **only part** of the authorized amount.

**Example:**

* Authorized amount: ₹10,000
* Captured amount: ₹7,000
* Remaining ₹3,000 gets released automatically or reversed manually

**Useful for:**

* Partial shipment (some items out of stock)
* Variable billing (final amount differs)
* Inventory shortage
* Split fulfillment

<CardGroup>
  <Card title="Full Capture" icon="circle-check">
    Capture the complete authorized amount when order is fully fulfilled.
  </Card>

  <Card title="Partial Capture" icon="scissors">
    Capture only what you need — remainder is released automatically.
  </Card>
</CardGroup>

***

## Auth Reversal Explained

**Auth reversal** releases held funds **without charging** the customer.

### When to Use Reversal

| Scenario                           | Action                    |
| ---------------------------------- | ------------------------- |
| Order cancelled before fulfillment | Reverse authorization     |
| Stock unavailable                  | Reverse authorization     |
| Booking failed                     | Reverse authorization     |
| Fraud detected                     | Reverse authorization     |
| Payment already captured           | Use refund (not reversal) |

<Warning>
  Auth reversal only works on `AUTHORIZED` transactions. Once captured, you must use the standard refund flow.
</Warning>

***

## Summary: Authorization vs Capture vs Reversal

| Action              | What It Does                           | When To Use                    | Status After |
| ------------------- | -------------------------------------- | ------------------------------ | ------------ |
| **Authorization**   | Holds funds on customer's card         | At order placement             | `AUTHORIZED` |
| **Full Capture**    | Charges the full authorized amount     | After complete fulfillment     | `CAPTURED`   |
| **Partial Capture** | Charges only part of authorized amount | Partial shipment/fulfillment   | `CAPTURED`   |
| **Reversal**        | Releases hold without charging         | Order cancelled before capture | `REVERSED`   |

***

## Next Steps

Now that you understand how Auth & Capture works, learn how to implement it:

<CardGroup>
  <Card title="Auth Payment Initiation" icon="shield-check" href="/docs/merchant/auth-capture/auth-payment-initiation">
    Start an authorization to hold funds on the customer's card.
  </Card>

  <Card title="Authorization Management" icon="shield-halved" href="/docs/merchant/auth-capture/authorization-management">
    Capture funds or release the hold after authorization.
  </Card>
</CardGroup>


# CodeDrop
Source: https://payglocal.in/docs/merchant/paycollect/codedrop

Embed PayGlocal's payment experience directly on your page — no redirect, no full-page navigation. The payment form opens as a popup and closes itself when done.

## What is CodeDrop?

With a standard PayCollect integration, clicking "Pay" redirects the customer away from your page to PayGlocal's hosted checkout. **CodeDrop removes that redirect entirely.**

Instead, the payment form opens as a **modal, drawer, or inline widget** directly on your page. When the payment is complete (or cancelled), the form closes itself automatically and your callback function receives the result — the customer never leaves your site.

<CardGroup>
  <Card title="Modal" icon="square">
    A dialog appears centered over your page. Customer's focus is locked on payment. Most common choice.
  </Card>

  <Card title="Drawer" icon="sidebar">
    Slides in from the side of the screen. Cart or order summary stays visible behind it.
  </Card>

  <Card title="Inline" icon="window">
    The payment form embeds directly within your page layout. Feels completely native to your checkout.
  </Card>
</CardGroup>

<Note>
  CodeDrop is a presentation layer on top of PayCollect — the underlying API, security, PCI rules, and supported payment methods are identical. No separate backend integration is needed.
</Note>

***

## How It Works

```
Your page          →     Your backend fetches redirectUrl from PayGlocal
     ↓
window.PGPay.launchPayment({ redirectUrl })
     ↓
CodeDrop opens (modal / drawer / inline)
Customer completes payment on PayGlocal's embedded form
     ↓
Form closes automatically
paymentCallback(data) fires with gid, status, merchantTxnId, x-gl-token
```

***

## Backend Implementation

Before CodeDrop can launch, your backend needs to call PayGlocal's Initiate Payment API and return the `redirectUrl` to your frontend.

Create an API endpoint on your server that:

1. Calls PayGlocal's `POST /gl/v1/payments/initiate/paycollect`
2. Returns the `redirectUrl` from the response to your frontend

Your frontend then passes this `redirectUrl` to `window.PGPay.launchPayment()`.

***

## Frontend Integration

### Step 1 — Get Enabled for CodeDrop

CodeDrop must be enabled for your Merchant ID by PayGlocal's operations team. Contact your account manager to request enablement. They will provide you a **`cdId`** — a unique identifier for your CodeDrop configuration.

***

### Step 2 — Add the Script Tag

Add the following script tag to your HTML `<head>` or at the end of `<body>`:

```html theme={null}
<script
  src="<codedrop script url>"
  data-display-mode="<display mode>"
  data-cd-id="<cdId>"
  defer
></script>
```

**Script URLs by environment:**

| Environment   | URL                                           |
| ------------- | --------------------------------------------- |
| UAT (Testing) | `https://codedrop.uat.payglocal.in/simple.js` |
| Production    | `https://codedrop.payglocal.in/simple.js`     |

**Display modes:**

| Value    | Behaviour                                                       |
| -------- | --------------------------------------------------------------- |
| `drawer` | Slides in from the side (default & recommended)                 |
| `modal`  | Opens as a dialog box on top of the page                        |
| `inline` | Embeds within the page (requires additional setup — see Step 3) |

Replace `<cdId>` with the ID provided by PayGlocal. For example, for a modal in UAT with cdId `123456789`:

```html theme={null}
<script
  src="https://codedrop.uat.payglocal.in/simple.js"
  data-display-mode="modal"
  data-cd-id="123456789"
  defer
></script>
```

***

### Step 3 — Add Payment Container *(Inline mode only)*

If you chose `inline` display mode, add a container `<div>` at the exact location in your page where the payment form should appear:

```html theme={null}
<div
  id="PayGlocal_payments"
  data-width="400px"
></div>
```

* `id="PayGlocal_payments"` is **mandatory** and must be exactly this value
* `data-width` is optional — accepted range is `350px` to `450px`, default is `400px`

Skip this step for `modal` and `drawer` modes.

***

### Step 4 — Launch the Payment Form

When the customer clicks your payment button, call your backend to get the `redirectUrl`, then pass it to CodeDrop:

```javascript theme={null}
window.PGPay.launchPayment({
  redirectUrl: '<redirectUrl>'
});
```

A complete example using `axios`:

```javascript theme={null}
function displayPaymentPage() {
  axios
    .get("<merchantPayNowApi>")
    .then((res) => {
      window.PGPay.launchPayment({
        redirectUrl: res.data.redirectUrl
      });
    });
}
```

Replace `<merchantPayNowApi>` with your own backend endpoint that returns the `redirectUrl`.

***

### Step 5 — Handle the Payment Callback

After the payment completes, is cancelled, or is abandoned, CodeDrop invokes your callback function with the payment result. Pass the callback as the second argument to `launchPayment()`:

```javascript theme={null}
function paymentCallback(data) {
  // handle payment status based on data parameter
}

window.PGPay.launchPayment(
  { redirectUrl: res.data.redirectUrl },
  paymentCallback
);
```

The `data` object passed to your callback contains:

```javascript theme={null}
const data = {
  gid: "gl_o-62693b07-1059-45f3-b353-d65cbfa2bee1",  // identify transaction in GCC
  status: "SENT_FOR_CAPTURE",                          // current payment status
  merchantTxnId: "23AEE8CB6B62EE2AF07",               // your transaction reference
  "x-gl-token": "eyJpc3N1ZWQtYnkiOiJHbG9..."          // use to fetch full status from PayGlocal
};
```

***

### Step 6 — Custom Pay Now Action *(Inline mode only)*

If you have hidden the default PayNow button inside the inline payment form, expose your own button and wire it to:

```javascript theme={null}
function payNowClicked(event) {
  // perform custom action
  window.PGPay.handlePayNow(event);
}
```

Add this to the `onclick` of your own PayNow button. The `event` parameter is the click event and is mandatory.

***

### Step 7 — Pass Updated Billing & Shipping Details *(Inline mode only)*

If your billing and shipping forms are on the same page as the inline payment widget, the customer might update their address while interacting with the payment form. To keep the payment form in sync, call:

```javascript theme={null}
function updateData() {
  const merchantPayload = {};
  window.PGPay.modifyPayment(merchantPayload);
}
```

The `merchantPayload` format:

```javascript theme={null}
const merchantPayload = {
  paymentData: {
    billingData: {
      firstName: "John",
      lastName: "Doe",
      emailId: "something@gmail.com",
      addressStreet1: "Block-2B",
      addressStreet2: "Hamilton street",
      addressCity: "Bangalore",
      addressState: "Karnataka",
      addressCountry: "IN",
      addressPostalCode: "123456"
    }
  },
  riskData: {
    shippingData: {
      firstName: "John",
      lastName: "Doe",
      emailId: "something@gmail.com",
      addressStreet1: "street 1",
      addressStreet2: "street 2",
      addressCity: "Bangalore",
      addressState: "Karnataka",
      addressCountry: "IN",
      addressPostalCode: "123456"
    }
  }
};
```

You can send `billingData`, `shippingData`, or both. Any field you omit is left unchanged. Data entered directly by the customer in the payment form always takes highest priority.

***

## For the Full Technical Reference with Code Examples

<Card title="CodeDrop API Reference" icon="book" href="/docs/api-reference/codedrop">
  Complete integration reference with annotated code examples for every step.
</Card>


# Checkout Flow (PayCollect)
Source: https://payglocal.in/docs/merchant/paycollect/overview

Hosted payment solution with zero PCI compliance burden — PayGlocal collects card details on a secure hosted page.

## Checkout Flow (PayCollect)

Empowering non-PCI DSS certified merchants with secure, flexible, and seamless payment methods. PayGlocal handles card details, ensuring compliance and simplicity.

<CardGroup>
  <Card title="Zero PCI burden" icon="shield-check">
    PayGlocal collects and stores card data on a PCI-compliant hosted page.
  </Card>

  <Card title="5-minute integration" icon="bolt">
    Send a minimal payload; PayGlocal handles the rest.
  </Card>

  <Card title="Built-in 3DS" icon="lock-keyhole">
    3D Secure authentication included automatically.
  </Card>

  <Card title="Alt payment methods" icon="globe">
    iDeal, Sofort, Trustly, giropay, wallets, BNPL — for international flows.
  </Card>
</CardGroup>

***

## Payment Patterns

Choose the pattern that fits your transaction model.

<CardGroup>
  <Card title="JWT Authentication" icon="key" href="/docs/merchant/paycollect/jwt-authentication">
    Standard one-time payments with secure token-based auth. Supports all PayCollect APIs.
  </Card>

  <Card title="Standing Instructions" icon="rotate" href="/docs/merchant/standing-instructions">
    Automate recurring payments. Flexible FIXED / VARIABLE mandates with JWE/JWS encryption.
  </Card>

  <Card title="Auth & Capture" icon="shield-check" href="/docs/merchant/auth-capture">
    Flexible authorization and capture. Prevents premature charges — ideal for delayed fulfillment.
  </Card>
</CardGroup>

***

## Endpoint

```
POST /gl/v1/payments/initiate/paycollect
```

### Minimum Required Payload

```json theme={null}
{
  "merchantTxnId": "23AEE8CB6B62EE2AF07",
  "paymentData": {
    "totalAmount": "89",
    "txnCurrency": "INR"
  },
  "merchantCallbackURL": "https://www.yoursite.com/callback"
}
```

### Response

```json theme={null}
{
  "gid": "gl-13bbd3c4-9817-4786-96c6-12fa6191f118",
  "status": "CREATED",
  "data": {
    "redirectUrl": "https://api.prod.payglocal.in/gl/v1/payments/redirect?x-gl-token=...",
    "statusUrl":   "https://api.prod.payglocal.in/gl/v1/payments/status?x-gl-token=..."
  }
}
```

Redirect the customer to `data.redirectUrl`. PayGlocal completes the payment and POSTs back to your `merchantCallbackURL`.

<Note>
  For Global Alternative Payment Methods (iDeal, Sofort, Trustly, giropay, EPS, wallets, BNPL), `shippingData.addressCountry` and `customerData.emailId` are required in the payload.
</Note>

<Warning>
  PayCollect does **not** support setting up Standing Instructions for cards through the hosted page. To create a recurring mandate, use the [Standing Instructions](/docs/merchant/standing-instructions) flow.
</Warning>

***

## Embedding Options

Don't want a full-page redirect? Embed the PayCollect form directly:

<Card title="CodeDrop — Modal, Drawer, or Inline" icon="square-code" href="/docs/merchant/paycollect/codedrop">
  Three display modes for the hosted form — Modal dialog, side Drawer, or fully Inline.
</Card>


# Seamless Flow (PayDirect)
Source: https://payglocal.in/docs/merchant/paydirect/overview

Direct payment integration for PCI DSS certified merchants — full control over card collection and checkout UI.

## Direct Payment Solution

Process payments directly with full control. For PCI DSS certified merchants who collect card data on their own interface.

<CardGroup>
  <Card title="25+" icon="credit-card">
    **Payment methods**
  </Card>

  <Card title="100ms" icon="bolt">
    **Avg response time**
  </Card>

  <Card title="300M+" icon="chart-line">
    **Daily API requests**
  </Card>

  <Card title="99.9%" icon="circle-check">
    **Success rate**
  </Card>
</CardGroup>

<Warning>
  PayDirect requires **PCI DSS Level 1 certification**. You collect, transmit, and handle card data on your own systems and are responsible for PCI compliance.
</Warning>

***

## Seamless Flow (PayDirect)

**PayDirect** is a direct payment integration solution for PCI DSS compliant merchants who collect card data on their own interface. You maintain full control over the payment flow and customer experience, while PayGlocal handles secure processing through our robust payment gateway. This approach is ideal for enterprises requiring maximum customization and direct card data handling.

### Payment Flow

```
Merchant Interface  →  Card Data Collection  →  JWT Encryption  →  PayGlocal Gateway  →  Payment Processed
```

***

## Key Benefits

<CardGroup>
  <Card title="Full UI Customization" icon="palette">
    Complete control over payment interface and user experience.
  </Card>

  <Card title="Direct Processing" icon="bolt">
    No redirects — payments processed on your domain.
  </Card>

  <Card title="Advanced API Access" icon="code">
    Comprehensive APIs with full customization capability.
  </Card>

  <Card title="Real-time Analytics" icon="chart-line">
    Instant access to transaction data and insights.
  </Card>
</CardGroup>

***

## Payment Patterns

<CardGroup>
  <Card title="JWT Authentication" icon="key" href="/docs/merchant/paydirect/jwt-authentication">
    Standard one-time payments with direct card data and JWT auth.
  </Card>

  <Card title="Standing Instructions" icon="rotate" href="/docs/merchant/standing-instructions">
    Recurring payments with pre-authorized mandates.
  </Card>

  <Card title="Auth & Capture" icon="shield-check" href="/docs/merchant/auth-capture">
    Two-step flow — authorize first, capture when ready.
  </Card>
</CardGroup>

***

## Endpoint

```
POST /gl/v1/payments/initiate
```

### Minimum Required Payload

```json theme={null}
{
  "merchantTxnId": "23AEE8CB6B62EE2AF07",
  "paymentData": {
    "totalAmount": "89",
    "txnCurrency": "INR",
    "cardData": {
      "number": "5132552222223470",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "securityCode": "123"
    }
  },
  "merchantCallbackURL": "https://www.yoursite.com/callback"
}
```

<Note>
  For international card transactions, `riskData` is **required**. For RuPay cards, `ipAddress`, `httpAccept`, and `httpUserAgent` are mandatory.
</Note>

***

## Ideal For

<CardGroup>
  <Card title="Enterprise Businesses" icon="building">
    Large corporations requiring customized payment experiences and direct control.
  </Card>

  <Card title="Financial Institutions" icon="building-columns">
    Banks and fintech requiring specialized integrations and compliance.
  </Card>

  <Card title="Retail Chains" icon="store">
    Multi-location businesses needing unified payment processing.
  </Card>

  <Card title="Tech-First Companies" icon="code">
    Development teams wanting full API control and custom implementations.
  </Card>

  <Card title="Payment Aggregators" icon="network-wired">
    Platforms providing payment services to multiple merchants.
  </Card>

  <Card title="Healthcare Providers" icon="hospital">
    Medical institutions requiring HIPAA-compliant payment processing.
  </Card>
</CardGroup>

***

## Ready to Get Started?

<CardGroup>
  <Card title="View Payment Methods" icon="layer-group" href="/docs/merchant/paydirect/jwt-authentication">
    Explore JWT Authentication, Standing Instructions, and Auth & Capture.
  </Card>

  <Card title="API Reference" icon="book" href="/docs/api-reference/payments-v2/paydirect/gpi">
    Full endpoint reference and interactive playground.
  </Card>
</CardGroup>


# Payment Flow
Source: https://payglocal.in/docs/merchant/payment-flow

Understand how a payment request is built — from raw payload to encrypted, signed API call.

Before making any API call, it helps to understand **what actually happens** when you send a payment request to PayGlocal. This page explains the full flow — no code, just the logic.

***

## Why Can't I Send a Raw Payload?

PayGlocal never accepts a plain JSON request. Every request must be:

* **Encrypted** — so no one in transit can read your payment data
* **Signed** — so PayGlocal can verify the request genuinely came from you

These two steps produce two tokens — a **JWE** and a **JWS** — which travel together in every API call.

***

## Flow: From Payload to Request

```
Your Payment Data (plain JSON)
         │
         ▼
  [ generateJWE ]
  Encrypts your payload using PayGlocal's public key
  Returns → JWE Token (encrypted, unreadable string)
         │
         ▼
  [ generateJWS ]
  Hashes the JWE and signs it using your private key
  Returns → JWS Token (signed proof string)
         │
         ▼
  [ POST Request ]
  Body    →  JWE Token
  Header  →  x-gl-token-external: JWS Token
         │
         ▼
  PayGlocal receives the request
  → Verifies JWS (confirms it came from you)
  → Decrypts JWE (reads your payload)
  → Processes the payment
```

***

## What Each Function Does

### `generateJWE` — Encrypt the Payload

**Takes in:** Your payment payload + PayGlocal's public key + your Merchant ID + Public Key ID

**What it does:** Converts your JSON payload into an encrypted token. Once encrypted, the data is completely unreadable — only PayGlocal can decrypt it using their private key.

**Returns:** A JWE token — a compact encrypted string that becomes the **body of your API request**.

***

### `generateJWS` — Sign the JWE

**Takes in:** The JWE token + your private key + your Merchant ID + Private Key ID

**What it does:** Takes the JWE token, hashes it with SHA-256, and signs that hash using your private key. This signature is proof that the request was sent by you and has not been modified in transit.

**Returns:** A JWS token — a compact signed string that goes into the **`x-gl-token-external` header of your API request**.

***

### `generateJWEAndJWS` — The Single Entry Point

**Takes in:** Your payload + all five credentials (public key, private key, Merchant ID, Public Key ID, Private Key ID)

**What it does:** Calls `generateJWE` first, then passes its output to `generateJWS`. Validates all your credentials before running.

**Returns:** Both tokens together — `{ jweToken, jwsToken }`.

This is the **only function you need to call**. Everything else happens internally.

***

## Assembling the Request

Once you have both tokens, your request is:

```
POST  https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect

Header:  Content-Type         →  text/plain
Header:  x-gl-token-external  →  JWS Token

Body:  JWE Token
```

That's it. PayGlocal handles the rest.

***

## Why Two Tokens?

| Token   | Sent as        | Key used                   | What it protects                                          |
| ------- | -------------- | -------------------------- | --------------------------------------------------------- |
| **JWE** | Request body   | PayGlocal's **public** key | Confidentiality — data cannot be read in transit          |
| **JWS** | Request header | **Your** private key       | Authenticity — PayGlocal confirms the request is from you |

One without the other is incomplete. JWE alone means PayGlocal can read the data, but cannot trust it came from you. JWS alone means PayGlocal can verify the sender, but cannot read the payload.

***

## Credentials You Need

| Credential               | Purpose                                                     |
| ------------------------ | ----------------------------------------------------------- |
| **PayGlocal Public Key** | Used by `generateJWE` to encrypt the payload                |
| **Your Private Key**     | Used by `generateJWS` to sign the JWE                       |
| **Merchant ID**          | Embedded in both token headers to identify you              |
| **Public Key ID**        | Tells PayGlocal which key was used to encrypt               |
| **Private Key ID**       | Tells PayGlocal which key to use for signature verification |

<Note>
  See [Key Management](/docs/getting-started/dashboard-and-key-management) for step-by-step instructions on fetching all five credentials.
</Note>


# Payment Response Handling
Source: https://payglocal.in/docs/merchant/payment-response-handling

Understanding how PayGlocal sends payment responses to your system.

## Payment Callback Flow

After a user completes a payment, PayGlocal sends the transaction response to the callback URL provided by the merchant during payment creation. This allows the merchant system to receive the payment result, process the transaction status, and redirect or display the appropriate success or failure page to the user.

The response is sent as an **HTTP POST request** containing the payment details in encoded format.

***

## Overview

<CardGroup>
  <Card title="HTTP POST Request" icon="arrow-up-from-bracket">
    PayGlocal sends payment results via HTTP POST to your configured `merchantCallbackURL`.
  </Card>

  <Card title="Encoded Token" icon="lock">
    Payment data is sent as `x-gl-token` — a base64url encoded JWT containing the full transaction result.
  </Card>

  <Card title="Decode & Process" icon="code">
    Extract, decode, and parse the token to access payment details and redirect the user accordingly.
  </Card>
</CardGroup>

***

## What Happens Internally — Step by Step

<Steps>
  <Step title="Payment Request Created">
    You send a payment initiation request to PayGlocal along with the `merchantCallbackURL` — a POST endpoint on your backend that you create yourself.
  </Step>

  <Step title="Customer Completes Payment">
    The customer completes (or abandons) the payment on the PayGlocal payment page.
  </Step>

  <Step title="PayGlocal Processes the Transaction">
    Once the transaction is processed, PayGlocal prepares the payment response containing the transaction status, amount, currency, transaction ID, payment method, and card or network details.
  </Step>

  <Step title="PayGlocal Sends Callback">
    PayGlocal fetches the `merchantCallbackURL` from the original request and sends an HTTP POST to that endpoint. The callback contains the encoded transaction response in the `x-gl-token` field.
  </Step>

  <Step title="Your Backend Receives and Processes">
    Your backend receives the callback at the configured endpoint. You decode the token, read the payment status, and decide what to show the user — a success page, failure page, or any other experience you choose.
  </Step>
</Steps>

***

## Implementation

### 1. Include `merchantCallbackURL` in Your Payment Request

Add `merchantCallbackURL` to your payment payload — this is where PayGlocal will POST the result after the transaction completes.

```json theme={null}
{
  "merchantTxnId": "23AEE8CB6B62EE2AF07",
  "paymentData": {
    "totalAmount": "15",
    "txnCurrency": "USD"
  },
  "merchantCallbackURL": "https://your-website-domain.com/payments/merchantCallback"
}
```

<Note>
  Must be a publicly accessible **HTTPS POST endpoint**. PayGlocal cannot reach localhost or private IPs.
</Note>

***

### 2. Receive, Decode, and Handle the Callback

Once the payment completes, PayGlocal POSTs to your callback URL with a single field in the body — `x-gl-token`. This token is a **JWT** (three dot-separated parts: Header · Payload · Signature). The payment data lives in the **Payload** section, encoded in base64url.

Here is what the raw token looks like when it arrives. It has **three dot-separated parts**, each shown in a different color:

<div>
  <span>eyJpc3N1ZWQtYnkiOiJHbG9jYWwiLCJpcy1kaWdlc3RlZCI6ImZhbHNlIiwiYWxnIjoiUlMyNTYiLCJraWQiOiJrSWQtRU5oN3Y1bDdTNE56YjhScCJ9</span><span>.</span><span>eyJ4LWdsLW9yZGVySWQiOiJnbF9vLTlmY2QzYTY3YTUwNDUxODczdzNyMFBwWDIiLCJhbXBsaWZpZXItbWlkIjpudWxsLCJpYXQiOiIxNzc4OTY0MzQ4MzQ5IiwieC1nbC1lbmMiOiJ0cnVlIiwieC1nbC1naWQiOiJnbF85ZmNkM2E2N2E1MDQ1MTg3NzE2dzNyMFBwWDIiLCJ4LWdsLW1lcmNoYW50SWQiOiJ0ZXN0bmV3Z2NjMjYifQ</span><span>.</span><span>K6Xiu7zld57xkYZ1JkfvyzQouiWW1shKjftVbDbGBp5h-E-1YazfZqBM7wk3ubH3HxtpMUa4FClconTQCvlhSkNmWmU\_D8IU8tMpToUU8nHs7ZEOa\_GXT5GBvvkC\_\_ixg\_a6MQHbSu4CWPXZsZWUXnJHNj1IcS06gxGdvj8-84F-Rj8WiMkSgCI23Ac\_N4bqywzebbm3bSjY-aPzVa9s79y\_XbKbguxIaHAZdoRSE2rQp4i4J9JQedXjYtaCP\_Bqv5W9fHP42rytBTsX7ZnTxW9oUYU999VP6rYc2wMfTVWzpa2rm40Ps53Z9PvDCQmzcJsQdm6HWw894pUuCF1xCQ</span>
</div>

**What each part means:**

| Part       | Color     | Name          | What it contains                                                                                                                     |
| ---------- | --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Part 1** | 🔴 Red    | **Header**    | Token metadata — signing algorithm (`RS256`) and the Key ID (`kid`) used to sign                                                     |
| **Part 2** | 🔵 Blue   | **Payload**   | **Your payment data** — transaction status, amount, `gid`, `merchantId`, and all other response fields. This is the part you decode. |
| **Part 3** | 🟣 Purple | **Signature** | Cryptographic signature — proves the token was issued by PayGlocal and has not been tampered with                                    |

<Note>
  The **middle part (Payload)** is where all the transaction data lives. Split the token on `.` and take index `[1]` to get this section, then base64url-decode it to read the payment result.
</Note>

Your callback endpoint decodes it in the following sequence:

**Extract the token** from the incoming request body:

```javascript theme={null}
const glToken = req.body['x-gl-token'];
```

**Split on `.`** — take the middle section (index 1), which is the Payload:

```javascript theme={null}
const base64UrlPayload = glToken.split('.')[1];
```

**Convert base64url → base64** by swapping `-` with `+` and `_` with `/`:

```javascript theme={null}
const base64Payload = base64UrlPayload.replace(/-/g, '+').replace(/_/g, '/');
```

**Decode to a UTF-8 string:**

```javascript theme={null}
const decodedString = Buffer.from(base64Payload, 'base64').toString('utf-8');
```

**Parse into a usable object:**

```javascript theme={null}
const paymentData = JSON.parse(decodedString);
```

After parsing, `paymentData` looks like this:

```json theme={null}
{
  "country": "UNITED KINGDOM",
  "amount": "48",
  "gid": "PGL_7F8A9B3C2D1E4F5A",
  "merchantId": "MERCH_9X8Y7Z6W5V4U3T",
  "cardType": "PREPAID",
  "merchantTxnId": "TXN_4K5L6M7N8O9P0Q",
  "paymentMethod": "CARD",
  "currency": "USD",
  "cardBrand": "VISA",
  "status": "SENT_FOR_CAPTURE"
}
```

***

### 3. Act on the Status

There is exactly **one success status**: `SENT_FOR_CAPTURE`. Every other status means the transaction did not complete.

Once decoded, PayGlocal hands control entirely back to you — you decide what the customer sees next. There is no fixed redirect or page; you build and control the experience.

**If `status === "SENT_FOR_CAPTURE"` → Payment successful:**
Mark the order as paid in your database, send a confirmation email, and redirect the customer to your success page.

**If `status` is anything else → Payment failed:**
Mark the order as failed and redirect the customer to your failure or retry page.

***

## Payment Status Reference

| Status               | Meaning                                   | Result    |
| -------------------- | ----------------------------------------- | --------- |
| `SENT_FOR_CAPTURE`   | Payment successful — funds captured       | ✅ Success |
| `AUTHORIZED`         | Funds held, capture pending               | ⏳ Pending |
| `ISSUER_DECLINE`     | Card declined by the issuing bank         | ❌ Failure |
| `GENERAL_DECLINE`    | Declined by PayGlocal risk engine         | ❌ Failure |
| `CUSTOMER_CANCELLED` | Customer cancelled on the payment page    | ❌ Failure |
| `ABANDONED`          | Customer left without completing payment  | ❌ Failure |
| `REQUEST_ERROR`      | Field-level error in the original request | ❌ Failure |

***

## Best Practices

<CardGroup>
  <Card title="Always Decode Before Trusting" icon="shield-check">
    Never act on the raw POST body. Always decode `x-gl-token` and read `status` before updating your database or redirecting the user.
  </Card>

  <Card title="Use gid as Source of Truth" icon="magnifying-glass">
    If the callback is delayed or missed, use the [Status Check](/docs/merchant/regular-payment/transaction-management) API with `gid` to fetch the current status.
  </Card>

  <Card title="Prevent Duplicate Processing" icon="clone">
    Check `merchantTxnId` before updating order status — callbacks can occasionally arrive more than once.
  </Card>

  <Card title="Log Every Callback" icon="file-lines">
    Store the raw token and decoded payload for debugging, auditing, and reconciliation.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Webhooks" icon="bell" href="/docs/merchant/webhooks">
    Server-to-server notifications that arrive independently of the browser callback.
  </Card>

  <Card title="Status Check" icon="magnifying-glass" href="/docs/merchant/regular-payment/transaction-management">
    Verify any payment status server-side at any time using the gid.
  </Card>

  <Card title="Node.js Implementation" icon="node-js" href="/docs/api-reference/callback-handling">
    Complete Node.js code for your `merchantCallbackURL` endpoint — ready to adapt and use.
  </Card>
</CardGroup>


# Recurring Payment (SI)
Source: https://payglocal.in/docs/merchant/recurring-payment

Standing Instructions — mandate creation, recurring deductions, and full mandate lifecycle management.

## What is a Recurring Payment?

**Recurring payment** is a payment model where customers authorize merchants to charge them automatically for future payments **without requiring authentication every time**.

Instead of asking the customer to manually complete payment during every billing cycle, the customer **approves a mandate once**, and future charges happen automatically based on the configured recurring setup.

<CardGroup>
  <Card title="One-Time Setup" icon="user-check">
    Customer authorizes recurring charges just once during the first payment.
  </Card>

  <Card title="Automatic Billing" icon="clock-rotate-left">
    Future payments happen automatically without customer intervention.
  </Card>
</CardGroup>

### Common Use Cases

Recurring payments are commonly used for:

* **OTT platforms** (Netflix, Prime Video)
* **EMI payments** (loan installments)
* **Utility bills** (electricity, water, gas)
* **SaaS products** (cloud software subscriptions)
* **Membership plans** (gym, clubs)
* **Insurance premiums** (monthly/quarterly)
* **Auto-recharge systems** (prepaid mobile, wallets)

***

## How Recurring Payments Work

<Steps>
  <Step title="Customer Creates Mandate">
    Customer performs the **first payment** and approves recurring authorization.

    **This creates:**

    * A recurring mandate
    * A stored authorization
    * A unique **Mandate ID**
  </Step>

  <Step title="Merchant Stores Mandate Information">
    Merchant securely stores:

    * **Mandate ID**
    * Customer reference
    * Payment method details
    * Frequency configuration

    This Mandate ID is used for **all future recurring operations**.
  </Step>

  <Step title="Future Charges Happen">
    Based on the SI type:

    * **Fixed SI:** PayGlocal automatically debits customer
    * **Variable SI:** Merchant manually triggers charges when required
  </Step>
</Steps>

***

## SI Models Supported by PayGlocal

PayGlocal supports **two recurring payment models:**

<CardGroup>
  <Card title="Fixed SI — Auto Debit" icon="robot">
    **Fixed recurring payment** with predefined amount and schedule.

    **Examples:**

    * ₹999 every month
    * ₹499 every week
    * ₹1,200 every quarter

    **Characteristics:**

    * Amount remains **fixed**
    * Frequency remains **fixed**
    * PayGlocal **automatically deducts** payment based on schedule

    **Best for:**

    * OTT subscriptions
    * Gym memberships
    * SaaS subscriptions
    * Fixed EMI plans
  </Card>

  <Card title="Variable SI — On-Demand" icon="hand-pointer">
    **Variable recurring payment** where amount may change for every deduction.

    **Examples:**

    * Electricity bills
    * Water bills
    * Usage-based billing
    * Metered SaaS pricing

    **Characteristics:**

    * Merchant sets a **maximum allowed limit** during setup
    * Deduction does **NOT happen automatically**
    * Merchant must **trigger payment** whenever required

    **Best for:**

    * Utility billing
    * Consumption-based pricing
    * Dynamic invoices
    * Top-ups
  </Card>
</CardGroup>

***

## Fixed SI — Auto Debit

### How It Works

During mandate creation:

1. Merchant defines **fixed recurring amount**
2. Merchant defines **billing frequency**
3. Customer authorizes recurring deductions

**Example:** Customer approves:

* ₹999
* Every month
* Automatically deducted

**Once approved:** PayGlocal automatically charges customer based on configured schedule.

### Auto Debit Frequencies

Supported recurring schedules may include:

| Frequency   | Example                |
| ----------- | ---------------------- |
| `DAILY`     | Charged every day      |
| `WEEKLY`    | Charged every week     |
| `MONTHLY`   | Charged every month    |
| `QUARTERLY` | Charged every 3 months |
| `YEARLY`    | Charged every year     |

### Fixed SI Flow

```
Customer Creates Mandate
        ↓
Merchant Receives Mandate ID
        ↓
PayGlocal Schedules Recurring Charges
        ↓
Automatic Debit Happens
        ↓
Merchant Receives Payment Status Webhook
```

<Note>
  **Merchant does not need to trigger deductions manually** — PayGlocal handles everything automatically based on the configured frequency.
</Note>

***

## Variable SI — On-Demand Deduction

### How It Works

During mandate creation:

1. Merchant defines **maximum allowed amount**
2. Customer approves charging permission up to that limit

<Warning>
  **Important:** Payment is **NOT auto-debited** on schedule. Merchant must **manually initiate** every deduction request by the help of On Demand API.
</Warning>

### When to Use On-Demand Deduction

For charging customer cards in Variable SI, merchant triggers deduction request manually. This is useful when:

* Final amount **changes**
* **Usage-based** billing exists
* Invoice amount **varies**

**Example Use Cases:**

* Electricity bill generated monthly
* Cloud usage billing
* Water bill deduction
* Wallet recharge
* Subscription add-ons
* Consumption-based SaaS pricing

### Variable SI Flow

```
Customer Creates Variable Mandate
        ↓
Merchant Receives Mandate ID
        ↓
Merchant Generates Invoice
        ↓
Merchant Triggers On-Demand Charge
        ↓
Payment Gets Processed
        ↓
Merchant Receives Payment Status
```

<Note>
  **Amount must always remain within approved mandate limit.** If you need to charge more than the maximum limit, you must create a new mandate.
</Note>

***

## Mandate Management

Once a mandate is created, merchants can **manage its lifecycle**.

### Mandate Operations

Merchants can:

* **Pause** recurring deductions temporarily
* **Resume** paused mandates
* **Cancel** mandates permanently
* **Check** mandate status
* **View** deduction history

This gives merchants **complete control** over recurring billing operations.

<CardGroup>
  <Card title="Pause Mandate" icon="circle-pause">
    Temporarily suspend recurring charges without cancelling the mandate.
  </Card>

  <Card title="Activate Mandate" icon="play">
    Resume a paused mandate and restart recurring billing.
  </Card>

  <Card title="Cancel Mandate" icon="ban">
    Permanently revoke a mandate — cannot be undone.
  </Card>
</CardGroup>

***

## Fixed vs Variable — Quick Comparison

| Feature        | Fixed SI (Auto Debit)            | Variable SI (On-Demand)              |
| -------------- | -------------------------------- | ------------------------------------ |
| **Amount**     | Fixed amount every cycle         | Variable amount (within max limit)   |
| **Frequency**  | Predefined schedule              | Merchant-triggered                   |
| **Automation** | Fully automatic                  | Manual trigger required              |
| **Deduction**  | PayGlocal handles automatically  | Merchant initiates each charge       |
| **Best For**   | Subscriptions, EMIs, memberships | Utility bills, usage-based billing   |
| **Example**    | ₹999 every month for Netflix     | Electricity bill — varies each month |

***

## Next Steps

Now that you understand how Recurring Payments work, learn how to implement them:

<CardGroup>
  <Card title="SI Payment Initiation" icon="paper-plane" href="/docs/merchant/recurring-payment/si-payment-initiation">
    Create a recurring mandate during the first payment.
  </Card>

  <Card title="SI Transaction Management" icon="hand-pointer" href="/docs/merchant/recurring-payment/si-transaction-management">
    Trigger on-demand deductions for Variable SI mandates.
  </Card>

  <Card title="SI Mandate Management" icon="list-check" href="/docs/merchant/recurring-payment/si-mandate-management">
    Pause, activate, or cancel mandates after creation.
  </Card>
</CardGroup>


# Regular Payment
Source: https://payglocal.in/docs/merchant/regular-payment

One-time, instant payments for products and services — simple checkout experience.

## What is a Regular Payment?

**Regular Payment** is a simple **one-time payment transaction** where the customer makes a payment instantly for a product or service.

The customer:

1. Visits a website or app
2. Selects a product or service
3. Completes payment
4. Receives confirmation

**The transaction ends once the payment is completed.**

This is the most common type of online payment flow used across e-commerce, retail, travel, food delivery, ticket booking, and digital services.

***

## Understanding One-Time Payments

A **one-time payment** means:

<CardGroup>
  <Card title="Single Purchase" icon="shopping-bag">
    Customer pays only for the **current purchase** — not for future transactions.
  </Card>

  <Card title="Instant Settlement" icon="bolt">
    Payment is completed **instantly** — money is captured right away.
  </Card>

  <Card title="No Continuation" icon="ban">
    Transaction does **not continue automatically** in the future.
  </Card>
</CardGroup>

**Every new purchase creates a completely new payment transaction.**

### Example

```
Customer purchases shoes online
        ↓
Completes payment
        ↓
Order gets confirmed
        ↓
Transaction ends
```

**If the customer buys again tomorrow:**\
A **new payment process** starts again from scratch.

***

## Simple Payment Experience

Regular payment is designed to provide:

* **Quick checkout** — fast payment completion
* **Instant confirmation** — immediate order confirmation
* **Seamless experience** — smooth payment flow
* **Easy order completion** — hassle-free checkout

### The Goal

| For Customer                     | For Merchant                         |
| -------------------------------- | ------------------------------------ |
| Complete payment quickly         | Receive instant payment confirmation |
| Get immediate order confirmation | Begin order processing immediately   |
| Simple, intuitive checkout       | Reduce cart abandonment              |

***

## Where Regular Payments Are Commonly Used

<CardGroup>
  <Card title="E-commerce Websites" icon="cart-shopping">
    **Customers purchase:**

    * Clothes
    * Electronics
    * Accessories
    * Groceries

    Payment is completed **instantly during checkout**.
  </Card>

  <Card title="Food Delivery Platforms" icon="utensils">
    **Customers:**

    * Place food orders
    * Make immediate payment
    * Receive order confirmation

    Payment is **for that order only**.
  </Card>
</CardGroup>

***

## How Regular Payment Works

<Steps>
  <Step title="Customer Initiates Payment">
    Customer adds items to cart and proceeds to checkout.
  </Step>

  <Step title="Payment Details Entered">
    Customer enters:

    * Card details, OR
    * UPI ID, OR
    * Net banking credentials, OR
    * Wallet credentials
  </Step>

  <Step title="Payment Processing">
    Payment gateway validates and processes the transaction instantly.
  </Step>

  <Step title="Instant Confirmation">
    Customer receives:

    * Payment success notification
    * Order confirmation
    * Receipt/invoice

    Merchant receives:

    * Payment confirmation
    * Order details
    * Settlement notification
  </Step>
</Steps>

***

## Regular Payment vs Other Payment Types

| Feature               | Regular Payment             | Recurring Payment (SI)      | Auth & Capture              |
| --------------------- | --------------------------- | --------------------------- | --------------------------- |
| **Payment Frequency** | One-time only               | Recurring/automatic         | One-time                    |
| **Capture Timing**    | Immediate                   | Scheduled or triggered      | Delayed (after auth)        |
| **Use Case**          | E-commerce, bills, bookings | Subscriptions, EMIs         | Hotels, flights, pre-orders |
| **Future Charges**    | None                        | Automatic or manual         | None (unless re-authorized) |
| **Customer Action**   | Pays each time              | Approves once               | Pays once, charged later    |
| **Complexity**        | Simple                      | Requires mandate management | Requires capture/reversal   |

***

<Note>
  **Regular payments are final and immediate** — once payment is completed, the transaction is done. If a customer needs a refund, merchant must initiate a separate refund process.
</Note>

***

## Next Steps

Now that you understand how Regular Payments work, learn how to implement them:

<CardGroup>
  <Card title="Payment Initiation" icon="paper-plane" href="/docs/merchant/regular-payment/payment-initiation">
    Start a one-time regular payment transaction.
  </Card>

  <Card title="Transaction Management" icon="magnifying-glass" href="/docs/merchant/regular-payment/transaction-management">
    Check payment status and process refunds.
  </Card>
</CardGroup>


# SDKs & Libraries
Source: https://payglocal.in/docs/merchant/sdks

Production-ready PayGlocal SDKs in 4 languages — identical functionality with language-specific optimizations.

## SDKs & Libraries

Production-ready SDKs for your favorite programming languages. Start integrating in minutes with comprehensive features and excellent documentation.

<Note>
  All SDKs provide **identical functionality** with language-specific optimizations.
</Note>

***

## Available SDKs

<CardGroup>
  <Card title="Node.js" icon="node-js">
    For JavaScript / TypeScript backends. Promise-based API with full TypeScript types.

    Built-in JWE/JWS encryption, request signing, and status helpers.
  </Card>

  <Card title="Python" icon="python">
    For Python services and scripts. Sync and async support.

    Built-in JWE/JWS encryption, key management helpers, and webhook validators.
  </Card>

  <Card title="Java" icon="java">
    For JVM-based services. Maven and Gradle support.

    Built-in JWE/JWS encryption, request signing, and Spring-friendly configurations.
  </Card>

  <Card title="Bash / cURL" icon="terminal">
    For shell scripts and direct API testing. Reference scripts in our sample repo.

    Includes openssl-based encryption + signing helpers.
  </Card>
</CardGroup>

<Note>
  SDK source code and language-specific quickstarts are distributed via the PayGlocal sample-client GitHub repository. Contact your PayGlocal representative or [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in) for repository access.
</Note>

***

## What All SDKs Provide

| Capability               | Description                                                    |
| ------------------------ | -------------------------------------------------------------- |
| **JWE encryption**       | Encrypts request payloads using PayGlocal's public certificate |
| **JWS signing**          | Signs every request with your private key                      |
| **Header construction**  | Adds `x-gl-token-external`, `x-gl-merchantid`, `x-gl-kid`      |
| **Endpoint routing**     | UAT vs Production via single config flag                       |
| **Response decoding**    | Decodes `x-gl-token` callbacks and verifies signatures         |
| **Status helpers**       | Wraps GET Status, Refund, Capture, Reversal, SI APIs           |
| **Webhook verification** | Validates incoming webhook signatures                          |

***

## Ready to Get Started?

<CardGroup>
  <Card title="View Documentation" icon="book" href="/docs/merchant/paycollect/overview">
    Browse the integration guides to learn how PayGlocal APIs work end-to-end.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference/payments-v2/paycollect/overview">
    Field-by-field endpoint reference with an interactive playground.
  </Card>
</CardGroup>


# Webhooks
Source: https://payglocal.in/docs/merchant/webhooks

Real-time event notifications for your application.

## Overview

Webhook notifications are sent to the webhook URL shared by the merchant. There are no additional integration steps required to implement and receive responses on webhook.

To receive webhook responses, share a webhook URL with PayGlocal on which you want to be notified about the status of your transactions.

**Example webhook URL:**

```
https://www.nameofyourwebsite.com/payment/payglocal/webhook_response
```

Once the webhook URL is configured on your MID based on your request, you will start receiving the response for all transactions as per the configuration.

<Note>
  To get your webhook URL configured, contact your PayGlocal account manager or write to [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in).
</Note>

***

## How to Form Your Webhook URL

Your webhook URL is simply a **publicly accessible POST endpoint** on your own backend server. You build it yourself — PayGlocal will call it whenever a payment event occurs.

A typical webhook URL follows this pattern:

```
https://<your-domain>/<your-path>/webhook
```

**Examples:**

```
https://api.yourstore.com/payments/payglocal/webhook
https://backend.yourapp.in/payglocal/notify
https://yourwebsite.com/payment/payglocal/webhook_response
```

**Rules for a valid webhook URL:**

* Must be **HTTPS** (HTTP is not accepted)
* Must be **publicly reachable** — localhost or private IPs will not work
* Must accept **HTTP POST** requests
* Must return **HTTP 200** to acknowledge receipt

***

## Setting Up Your Webhook Endpoint

You need to create a POST endpoint on your backend that PayGlocal can call. The endpoint receives a JSON body and must respond with `200 OK`.

Here is what your endpoint needs to do:

```
1. Listen for POST requests at your webhook URL
2. Read the JSON body from the incoming request
3. Return HTTP 200 immediately
4. Process the event (update order, notify user, etc.) after responding
```

**Pseudo-code for any backend (Node, Python, Java, etc.):**

```
POST /payglocal/webhook

  → Read request body (JSON)
  → Validate that merchantId matches your own MID
  → Respond with HTTP 200 OK immediately
  → Trigger your business logic (mark order paid, send receipt, etc.)
```

<Warning>
  Always return **HTTP 200** before running any business logic. If your server takes too long to respond, PayGlocal may consider the delivery failed and retry the webhook.
</Warning>

***

## Real-Time Event Notifications

Webhooks enable your application to receive instant notifications when events occur in PayGlocal, eliminating the need for constant polling and enabling real-time, event-driven workflows.

<CardGroup>
  <Card title="What is a Webhook?" icon="webhook">
    An automated HTTP POST request sent from PayGlocal to your server the moment a payment event occurs — no polling needed.
  </Card>

  <Card title="Why Use Webhooks?" icon="bolt">
    Instant notifications, no polling overhead, reduced server load, and event-driven workflows for faster applications.
  </Card>

  <Card title="When to Use" icon="clock">
    Payment status updates, order confirmations, transaction monitoring, and any scenario requiring immediate event-based action.
  </Card>
</CardGroup>

***

## Webhook Flow

```
1. Event Occurs
   Payment is processed on PayGlocal
         │
         ▼
2. Webhook Triggered
   PayGlocal sends a POST request to your webhook URL
         │
         ▼
3. Your Server Receives
   Your endpoint receives the webhook payload
         │
         ▼
4. Process & Respond
   Handle the event and return HTTP 200
         │
         ▼
5. Action Taken
   Update your database, fulfil the order, notify the user
```

***

## Sample Webhook Payload

When an event occurs, PayGlocal sends a POST request to your configured webhook URL. Here is an example of the payload your server receives:

```json theme={null}
{
  "country": "UNITED KINGDOM",
  "amount": "48",
  "gid": "gl_o-pYA8MLrsnfVpKp1mw",
  "merchantId": "alwyntest1",
  "merchantTxnId": "17083906765",
  "paymentMethod": "CARD",
  "currency": "USD",
  "cardBrand": "VISA",
  "status": "SENT_FOR_CAPTURE"
}
```

### Payload Field Reference

| Field           | Description                                   |
| --------------- | --------------------------------------------- |
| `country`       | Country of the card used for payment          |
| `amount`        | Transaction amount                            |
| `gid`           | PayGlocal's unique transaction identifier     |
| `merchantId`    | Your Merchant ID                              |
| `merchantTxnId` | Your unique transaction reference             |
| `paymentMethod` | Payment method used (e.g. `CARD`)             |
| `currency`      | Currency of the transaction                   |
| `cardBrand`     | Card network used (e.g. `VISA`, `MASTERCARD`) |
| `status`        | Final transaction status                      |

***

## Payment Status Values

| Status               | Meaning                                  |
| -------------------- | ---------------------------------------- |
| `SENT_FOR_CAPTURE`   | Payment successful — funds captured      |
| `AUTHORIZED`         | Payment authorized, awaiting capture     |
| `ISSUER_DECLINE`     | Card declined by the issuing bank        |
| `CUSTOMER_CANCELLED` | Customer cancelled the payment           |
| `ABANDONED`          | Customer left without completing payment |
| `GENERAL_DECLINE`    | Declined due to risk or fraud check      |

***


# Invoice Link
Source: https://payglocal.in/docs/no-code/invoice-link

Generate and share professional payment invoices with customers digitally.

## What is an Invoice Link?

**Invoice Links** allow merchants to generate and share professional payment invoices with customers digitally. These invoices can include complete transaction details such as invoice number, due date, item details, tax, discounts, billing details, merchant notes, and more.

The customer receives a secure invoice link through supported communication channels and can complete the payment directly using the hosted payment page.

## When to Use Invoice Link?

Invoice Links are especially useful for:

* **International and domestic customer payments**
* **Service-based businesses** requiring detailed billing
* **Manual order collections** with professional invoicing
* **Professional invoicing and payment tracking**
* **Businesses requiring detailed billing information**

## How to Create an Invoice Link

<Steps>
  <Step title="Navigate to Invoice Links">
    Log in to the [GCC dashboard](https://merchant.payglocal.in), click on **Payment Products** in the left sidebar, then select **Invoice Links**.

    <div>
      <img alt="Navigate to Invoice Links" />
    </div>
  </Step>

  <Step title="Click Create Invoice">
    Click the **+ Create invoice** button in the top right corner to open the invoice creation form.
  </Step>

  <Step title="Fill Payment Details">
    Start by filling in the **Payment Details** section:

    <div>
      <img alt="Create Invoice Link form with live preview" />
    </div>

    **Required Fields:**

    * **Select Currency**: Choose the invoice currency (e.g., FJD \$, INR, USD)
    * **Amount**: Enter the invoice amount

    As you fill in these details, you'll see a **live preview** of how your invoice will look on the right side of the screen, showing:

    * Trading Name
    * Invoice preview layout
    * Description & Item Code
    * PPU (Price Per Unit), QTY, TAX, AMOUNT columns
  </Step>

  <Step title="Complete Customer and Invoice Details">
    Continue filling in the remaining sections:

    <div>
      <img alt="Invoice details with live preview" />
    </div>

    **Section 2: Customer Details**

    * Customer name, email, phone, and address

    **Section 3: Invoice Details** (All fields are self-explanatory)

    * **Invoice No.**: Unique invoice identifier (e.g., 12343)
    * **Due Date**: Payment deadline (e.g., 2026/06/21)
    * **Items**: Add line items with:
      * Description (e.g., "payment for Jacket")
      * Item Code (e.g., 12345)
      * PPU (Price Per Unit, e.g., \$100)
      * Qty (Quantity, e.g., 1)
      * Tax(%) (e.g., 18)
      * Amount (automatically calculated, e.g., \$118.00)
    * **Discount Type**: Select discount type
    * **Discount**: Enter discount amount if applicable
    * **Merchant's Note**: Add notes (e.g., "Payment for jacket")
    * **Memo**: Additional information

    Click **Create Invoice Link** to generate and share the invoice. You can also **Save as Draft** to finish later.
  </Step>

  <Step title="Invoice Link Created Successfully">
    After creating the invoice, you'll see a success confirmation:

    <div>
      <img alt="Invoice Link Created Successfully" />
    </div>

    The success modal shows:

    * **Invoice Link is created successfully and shared!**
    * The generated invoice link URL that you can copy
    * **Copy Invoice Link** button to easily copy the link
    * **View all Invoice Links** option to see your invoice dashboard
  </Step>
</Steps>

## Customer Notifications

<Note>
  **Notification Channels**:

  * **International Customers**: Notifications are sent via **Email only**
  * **Domestic Customers** (India): Notifications are sent via both **Email and SMS**

  Customers receive notifications for invoice creation, payment reminders, and payment confirmation.
</Note>

## Customer Experience

When a customer receives an invoice link:

1. **Receives Invoice**: Customer gets the invoice link via email or SMS
2. **Views Invoice**: Customer opens the link and sees the professional invoice with all details
3. **Reviews Details**: Customer reviews items, amounts, tax, and billing information
4. **Makes Payment**: Customer clicks to pay and is directed to PayGlocal's secure checkout
5. **Completes Payment**: Customer completes payment using their preferred method
6. **Gets Receipt**: Customer receives payment confirmation and updated invoice

## Key Differences from Payment Link

| Feature      | Invoice Link                  | Payment Link           |
| ------------ | ----------------------------- | ---------------------- |
| **Purpose**  | Professional invoicing        | Quick payment requests |
| **Details**  | Comprehensive billing info    | Basic payment details  |
| **Items**    | Multiple line items           | Single amount          |
| **Preview**  | Live invoice preview          | No preview             |
| **Best For** | B2B, services, formal billing | B2C, quick payments    |

## Next Steps

<CardGroup>
  <Card title="Payment Link" icon="link" href="/docs/no-code/payment-link">
    For quick payment requests without detailed invoicing
  </Card>

  <Card title="Payment Button" icon="circle-play" href="/docs/no-code/payment-button">
    For dynamic amount payments on your website
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/merchant/webhooks">
    Set up real-time payment notifications
  </Card>

  <Card title="Dashboard Overview" icon="chart-line" href="/docs/getting-started/gcc-dashboard">
    Explore more dashboard features
  </Card>
</CardGroup>

## Support

* **Business and invoicing questions**: Contact your PayGlocal account manager
* **Technical issues**: Email [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in)
* **Dashboard access**: Reach out to your account manager


# How No-Code Works
Source: https://payglocal.in/docs/no-code/overview

Accept payments without writing code using PayGlocal's hosted solutions.

## What is No-Code Integration?

No-code integration allows you to start accepting payments through PayGlocal **without any API integration or technical development**. All configuration is done through the **GCC (Glocal Command Center) dashboard**, and PayGlocal handles the entire payment experience.

These solutions are ideal for:

* Businesses that need to start accepting payments quickly
* Teams without dedicated development resources
* Use cases requiring simple, one-time, or ad-hoc payments
* Sharing payment requests via email, SMS, or WhatsApp

## How No-Code Integration Works

<Steps>
  <Step title="Log in & Choose Product">
    Log in to the [GCC dashboard](https://merchant.payglocal.in) and select the product that fits your use case — **Payment Link**, **Invoice Link**, or **Payment Button**.
  </Step>

  <Step title="Configure & Generate">
    Fill in the payment amount, currency, customer details, and any optional settings. Click **Create** to generate your link or button embed code.
  </Step>

  <Step title="Share & Track">
    Share the link via email, SMS, or WhatsApp — or embed the Payment Button on your website. Monitor payment status and reconcile transactions directly from the GCC dashboard.
  </Step>
</Steps>

## Key Benefits

| Benefit                     | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| **No Development Required** | Create and share payment requests through a simple web interface |
| **Quick Setup**             | Start accepting payments in minutes, not weeks                   |
| **Secure & PCI Compliant**  | PayGlocal handles all payment security and compliance            |
| **Multiple Channels**       | Share links via email, SMS, WhatsApp, or social media            |
| **Real-time Tracking**      | Monitor all payment statuses from the GCC dashboard              |
| **Customer Notifications**  | Automatic email and SMS notifications to customers               |

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    participant Merchant
    participant GCC Dashboard
    participant Customer
    participant PayGlocal Checkout
    
    Merchant->>GCC Dashboard: Create payment link/button
    GCC Dashboard->>Merchant: Returns shareable link
    Merchant->>Customer: Share link (Email/SMS/WhatsApp)
    Customer->>PayGlocal Checkout: Click link & enter details
    PayGlocal Checkout->>Customer: Payment confirmation
    PayGlocal Checkout->>Merchant: Update status in GCC
```

## Comparison: Which Product to Use?

| Use Case                                   | Recommended Product                  |
| ------------------------------------------ | ------------------------------------ |
| Share a one-time payment request           | **Payment Link**                     |
| Send formal billing/invoice requests       | **Invoice Link**                     |
| Add payment to your website without coding | **Payment Button**                   |
| Request payment after service delivery     | **Payment Link** or **Invoice Link** |

## Next Steps

<CardGroup>
  <Card title="Create a Payment Link" icon="link" href="/docs/no-code/payment-link">
    Learn how to generate and share payment links
  </Card>

  <Card title="Invoice Link Setup" icon="file-invoice" href="/docs/no-code/invoice-link">
    Send professional invoice payment requests
  </Card>

  <Card title="Payment Button" icon="circle-play" href="/docs/no-code/payment-button">
    Embed payment buttons on your website
  </Card>
</CardGroup>

## Support

* **Product selection and business queries**: Contact your PayGlocal account manager
* **Technical issues**: Email [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in)


# Payment Button
Source: https://payglocal.in/docs/no-code/payment-button

Embed payment buttons on your website for dynamic amount payments.

## What is a Payment Button?

A **Payment Button** is a no-code solution that allows you to add a payment button to your website without any API integration. When you create a payment button in the GCC dashboard, you receive JavaScript and HTML scripts that you can simply paste into your website.

## When to Use Payment Button?

Payment Button is ideal when:

* **Dynamic Amounts**: The payment amount needs to be entered by the customer (not fixed)
* **Quick Website Integration**: You want to add payment functionality without backend development
* **No API Knowledge Required**: You can embed payments by just copying and pasting code

Unlike Payment Links (which have fixed amounts), Payment Buttons allow customers to enter the amount they want to pay.

## How to Create a Payment Button

<Steps>
  <Step title="Navigate to Payment Button">
    Log in to the [GCC dashboard](https://merchant.payglocal.in), click on **Payment Products** in the left sidebar, then select **Payment Button**.

    <div>
      <img alt="Navigate to Payment Button" />
    </div>
  </Step>

  <Step title="Click Create">
    Click the **Create** button in the top right corner to open the payment button creation form.
  </Step>

  <Step title="Configure Payment Button">
    Fill in the required details:

    <div>
      <img alt="Create Payment Button Form" />
    </div>

    **Configuration Options:**

    * **ISO3 Currency Code**: Select the currency (e.g., INR for Indian Rupee)
    * **Website URL**: Enter your website URL where the button will be embedded
    * **Customer Phone Number**: Toggle on/off to collect customer phone number
    * **Customer Email ID**: Toggle on/off to collect customer email
  </Step>

  <Step title="Submit">
    Click the **Submit** button to generate your payment button.
  </Step>

  <Step title="Copy the Scripts">
    After submission, open the button from the **Payment Button** dashboard. The **Payment Button is retrieved** panel shows your **Button ID** and **Embed Code**.

    <div>
      <img alt="Payment Button retrieved with Button ID and embed code" />
    </div>

    * Click **Copy Button ID** to save the button reference for search and status checks
    * Click **Copy Embed Code** and paste the snippet into your website HTML where customers will pay
  </Step>

  <Step title="Embed on Your Website">
    1. Copy the JavaScript script and add it to your website
    2. Copy the HTML button code and place it where you want the button
    3. Test the button to ensure it works correctly
    4. The customer will be able to enter the payment amount when they click the button
  </Step>
</Steps>

## How Payment Button Works

When a customer clicks your payment button:

1. **Button Click**: Customer clicks the payment button on your website
2. **Enter Amount**: Customer enters the payment amount (dynamic)
3. **Enter Details**: Customer fills in required information (email/phone if enabled)
4. **Payment Page**: Customer is directed to PayGlocal's secure checkout
5. **Complete Payment**: Customer completes payment using their preferred method
6. **Confirmation**: Customer receives payment confirmation and returns to your website

## Customer Experience

<img alt="Customer Experience - Coming Soon" />

*Screenshot showing customer entering amount and making payment - Coming soon*

## Managing Payment Buttons

From the Payment Button dashboard, you can:

* **View All Buttons**: See all payment buttons you've created
* **Check Status**: Monitor which buttons are active
* **View Transactions**: See all payments made through each button
* **Edit Button**: Update button configuration
* **Enable/Disable**: Activate or deactivate buttons as needed

## Button Embed Preview

<img alt="Button Embed Preview - Coming Soon" />

*Screenshot showing how the button appears on a website - Coming soon*

## Next Steps

<CardGroup>
  <Card title="Payment Link" icon="link" href="/docs/no-code/payment-link">
    For fixed amount payments with shareable links
  </Card>

  <Card title="Invoice Link" icon="file-invoice" href="/docs/no-code/invoice-link">
    For formal invoice-style payments
  </Card>

  <Card title="API Integration" icon="code" href="/docs/merchant/regular-payment">
    For full API integration and customization
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/merchant/webhooks">
    Set up real-time payment notifications
  </Card>
</CardGroup>

## Support

* **Technical integration help**: Email [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in)
* **Business inquiries**: Contact your PayGlocal account manager
* **Dashboard access**: Reach out to your account manager for credentials


# Payment Link
Source: https://payglocal.in/docs/no-code/payment-link

Create and share payment links for quick, one-time payments without API integration.

## What is a Payment Link?

A **Payment Link** is a shareable URL that lets you collect payments without any coding or API integration. Create a link in the GCC dashboard, share it with your customer via email, SMS, or WhatsApp (domestic) or email (international), and they complete payment on PayGlocal’s secure hosted checkout page.

## How to Create a Payment Link

<Steps>
  <Step title="Navigate to Payment Links">
    Log in to the [GCC dashboard](https://merchant.payglocal.in) and click on **Payment Links** in the left sidebar under **Payment Products**.

    <div>
      <img alt="Navigate to Payment Links" />
    </div>
  </Step>

  <Step title="Access Payment Links Page">
    You'll see the Payment Links management page where you can view all your existing links and create new ones.

    <div>
      <img alt="Payment Links Page" />
    </div>
  </Step>

  <Step title="Create New Link">
    Click the **+ Create payment link** button in the top right corner to open the payment link creation form.
  </Step>

  <Step title="Fill Payment Details">
    Complete the payment link form with the following information:

    <div>
      <img alt="Create Payment Link Form" />
    </div>
  </Step>

  <Step title="Generate the Link">
    After filling all required fields, click the **Create payment link** button at the bottom of the form.
  </Step>

  <Step title="Share the Link">
    Once generated, the system will:

    * Display the Payment Link ID (PLID) and shareable URL
    * Automatically send the link to the customer's email and/or mobile (based on your selection)
    * Allow you to copy the URL and share it through any other channel

    <Note>
      **Customer Notifications**:

      * **International Customers**: Notifications are sent via **Email only**
      * **Domestic Customers** (India): Notifications are sent via both **Email and SMS/WhatsApp**

      This ensures customers receive timely updates about their payment links and transaction status through the most appropriate channels based on their location.
    </Note>
  </Step>

  <Step title="Track Status">
    Monitor payment attempts, link status, transaction details, and customer information in real time from the Payment Links dashboard.
  </Step>
</Steps>

## Payment Link Status

Your payment links can have the following statuses:

| Status         | Description                                             |
| -------------- | ------------------------------------------------------- |
| **Active**     | Link is live and ready to accept payments               |
| **Transacted** | A successful payment has been completed using this link |
| **Exhausted**  | The link has reached the maximum of 10 payment attempts |
| **Expired**    | The link's expiry time has passed                       |
| **Disabled**   | You manually disabled the link from the dashboard       |

<Warning>
  Customers can attempt payment on a Payment Link up to **10 times**. After 10 failed attempts, the link status automatically changes to **Exhausted** and cannot be used anymore. Create a new payment link if needed.
</Warning>

## Customer Experience

When a customer receives and clicks on a payment link:

1. **Link Opens**: The customer is directed to PayGlocal's secure hosted checkout page
2. **Information Review**: Customer reviews the payment amount, description, and merchant details
3. **Payment Details**: Customer enters their payment method details (card, UPI, net banking, etc.)
4. **Authentication**: For card payments, the customer completes **3D Secure (3DS)** verification on the issuer’s page — an extra check to confirm the cardholder. For some domestic flows, an **OTP** may also be required. Together, these steps help prevent fraud on card transactions.
5. **Confirmation**: Customer receives instant confirmation of payment success or failure
6. **Receipt**: PayGlocal sends a payment receipt to the customer's email/mobile

## Next Steps

<CardGroup>
  <Card title="Invoice Link" icon="file-invoice" href="/docs/no-code/invoice-link">
    Learn about invoice-style payment requests
  </Card>

  <Card title="Payment Button" icon="circle-play" href="/docs/no-code/payment-button">
    Embed payment buttons on your website
  </Card>

  <Card title="Dashboard Overview" icon="chart-line" href="/docs/getting-started/gcc-dashboard">
    Learn more about the GCC dashboard
  </Card>
</CardGroup>

## Support

* **Business and product questions**: Contact your PayGlocal account manager
* **Technical issues or errors**: Email [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in)
* **Dashboard access**: Reach out to your account manager for credentials


# Onboarding Overview
Source: https://payglocal.in/docs/onboarding/overview

Onboard your sub-merchants onto PayGlocal programmatically — submit KYC, upload documents, configure products, and trigger verification via the Merchant Onboarding API.

As a partner, you onboard sub-merchants onto PayGlocal programmatically. Use the **Merchant Onboarding API** to submit KYC data, upload documents, configure products, and trigger verification — all from your own platform.

## Start here

<CardGroup>
  <Card title="Merchant Requirements" icon="clipboard-check" href="/docs/guides/merchant-requirements">
    Entity types, required documents, and dynamic pendencies.
  </Card>

  <Card title="API Flow Overview" icon="diagram-project" href="/docs/guides/api-flow-overview">
    The end-to-end onboarding sequence, step by step.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/authentication">
    API key setup and HmacSHA256 digest generation.
  </Card>

  <Card title="Partner Onboarding Events" icon="bell" href="/docs/guides/partner-onboarding-events">
    UI postMessage events and webhook notifications.
  </Card>

  <Card title="iFrame Integration" icon="window-maximize" href="/docs/guides/iframe-integration">
    Embed the Verification Suite — VKYC, DigiLocker, and T\&C — inside your dashboard.
  </Card>

  <Card title="API Reference" icon="code" href="/docs/api-reference/onboarding-overview">
    All onboarding endpoints with the interactive explorer.
  </Card>
</CardGroup>


# Bagisto
Source: https://payglocal.in/docs/plugins/bagisto

Accept payments on your Bagisto store using PayGlocal - configure and go live in minutes.

## What is Bagisto?

[Bagisto](https://bagisto.com) is an open-source Laravel-based e-commerce platform that provides a flexible and feature-rich solution for building online stores. It offers multi-channel, multi-currency, and multi-locale support out of the box.

## Bagisto with PayGlocal

Integrating PayGlocal with Bagisto enables merchants to accept cross-border payments through international debit/credit cards and other payment methods. The PayGlocal payment gateway is built into Bagisto, requiring only configuration of your merchant credentials.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Prerequisites

* An active Bagisto installation (v2.x recommended)
* Admin access to your Bagisto dashboard
* PayGlocal merchant credentials from your [PayGlocal dashboard](/docs/getting-started/dashboard-and-key-management)

## Configuration Steps

Follow these steps to enable PayGlocal payments on your Bagisto store.

### Step 1: Navigate to Configure

Log in to your Bagisto admin panel and click **Configure** from the left sidebar.

<div>
  <img alt="Bagisto admin dashboard with Configure option highlighted in sidebar" />
</div>

### Step 2: Open Payment Methods

Scroll down to the **Sales** section and click on **Payment Methods**.

<div>
  <img alt="Bagisto configuration page showing Payment Methods option highlighted under Sales section" />
</div>

### Step 3: Configure PayGlocal

In the Payment Methods page, locate **PayGlocal** and configure the following:

1. Toggle the **Status** switch to enable PayGlocal
2. Fill in your merchant credentials (see Field Reference below)
3. Click **Save Configuration** in the top-right corner

<div>
  <img alt="PayGlocal configuration form in Bagisto with Save Configuration button highlighted" />
</div>

## Field Reference

| Field                    | Description                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------------- |
| **Status**               | Enable or disable the PayGlocal payment gateway.                                                        |
| **Title**                | Display name for PayGlocal shown to customers at checkout (e.g., "PayGlocal").                          |
| **Description**          | Payment method description displayed to customers on the checkout page.                                 |
| **Logo**                 | Optional logo image for the payment method (recommended: 27px x 20px).                                  |
| **Merchant ID**          | Your Merchant ID from the PayGlocal dashboard, visible under My Account.                                |
| **Public Key ID**        | The Public Key ID provided by PayGlocal, shown in the PayGlocal dashboard.                              |
| **Private Key ID**       | The Private Key ID of your private key, shown in the PayGlocal dashboard.                               |
| **PayGlocal Public Key** | Paste the contents of the PayGlocal public key PEM file. Used to encrypt requests and verify responses. |
| **Merchant Private Key** | Paste the contents of your merchant private key PEM file. Used to sign requests.                        |
| **Accepted Currencies**  | Comma-separated currency codes enabled for your merchant account (e.g., "INR" or "USD,INR").            |
| **Sandbox**              | Toggle to send payments to the PayGlocal test environment. Disable for production.                      |

<Note>
  For details on fetching your Merchant ID, keys, and PEM files, refer to the [Key Management](/docs/getting-started/dashboard-and-key-management) section.
</Note>

## Go Live

Before accepting real customer payments:

1. Ensure **Sandbox** mode is turned **off** in the PayGlocal configuration
2. Verify all credentials are from your production PayGlocal account
3. Test a transaction on your storefront to confirm the integration is working

<Check>
  **Setup Successful** - After following the steps above, your Bagisto store is ready to accept cross-border payments from customers using PayGlocal.
</Check>


# Magento
Source: https://payglocal.in/docs/plugins/magento

Accept cross-border payments on your Magento store using PayGlocal.

## What is Magento?

Magento is an open-source eCommerce platform built for B2B and B2C businesses. The platform allows building strong and powerful storefronts, which can be customised as per the business requirements. In 2018, this open-source eCommerce platform was acquired by Adobe and is now known as Adobe Commerce.

## Magento with PayGlocal

PayGlocal integration with Magento allows merchants to accept cross-border payments securely through internet banking and debit/credit cards. The Magento extension makes it possible for merchants to easily integrate the PayGlocal Payment Gateway with their stores.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Plugin Download

Download the extension based on your Magento and PHP version. If you are not able to see the download link for your version, kindly reach out to your account manager.

| Magento Version | PHP Version | Download                                                                            |
| --------------- | ----------- | ----------------------------------------------------------------------------------- |
| 1.9             | 5.6         | [Download](mailto:support@payglocal.in?subject=Magento%20Plugin%201.9%20PHP5.6)     |
| 2.x             | 7.2 – 7.4   | [Download](mailto:support@payglocal.in?subject=Magento%20Plugin%202.x%20PHP7.2-7.4) |
| 2.0.0           | 5.6         | [Download](mailto:support@payglocal.in?subject=Magento%20Plugin%202.0.0%20PHP5.6)   |

## Plugin Installation

<Steps>
  <Step title="Copy extension files">
    Unzip the extension file and copy all the folders to the Magento root directory.
  </Step>

  <Step title="Log in to Magento admin and clear cache">
    Log in to your Magento admin panel and go to **System → Cache Management**. Select all the cache and refresh.
  </Step>

  <Step title="Open Configuration">
    Go to **System → Configuration** to configure the extension.
  </Step>
</Steps>

## Configuration

<Steps>
  <Step title="Navigate to PayGlocal settings">
    Log in to your Magento admin panel and go to **System → Configuration → Sales → Payment Methods → PayGlocal**.
  </Step>

  <Step title="Configure the extension fields">
    Fill in the fields as described in the table below.
  </Step>
</Steps>

### Field Reference

| Field                                 | Description                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Enabled**                           | Select **Yes** to enable the PayGlocal extension.                                            |
| **Title**                             | Enter a custom title for the payment method shown to customers on the frontend.              |
| **Sandbox Mode**                      | Enable or disable sandbox mode as per your requirements.                                     |
| **Merchant ID**                       | Enter your Merchant ID from the PayGlocal dashboard — visible in the top bar when logged in. |
| **Public Key**                        | Enter the PayGlocal public key from the merchant account dashboard.                          |
| **Private Key**                       | Enter the PayGlocal private key from the merchant account dashboard.                         |
| **Public PEM**                        | Upload the public PEM file downloaded from the PayGlocal merchant account dashboard.         |
| **Private PEM**                       | Upload the private PEM file downloaded from the PayGlocal merchant account dashboard.        |
| **Payment from Applicable Countries** | Select whether to allow customers from all countries or only selected countries.             |
| **Payment from Specific Countries**   | Select the specific countries allowed to use the PayGlocal payment gateway.                  |
| **Sort Order**                        | Enter the sort order for PayGlocal in case of multiple payment methods in your store.        |
| **Minimum Order Amount**              | Enter the minimum order amount required to use the PayGlocal payment gateway.                |

<Note>
  For details on fetching your Merchant ID, keys, and PEM files, refer to the [Key Management](/docs/getting-started/dashboard-and-key-management) section.
</Note>

<div>
  <img alt="Magento PayGlocal payment method configuration screen" />
</div>

<Steps>
  <Step title="Save the configuration">
    Click **Save Config** at the top-right corner of the page.
  </Step>
</Steps>

<Check>
  **Setup Successful** — Once you have followed all the steps above, your Magento store is ready to accept online payments through PayGlocal.
</Check>


# OpenCart
Source: https://payglocal.in/docs/plugins/opencart

Accept payments on your OpenCart store using PayGlocal — download, install, and configure in minutes.

## What is OpenCart?

OpenCart is an open-source and free eCommerce platform, which is easy to set up and is used by thousands of merchants around the world. The eCommerce platform features plenty of free themes and extensions that add more functionalities and features to the store.

## OpenCart with PayGlocal

Integrating PayGlocal with OpenCart enables online merchants to accept online payments through internet banking and debit/credit cards from customers. The extension makes it easier for merchants to accept payments through the PayGlocal payment gateway.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Plugin Download

Download the extension based on your OpenCart and PHP version. If you are not able to see the download link for your version, kindly reach out to your account manager.

| OpenCart Version | PHP Version | Download                                                                |
| ---------------- | ----------- | ----------------------------------------------------------------------- |
| 1.5 – 5.6        | Any         | [Download](mailto:support@payglocal.in?subject=OpenCart%20Plugin%201.5) |
| 2.3              | Any         | [Download](mailto:support@payglocal.in?subject=OpenCart%20Plugin%202.3) |
| 3.0              | Any         | [Download](mailto:support@payglocal.in?subject=OpenCart%20Plugin%203.0) |

## Plugin Installation

<Steps>
  <Step title="Open Extension Installer">
    Log in to your OpenCart admin panel and go to **Extensions → Extension Installer**.
  </Step>

  <Step title="Upload the extension">
    Upload the extension file that was downloaded.
  </Step>

  <Step title="Continue after upload">
    Click the **Continue** button once the upload is completed.
  </Step>

  <Step title="Install the PayGlocal extension">
    Navigate to **Extensions → Extensions**, select **Payments** from the drop-down, and install the PayGlocal Payment Gateway extension.
  </Step>
</Steps>

## Configuration

<Steps>
  <Step title="Navigate to PayGlocal settings">
    Log in to your OpenCart admin panel and navigate to **Extensions → Extensions**. Select **Payments** from the drop-down. Click the **Edit** option against the PayGlocal Payment Gateway to configure it.
  </Step>
</Steps>

<div>
  <img alt="OpenCart Extensions Payments list with PayGlocal highlighted" />
</div>

<Steps>
  <Step title="Configure the extension fields">
    Configure the extension as described in the table below.
  </Step>
</Steps>

### Field Reference

| Field               | Description                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------- |
| **Total**           | Enter the minimum order total required for customers to use the PayGlocal payment method.    |
| **Title**           | Enter a custom title for the payment method shown to customers on the frontend.              |
| **Sandbox Mode**    | Enable or disable sandbox mode as per your requirements.                                     |
| **Merchant ID**     | Enter your Merchant ID from the PayGlocal dashboard — visible in the top bar when logged in. |
| **Public Key**      | Enter the PayGlocal public key from the merchant account dashboard.                          |
| **Private Key**     | Enter the PayGlocal private key from the merchant account dashboard.                         |
| **Public PEM**      | Upload the public PEM file downloaded from the PayGlocal merchant account dashboard.         |
| **Private PEM**     | Upload the private PEM file downloaded from the PayGlocal merchant account dashboard.        |
| **Gateway URL**     | Enter: `https://api.uat.payglocal.in/gl/v1/payments/initiate/paycollect`                     |
| **Refund URL**      | Enter: `https://api.uat.payglocal.in/gl/v1/payments/{gid}/refund`                            |
| **Refund Required** | Select **Yes** to allow refund functionality for payments made through PayGlocal.            |
| **Order Status**    | Set the default status of orders paid using PayGlocal.                                       |
| **Geo Zone**        | Select the applicable geographical zone for allowing the payment method.                     |
| **Status**          | Enable or disable the PayGlocal payment method from here.                                    |
| **Sort Order**      | In case of multiple payment methods, enter the sort order of the PayGlocal payment gateway.  |

<Note>
  For details on fetching your Merchant ID, keys, and PEM files, refer to the [Key Management](/docs/getting-started/dashboard-and-key-management) section.
</Note>

<div>
  <img alt="OpenCart PayGlocal payment gateway configuration form" />
</div>

<Steps>
  <Step title="Save the configuration">
    Click the **Save** button at the top-right corner of the page.
  </Step>
</Steps>

<Check>
  **Setup Successful** — Once you have followed all the steps above, the PayGlocal payment gateway is successfully set up with your OpenCart store.
</Check>


# Plugin Integration
Source: https://payglocal.in/docs/plugins/overview

Accept PayGlocal on Shopify, WooCommerce, Magento, OpenCart, Wix, or Bagisto - guided installs, downloads, and configuration.

<div>
  <p>Merchant store plugins</p>

  <p>
    Use PayGlocal on the platform you already run. Pick a guide below for install paths, download matrices, admin screenshots, and
    credential fields. Same integration outcome as our APIs — less engineering lift when a native plugin fits your stack.
  </p>
</div>

## Supported platforms

<CardGroup>
  <Card title="Shopify" icon="shopify" href="/docs/plugins/shopify">
    Two App Store flows: **Seamless** (card fields on your storefront) and **Redirection** (hosted PayGlocal page). Install both when you need both checkout experiences.
  </Card>

  <Card title="WooCommerce" icon="wordpress" href="/docs/plugins/woocommerce">
    WordPress ZIP plugin: PHP-based download matrix (with and without Elementor), upload install, and **WooCommerce → Payments** configuration walkthrough.
  </Card>

  <Card title="Magento" icon="magento" href="/docs/plugins/magento">
    Adobe Commerce / Magento module: copy to root, flush cache, then **System → Configuration → Sales → Payment Methods**.
  </Card>

  <Card title="OpenCart" icon="cart-shopping" href="/docs/plugins/opencart">
    Extension installer, **Extensions → Payments**, and field reference including gateway and refund URLs for sandbox testing.
  </Card>

  <Card title="Wix" icon="wix" href="/docs/plugins/wix">
    Velo **Service Plugins → Payment**, npm packages (`jose`, `crypto-js`), publish, then connect under **Accept Payments**.
  </Card>

  <Card title="Bagisto" icon="bag-shopping" href="/docs/plugins/bagisto">
    Laravel-based e-commerce: built-in PayGlocal support via **Configure → Payment Methods**. Paste your credentials and go live.
  </Card>
</CardGroup>

## What you will need

Before any plugin setup, have merchant credentials from [GCC](/docs/getting-started/dashboard-and-key-management) and review [Key Management](/docs/key-management/overview) for signing material (merchant ID, keys, PEM files) referenced in each admin UI.

<Note>
  If your PHP, Magento, OpenCart, or WooCommerce version is not listed in a download table, contact your **PayGlocal account manager** for the correct build.
</Note>


# Shopify
Source: https://payglocal.in/docs/plugins/shopify

Accept payments on your Shopify store using PayGlocal — Seamless or Redirection.

## What is Shopify?

[Shopify](https://www.shopify.com) is an e-commerce platform used by millions of merchants around the world to build and run their online stores.

## Shopify with PayGlocal

Integrating PayGlocal with Shopify enables online merchants to accept payments through internet banking and debit/credit cards from customers on the Shopify platform. The plugin makes it easier for merchants to accept payments through the PayGlocal payment gateway.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Available Plugins

PayGlocal offers two Shopify plugins depending on how you want customers to complete their payment.

<div>
  <table>
    <thead>
      <tr>
        <th>Flow</th>
        <th>Description</th>
        <th>Install</th>
      </tr>
    </thead>

    <tbody>
      <tr>
        <td>Seamless</td>
        <td>Card details collected on your Shopify storefront. Customer never leaves your store.</td>

        <td>
          <a href="https://apps.shopify.com/payglocal-seamless-payment">
            Install Seamless Flow
          </a>
        </td>
      </tr>

      <tr>
        <td>Redirection</td>
        <td>Customer is redirected to PayGlocal's hosted payment page, then returned to your store after payment.</td>

        <td>
          <a href="https://apps.shopify.com/payglocal">
            Install Redirection Flow
          </a>
        </td>
      </tr>
    </tbody>
  </table>
</div>

## Prerequisites

* An active Shopify store with permission to install payment apps

## Installation Steps

<Steps>
  <Step title="Click the install link">
    Use the links in the table above to open the app on the Shopify App Store. Click **Install**.
  </Step>

  <Step title="Activate the plugin">
    Once installed, activate the PayGlocal plugin from within your Shopify admin.
  </Step>

  <Step title="Done">
    PayGlocal will now appear as a payment gateway on your Shopify checkout page.
  </Step>
</Steps>


# Wix
Source: https://payglocal.in/docs/plugins/wix

Accept payments on your Wix store using PayGlocal — set up the plugin via Velo Dev Mode.

## PayGlocal × Wix

Integrating PayGlocal with Wix enables merchants to accept online payments from their customers on the Wix platform. The plugin makes it easier for merchants to accept payments through the PayGlocal payment gateway.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Installation Steps

### Step 1 — Log in to Your Wix Site

Log in to your Wix account and select the site on which you need to install the PayGlocal plugin. Click the **Edit Site** button (top-right) from your dashboard.

<div>
  <img alt="Wix Dashboard — click Edit Site" />
</div>

***

### Step 2 — Enable Dev Mode

From the Wix editor top bar, go to **Dev Mode** and click **Turn on Dev Mode** to enable Velo.

<div>
  <img alt="Wix Velo Dev Mode panel" />
</div>

***

### Step 3 — Plugin Directory Structure

Inside the **Service Plugins** directory, click the **+** (Add) icon and select **Payment** from the list.

<div>
  <img alt="Service Plugins panel with Payment option" />
</div>

Enter the plugin name as **PayGlocal**. Two files will be created automatically:

* `PayGlocal.js`
* `PayGlocal-config.js`

<div>
  <img alt="Add new payment plugin modal with PayGlocal name" />
</div>

<Note>
  Replace the contents in both files by copying the code from the repository: [PayGlocal-Plugin-Wix-Github](https://github.com/PayGlocal-Technologies)
</Note>

***

### Step 4 — Create Backend Configuration Files

In the **Backend** section, create the following configuration files:

* `payglocal-wrapper.js`
* `payglocal-constants.js`
* `http-functions.js` *(if required)*

<div>
  <img alt="Wix Backend & Public panel with payment-provider folder" />
</div>

<Note>
  Replace the contents in the above files by copying the code from: [PayGlocal-Plugin-Configuration-Wix-Github](https://github.com/PayGlocal-Technologies)
</Note>

***

### Step 5 — Set Merchant-Specific Values

In the `payglocal-constants.js` file, enter the values as below:

| Constant       | Where to find it                                                            |
| -------------- | --------------------------------------------------------------------------- |
| `ACCOUNT_NAME` | **Settings → Website Settings → Site Address (URL)** — copy the domain name |
| `WEBSITE_NAME` | Enter your site URI here                                                    |

Also enter your **Public Key** in the designated field within the file.

***

### Step 6 — Install npm Packages

Navigate to **Packages & Apps** in the Velo sidebar and install the following libraries via npm:

* `jose`
* `crypto-js`

<div>
  <img alt="Wix Packages and Apps panel with jose and crypto-js installed" />
</div>

***

### Step 7 — Publish the Website

Once all the changes are made, click the **Publish** button (top-right of the editor) to make PayGlocal live on your site.

***

### Step 8 — Verify Plugin on Payment Page

After publishing, PayGlocal will appear as a plugin under the **Accept Payments** section.

<div>
  <img alt="PayGlocal listed as a payment provider with Connect button" />
</div>

***

## Activating PayGlocal for Payment Processing

To activate PayGlocal as a payment method:

<Steps>
  <Step title="Locate the PayGlocal plugin">
    Once the website is published, ensure PayGlocal is visible as a payment plugin under Accept Payments.
  </Step>

  <Step title="Enter credentials and connect">
    Enter your **Merchant ID** and **API Key** in the relevant fields and click **Connect**.
  </Step>

  <Step title="Ready to process">
    Upon successful connection, PayGlocal will be ready to process payments.
  </Step>
</Steps>

<Check>
  **Setup Successful** — Once you have followed all the steps above, the PayGlocal payment gateway is successfully set up with your Wix store.
</Check>

<Warning>
  If you face any installation errors, email us at [merchant.support@payglocal.in](mailto:merchant.support@payglocal.in) and we will get back to you at the earliest.
</Warning>

***

## Customer Journey

On the checkout page, PayGlocal will appear as a payment option. Upon selecting **International Credit/Debit cards (PayGlocal)**, the customer will be redirected to the payment page to complete the transaction.

<div>
  <img alt="Wix checkout page showing PayGlocal as a payment option" />
</div>

After a successful payment, an order entry will be created in the **Orders** tab with all relevant transaction details.


# WooCommerce
Source: https://payglocal.in/docs/plugins/woocommerce

Accept payments on your WooCommerce store using PayGlocal — download, install, and configure in minutes.

## What is WooCommerce?

WooCommerce is an open-source plugin for WordPress that allows creating online eCommerce sites. The plugin is easy to set up and is being used by thousands of businesses around the world.

## WooCommerce with PayGlocal

Integrating your WooCommerce store with PayGlocal allows you to accept online payments securely through net banking and debit/credit card. Our WooCommerce plugin makes the PayGlocal integration seamless for the merchants.

<Note>
  Before following the steps below, ensure you have a **PayGlocal merchant account**. [Contact us](mailto:support@payglocal.in) to create one.
</Note>

## Plugin Download

Download the ZIP package based on your PHP version. If you are not able to see the package for your PHP version, kindly reach out to your account manager.

<Note>
  **Technical Requirements** — PHP 7.0 or higher · WooCommerce compatible version · Minimum 25 MB free disk space.
</Note>

### Without Elementor

| PHP Version | Download                                                                             |
| ----------- | ------------------------------------------------------------------------------------ |
| 7.1         | [Download](mailto:support@payglocal.in?subject=WooCommerce%20Plugin%20PHP%207.1)     |
| 7.2 – 7.4   | [Download](mailto:support@payglocal.in?subject=WooCommerce%20Plugin%20PHP%207.2-7.4) |
| 8.0         | [Download](mailto:support@payglocal.in?subject=WooCommerce%20Plugin%20PHP%208.0)     |

### With Elementor

| PHP Version | Download                                         |
| ----------- | ------------------------------------------------ |
| 7.4         | [Download](https://drops.meetanshi.com/f/ac2l2B) |
| 8.0         | [Download](https://drops.meetanshi.com/f/8Xkr8t) |

## Plugin Installation

Follow the steps below to install the PayGlocal WooCommerce plugin and start accepting payments.

<Steps>
  <Step title="Log in to your WordPress admin panel">
    Open your WordPress site and sign in to the admin panel.
  </Step>

  <Step title="Go to Plugins → Installed Plugins → Add New">
    From the left navigation, go to **Plugins → Installed Plugins → Add New**.
  </Step>
</Steps>

<div>
  <img alt="WordPress Plugins screen with Add New highlighted" />
</div>

<Steps>
  <Step title="Click Upload Plugin">
    On the Add Plugins screen, click **Upload Plugin**.
  </Step>

  <Step title="Upload the ZIP package and install">
    WordPress will ask you to upload a ZIP package. Upload the downloaded ZIP package and click **Install Now**.
  </Step>
</Steps>

<div>
  <img alt="WordPress Add Plugins screen showing Upload Plugin and Install Now" />
</div>

## Configuration

<Steps>
  <Step title="Log in to your WordPress admin panel">
    After installation, log in to your WordPress admin panel.
  </Step>

  <Step title="Activate the plugin">
    Navigate to the WordPress Plugin Manager to activate the plugin.
  </Step>

  <Step title="Enable PayGlocal in Payments settings">
    Go to **Settings → Payments**, find **PayGlocal Payments** in the list and enable it.
  </Step>

  <Step title="Open the configuration form">
    Click **Manage** to configure the plugin.
  </Step>
</Steps>

<div>
  <img alt="WooCommerce Payments settings with PayGlocal enabled and Manage highlighted" />
</div>

<Steps>
  <Step title="Configure the plugin fields">
    Fill in the fields as described in the table below.
  </Step>

  <Step title="Save the configuration">
    Click **Save Changes** to save the configuration.
  </Step>
</Steps>

<div>
  <img alt="PayGlocal WooCommerce plugin configuration form" />
</div>

### Field Reference

| Field                | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| **Enable / Disable** | Enable or disable the PayGlocal payment gateway.                                       |
| **Title**            | Custom title for PayGlocal payments shown to customers on the checkout page.           |
| **Description**      | Payment method description displayed to customers on the checkout page.                |
| **Payment Mode**     | Select Sandbox (for testing) or Production.                                            |
| **Merchant ID**      | Your Merchant ID from the PayGlocal dashboard — visible in the top bar when logged in. |
| **Public KID**       | The Public Key ID provided by PayGlocal.                                               |
| **Private KID**      | The Private Key ID provided by PayGlocal.                                              |
| **Public PEM**       | Download the public PEM file from the PayGlocal merchant account and upload it here.   |
| **Private PEM**      | Download the private PEM file from the PayGlocal merchant account and upload it here.  |

<Note>
  For details on fetching your Merchant ID, keys, and PEM files, refer to the [Key Management](/docs/getting-started/dashboard-and-key-management) section.
</Note>

<Check>
  **Setup Successful** — After following the steps above, your WooCommerce store is ready to accept online payments from customers using PayGlocal.
</Check>