Skip to main content

Documentation Index

Fetch the complete documentation index at: https://payglocal.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

When funds arrive in a merchant’s virtual account, PayGlocal requires a supporting document — typically an invoice — before processing settlement. You upload this document using a two-step presigned URL flow:
  1. Request a presigned upload URL from PayGlocal
  2. Upload the file directly to that URL
This keeps your API key out of the file upload and lets clients upload large files efficiently without routing through your backend.

​
When to Trigger This

Upload the document 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 to the upload API. 
MCA_FUND_RECEIVED webhook received
         │
         ▼
  Extract gid from payload
         │
         ▼
  POST /gcc/v1/ffms/external/transaction/{gid}/upload-presigned
         │
         ▼
  Receive presignedUrl
         │
         ▼
  PUT <presignedUrl> with file binary
         │
         ▼
  Upload complete — PayGlocal processes settlement

​
Step 1: Request the Presigned URL

Make a POST request with the transaction and invoice details. The key required fields are:
FieldWhat to send
gidFrom the path — the transaction ID from the webhook
amountThe transaction amount from the webhook
currencyThe transaction currency from the webhook
merchantIdThe merchant’s ID — must match the transaction
invoiceTypeThe type of document you are uploading (e.g. INVOICE)
paymentTypeThe payment type (e.g. CARD)
fileNameThe file name including extension (e.g. invoice_001.pdf)
Optional fields like invoiceNumber, customerFullName, purposeCode, and fxRate provide additional context that helps PayGlocal’s compliance processing. Example request body: 
{
  "amount": "1000.00",
  "currency": "USD",
  "invoiceType": "INVOICE",
  "paymentType": "CARD",
  "merchantId": "<merchant_id>",
  "invoiceNumber": "INV-2026-00321",
  "customerFullName": "John Doe",
  "purposeCode": "P0102",
  "fxRate": "83.12",
  "fileName": "invoice_INV-2026-00321.pdf"
}
The response gives you a presignedUrl to use in Step 2.

​
Step 2: Upload the File

Use the presignedUrl from Step 1 to upload the file with an HTTP PUT. No authentication headers are needed — the presigned URL is self-authorising. 
curl -X PUT "<presignedUrl>" \
  --upload-file invoice_INV-2026-00321.pdf
A 200 OK response from the PUT confirms the upload succeeded.
The presigned URL is temporary. Upload the file immediately after receiving it in Step 1 — do not cache or reuse the URL.

​
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 uploaded, 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.