Skip to main content

​
Overview

When funds arrive in a merchant’s virtual account, PayGlocal requires a supporting document — typically an invoice — before initiating compliance. You provide this document via a single-call presigned URL flow:
  1. Host the file yourself and generate a presigned URL for it from your own storage (e.g. an S3 bucket you control)
  2. Call PayGlocal’s upload endpoint with that presignedUrl in the request body — PayGlocal fetches the file from it and stores it for the transaction
There is no separate “get a URL, then PUT the file” round trip — the presigned URL is yours to begin with, and PayGlocal is the one downloading from it, not the one issuing it.

​
When to Trigger This

Call the upload endpoint as soon as you receive an MCA_FUND_RECEIVED webhook with status DOCUMENT_PENDING. Extract the gid from the webhook payload — that is what you pass in the path.

​
Request the Upload

Make a single POST request with the transaction, invoice, and presigned URL details. The required fields are: Optional fields like invoiceNumber, customerFullName, purposeCode, and fxRate provide additional context that helps PayGlocal’s compliance processing. Example request body:
A 200 OK response confirms PayGlocal has fetched and stored the file.
The presignedUrl you provide must be reachable at the time of the request — PayGlocal fetches it immediately during this call. It is not stored or reused afterward, so don’t send a URL that expires before the request completes.

​
File Naming Tips

  • Use the invoice number in the filename so it is traceable (e.g. invoice_INV-2026-00321.pdf)
  • Keep the file extension to 10 characters or fewer
  • Supported formats: PDF is recommended for invoices

​
After the Upload

Once the file is fetched, PayGlocal will:
  1. Validate the invoice against the transaction
  2. Send you a TXN_SENT_FOR_SETTLEMENT webhook when processing begins
  3. Send you a TXN_SETTLED webhook when funds hit the merchant’s account
  4. Send you a FIRC_RECEIVED webhook with the compliance certificate
You do not need to call any further API — just listen for the subsequent webhooks. For the full API spec and interactive playground, see Get Upload Presigned URL.