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 an HTTP POST with a JSON body (Content-Type: application/json). Your endpoint must respond with an HTTP 2xx status. Respond first, then process.
Setting Up Your Webhook Endpoint
Your webhook endpoint is a publicly accessible POST endpoint on your backend. Share the URL, and the authentication type you want, with your PayGlocal account manager. PayGlocal configures it against your partner account. There is no self-service API for this. Requirements for a valid webhook URL:- HTTPS
- Publicly reachable (no localhost or private IPs)
- Accepts HTTP POST requests
- Returns an HTTP
2xxstatus promptly. Aim for a few seconds and never more than 30.
3xx response counts as a failure, so give us the final URL.
Events are opt-in. You only receive the events that were enabled for your partner account. If an event you expect never arrives, ask your account manager to confirm it is enabled. Use the subscription key in the table below when you ask.
Authenticating Webhooks
Each request tells you how it was authenticated, based on the authentication type configured for your account:
HMAC:
x-gl-digest is base64(HMAC_SHA256(secret, body)) using your API secret. For transaction events (MCA_FUND_RECEIVED, TXN_SENT_FOR_SETTLEMENT, TXN_SETTLED, FIRC_RECEIVED, CHANGE_REQUESTED, TXN_REFUNDED) the digest is computed over the exact body string you receive, so verify against the raw bytes before parsing.
JWS: x-gl-webhook-token is an RS256-signed token issued by PayGlocal that carries a SHA-256 digest of the request body.
We recommend using one of the authenticated types in production.
The Events
VIRTUAL_ACCOUNT_PROVISIONED
Fired once a merchant’s virtual accounts have been successfully provisioned. This is your signal that the merchant is ready to receive funds.
This event fires only once per merchant, after provisioning is complete. It is sent only for merchants onboarded through your partner account, and only if it has been enabled for you.
event_timestamp is in epoch milliseconds, sent as a string.MERCHANT_MCA_ACCEPTED
Fired when a merchant’s onboarding application is accepted for the MCA product specifically.
MERCHANT_CARDS_ACCEPTED
Fired when a merchant’s onboarding application is accepted for the Cards product specifically.
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.MCA_FUND_RECEIVED
Fired when funds land in the merchant’s virtual account. This is your trigger to upload the supporting invoice.
gid and start your invoice upload flow. See Uploading Documents.
sender_address, sender_country, sender_accountno and paymentRail can be empty or null when the bank did not provide them. sender_name may be partially masked.TXN_SENT_FOR_SETTLEMENT
Fired when the transaction has been submitted for settlement. No action is required from your side.
TXN_SETTLED
Fired when the funds have been settled to the merchant’s INR bank account.
settled_at and fxRateBookedAt are ISO-8601 date-times. settled_at can be null. Parse them as date-times, not as plain dates.FIRC_RECEIVED
Fired when the Foreign Inward Remittance Certificate (FIRC) is ready. The FIRC is the official proof of receipt for cross-border payments and is required for compliance.
fircUrl and store it in your own system.
If a transaction has more than one FIRC document,
fircUrl points to a single ZIP file (<gid>-firc.zip) that contains them. fircUrl can be null if no FIRC file exists yet. When a delivery is retried, the URL is regenerated, so a retry always carries a fresh 10 minutes.CHANGE_REQUESTED (compliance alert)
Fired when PayGlocal’s compliance team needs a different or corrected document. The transaction goes back to DOCUMENT_PENDING.
reason, get the corrected document, and upload it again with Upload Document via Presigned URL using the same gid. The settlement fields are usually empty at this stage.
The subscription key for this event is
FFMS_COMPLIANCE_ALERT.TXN_REFUNDED
Fired when a transaction is refunded. This event uses camelCase field names, unlike the other transaction events.
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.
invoiceUrl and store it in your own system, keyed by resellerMid and servicePeriod.
Event Summary
Delivery, Retries and Ordering
Success and failure Any HTTP2xx response counts as success. Any other response, including 3xx, 4xx and 5xx, and any timeout, counts as a failure.
Retries
- Transaction events (
MCA_FUND_RECEIVED,TXN_SENT_FOR_SETTLEMENT,TXN_SETTLED,FIRC_RECEIVED,CHANGE_REQUESTED,TXN_REFUNDED): after a failed delivery PayGlocal retries up to 3 times, no sooner than 5, 15 and 30 minutes after the previous failure. Retries run on a schedule, so a retry can arrive later than those minimums. After the last retry PayGlocal stops. There is no manual replay from your side, so contact support with thegidif you missed an event. - Other events (onboarding events,
VIRTUAL_ACCOUNT_PROVISIONED,INVOICE_GENERATED): do not rely on retries. Keep your endpoint available, and use the fetch APIs to reconcile if you suspect a missed event. - On retry, PayGlocal rebuilds the payload from the current transaction state. A retried event can therefore show newer data than the original.
MCA_FUND_RECEIVED can arrive after TXN_SENT_FOR_SETTLEMENT. Never assume the order of arrival. Use the status to decide whether an event moves a transaction forward, and ignore events that would move it backwards.
Duplicates can happen
The same event can arrive more than once, for example if your endpoint was slow to answer. Payloads do not carry an event ID. Use gid plus status as your idempotency key, because several events share the same gid.
Handling Best Practices
Respond first, process second Return an HTTP2xx immediately, before any business logic. Long-running work in the handler causes timeouts and retries.
gid and status 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 documents immediately
Do not cache fircUrl or invoiceUrl. Download the file to your own storage (S3, GCS, etc.) the moment you receive the event. They expire in 10 and 15 minutes.
Be tolerant of new fields
PayGlocal may add fields to payloads over time. Ignore fields you do not recognise instead of rejecting the request.
Test in the sandbox
Use MCA Demo Funding Ingestion to simulate a funding event and receive MCA_FUND_RECEIVED on your sandbox endpoint.
