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 Four Events
MCA_FUND_RECEIVED
Fired when funds land in the merchant’s virtual account. This is your trigger to upload the supporting invoice.
What to do: Extract the gid and trigger your invoice upload flow. See Uploading Documents.
TXN_SENT_FOR_SETTLEMENT
Fired when PayGlocal has accepted the invoice and submitted the transaction for settlement. No action required from your side.
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.
What to do: Mark the transaction as complete. Notify the merchant with settlement details including the FX rate applied 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.
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.
Event Summary
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.
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.
