Skip to main content

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 2xx status promptly. Aim for a few seconds and never more than 30.
PayGlocal does not follow redirects. A 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.
What to do: Mark the merchant as ready, then call Fetch Virtual Accounts to get the account details. This event does not include individual account details.
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.
What to do: Extract the 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.
What to do: Update the transaction status in your system and tell 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 and share the settlement details with the merchant: the FX rate applied, when it was booked, the GST amount and the final settled amount.
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.
What to do: Download the FIRC immediately from fircUrl and store it in your own system.
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.
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.
What to do: Read 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.
What to do: Mark the transaction as refunded in your system and inform the merchant.

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

Event Summary


Delivery, Retries and Ordering

Success and failure Any HTTP 2xx 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 the gid if 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.
Ordering is not guaranteed Events come from different systems and retries can arrive late. A retried 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 HTTP 2xx immediately, before any business logic. Long-running work in the handler causes timeouts and retries.
Make your handler idempotent Check whether you have already processed a given 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.