> ## Documentation Index
> Fetch the complete documentation index at: https://payglocal.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCA Webhook Events
> 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.
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.
***
### `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"
}
```
A merchant onboarding for multiple products fires one `MERCHANT__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.
***
### `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": "",
"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": "",
"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": "",
"merchantId": "",
"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": "",
"transaction_amount": "1000.00",
"transaction_currency": "USD",
"settled_at": "2024-10-23",
"settlement_amount": "998.00",
"settlement_currency": "USD",
"fircUrl": "https://.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.
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.
***
### `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": "",
"servicePeriod": "202606",
"MONTH": "May",
"product": "MCA",
"YEAR": "2026",
"merchantId": "",
"invoiceUrl": "https://.s3.amazonaws.com/backfill/reseller_details/invoice.pdf?X-Amz-Expires=900&X-Amz-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`.
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.
***
## 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.