> ## Documentation Index
> Fetch the complete documentation index at: https://payglocal.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploading Transaction Documents

> How to attach a supporting invoice to an MCA transaction using the presigned upload flow.

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

```
MCA_FUND_RECEIVED webhook received
         │
         ▼
  Extract gid from payload
         │
         ▼
  Host the file at a presigned URL you control
         │
         ▼
  POST /gcc/v1/ffms/external/transaction/{gid}/upload-presigned
  with presignedUrl in the request body
         │
         ▼
  PayGlocal fetches the file from presignedUrl and stores it
         │
         ▼
  Upload complete — PayGlocal initiates compliance check
```

***

## Request the Upload

Make a single POST request with the transaction, invoice, and presigned URL details. The required fields are:

| Field          | What to send                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------- |
| `gid`          | From the path — the transaction ID from the webhook                                          |
| `amount`       | The transaction amount from the webhook                                                      |
| `currency`     | The transaction currency from the webhook                                                    |
| `merchantId`   | The merchant's ID — must match the transaction                                               |
| `invoiceType`  | The type of document you are uploading (e.g. `INVOICE`)                                      |
| `paymentType`  | The payment type (e.g. `CARD`)                                                               |
| `fileName`     | The file name including extension (e.g. `invoice_001.pdf`)                                   |
| `presignedUrl` | A URL you control that PayGlocal can fetch the file from — must be reachable at request time |

Optional fields like `invoiceNumber`, `customerFullName`, `purposeCode`, and `fxRate` provide additional context that helps PayGlocal's compliance processing.

**Example request body:**

```json theme={null}
{
  "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",
  "presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
```

A `200 OK` response confirms PayGlocal has fetched and stored the file.

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

***

## 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](/docs/api-reference/mca/document-upload).