MCA Webhook Events

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.

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

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

{
  "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_<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": "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.

`TXN_SENT_FOR_SETTLEMENT`

Fired when PayGlocal has accepted the invoice and submitted the transaction for settlement. No action required from your side.

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

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

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

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.

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

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.

Introduction

Onboarding

Dashboard

Integration

Integration Resources

Merchant store plugins

MCA Integration

Overview

Setting Up Your Webhook Endpoint

The Eight Events

`VIRTUAL_ACCOUNT_PROVISIONED`

`MERCHANT_MCA_ACCEPTED`

`MERCHANT_CARDS_ACCEPTED`

`MCA_FUND_RECEIVED`

`TXN_SENT_FOR_SETTLEMENT`

`TXN_SETTLED`

`FIRC_RECEIVED`

`INVOICE_GENERATED`

Event Summary

Handling Best Practices

​Overview

​Setting Up Your Webhook Endpoint

​The Eight Events

​VIRTUAL_ACCOUNT_PROVISIONED

​MERCHANT_MCA_ACCEPTED

​MERCHANT_CARDS_ACCEPTED

​MCA_FUND_RECEIVED

​TXN_SENT_FOR_SETTLEMENT

​TXN_SETTLED

​FIRC_RECEIVED

​INVOICE_GENERATED

​Event Summary

​Handling Best Practices

Overview

Setting Up Your Webhook Endpoint

The Eight Events

`VIRTUAL_ACCOUNT_PROVISIONED`

`MERCHANT_MCA_ACCEPTED`

`MERCHANT_CARDS_ACCEPTED`

`MCA_FUND_RECEIVED`

`TXN_SENT_FOR_SETTLEMENT`

`TXN_SETTLED`

`FIRC_RECEIVED`

`INVOICE_GENERATED`

Event Summary

Handling Best Practices