Partner APIs: MCA
Upload Document via Presigned URL
Attaches a supporting document (e.g. invoice) to an FFMS transaction using a presigned
URL you already control. Provide the presignedUrl in the request body; PayGlocal
downloads the file from that URL and stores it. Only PDF files are accepted. A 200
response means the file was stored, not that it has been approved; size (10 MB) and
compliance checks run afterwards.
POST
/
gcc
/
v1
/
ffms
/
external
/
transaction
/
{gid}
/
upload-presigned
Upload Document via Presigned URL
curl --request POST \
--url https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned \
--header 'Content-Type: application/json' \
--header 'x-gl-auth: <api-key>' \
--data '
{
"amount": "1000.00",
"currency": "USD",
"invoiceType": "INVOICE",
"paymentType": "FULL",
"merchantId": "merchant_001",
"customerFullName": "John Doe",
"shippingDetails": "Bangalore, India",
"invoiceNumber": "INV-2026-00321",
"purposeCode": "P0102",
"fxRate": "83.12",
"fileName": "invoice_INV-2026-00321.pdf",
"presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
'import requests
url = "https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned"
payload = {
"amount": "1000.00",
"currency": "USD",
"invoiceType": "INVOICE",
"paymentType": "FULL",
"merchantId": "merchant_001",
"customerFullName": "John Doe",
"shippingDetails": "Bangalore, India",
"invoiceNumber": "INV-2026-00321",
"purposeCode": "P0102",
"fxRate": "83.12",
"fileName": "invoice_INV-2026-00321.pdf",
"presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
headers = {
"x-gl-auth": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.post("https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned")
.header("x-gl-auth", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1000.00\",\n \"currency\": \"USD\",\n \"invoiceType\": \"INVOICE\",\n \"paymentType\": \"FULL\",\n \"merchantId\": \"merchant_001\",\n \"customerFullName\": \"John Doe\",\n \"shippingDetails\": \"Bangalore, India\",\n \"invoiceNumber\": \"INV-2026-00321\",\n \"purposeCode\": \"P0102\",\n \"fxRate\": \"83.12\",\n \"fileName\": \"invoice_INV-2026-00321.pdf\",\n \"presignedUrl\": \"https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=...\"\n}")
.asString();const url = 'https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned';
const options = {
method: 'POST',
headers: {'x-gl-auth': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '1000.00',
currency: 'USD',
invoiceType: 'INVOICE',
paymentType: 'FULL',
merchantId: 'merchant_001',
customerFullName: 'John Doe',
shippingDetails: 'Bangalore, India',
invoiceNumber: 'INV-2026-00321',
purposeCode: 'P0102',
fxRate: '83.12',
fileName: 'invoice_INV-2026-00321.pdf',
presignedUrl: 'https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=...'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"gid": "gl_XXXXXXXXXXXXXXXX",
"status": "201 CREATED",
"message": "Request completed",
"timestamp": "05/03/2026 17:35:10",
"reasonCode": "GL-201-001",
"data": null,
"errors": null
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": null,
"errorDetails": [
{
"fieldName": "paymentData.totalAmount",
"message": "This field is required"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "UNAUTHORIZED",
"data": {},
"errors": null,
"errorDetails": [
{
"fieldName": "authorization",
"message": "Invalid x-gl-token-external"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}When to Use
Call this when you receive anMCA_FUND_RECEIVED webhook with status DOCUMENT_PENDING, or a CHANGE_REQUESTED alert asking for a corrected document. You provide the supporting document (for example an invoice) as a presigned URL you control. PayGlocal downloads the file from that URL during this call and stores it for the transaction.
Authentication
Send your API key in thex-gl-auth header. No x-gl-digest is needed for this endpoint.
x-gl-auth: <your API key>
Request Rules
| Field | Rule |
|---|---|
gid (path) | The gid from the webhook. The transaction must currently be DOCUMENT_PENDING. |
presignedUrl | Required in practice. Must be reachable when you call. |
fileName | Required in practice. Must end in .pdf (case-insensitive). Only PDF is accepted. |
invoiceType | Send INVOICE. |
paymentType | Send FULL. |
amount, currency | Send the values from the webhook. They are recorded with the document; PayGlocal does not reject a mismatch at this step. |
merchantId | Send the merchant ID from the webhook. PayGlocal takes the merchant from the transaction itself. |
customerFullName | Optional. 3 to 150 characters. |
invoiceNumber | Optional. 1 to 100 characters. |
shippingDetails | Optional. 1 to 120 characters. |
purposeCode | Optional. If you send one, it must be one of the purpose codes configured for the merchant; otherwise 400. If you send several comma-separated, only the first is used. |
fxRate | Accepted but not used by this endpoint. PayGlocal applies the FX rate at settlement. |
What a 200 Means
A 200 means PayGlocal downloaded and stored the file. It does not mean the document has been approved. Checks that run afterwards:
- The file must be 10 MB or smaller and a valid PDF.
- PayGlocal’s compliance team reviews the document.
200, the transaction stays in DOCUMENT_PENDING and you receive no webhook. If your transaction does not move to SENT_FOR_SETTLEMENT after you upload, upload a corrected file or contact support with the gid.
If the compliance team needs a different document, you receive a CHANGE_REQUESTED alert with a reason, the transaction returns to DOCUMENT_PENDING, and you can upload again with this same endpoint.
Retrying and Re-uploading
- If the call fails with
400 Failed to download file from presigned URL, nothing was saved. Fix the URL (or its expiry) and call again. - While the transaction is still
DOCUMENT_PENDING, calling again with a new file is accepted. - Do not send two uploads for the same
gidat the same time. The second returns409.
The
presignedUrl is fetched immediately during the request and is not stored or reused. Make sure it stays valid for at least a few minutes.Error Scenarios
| Scenario | HTTP Code |
|---|---|
Invalid field (length, paymentType value, purpose code not allowed for the merchant) | 400 |
fileName is not a .pdf | 400 |
presignedUrl or fileName missing | 400 |
gid not found (Transaction not found) | 400 |
Transaction is not open for upload (not open for new document upload) | 400 |
Could not download from presignedUrl | 400 |
x-gl-auth missing or invalid | 401 |
| Transaction does not belong to your partner account | 403 |
Another upload for the same gid is already in progress | 409 |
| Internal server error | 500 |
Authorizations
Path Parameters
Body
application/json
A presigned URL you control, pointing to the PDF to attach. PayGlocal downloads the file from this URL during the request and stores it. The URL must be reachable when the request is made. Files larger than 10 MB are rejected after the upload.
Example:
"https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
Upload Document via Presigned URL
curl --request POST \
--url https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned \
--header 'Content-Type: application/json' \
--header 'x-gl-auth: <api-key>' \
--data '
{
"amount": "1000.00",
"currency": "USD",
"invoiceType": "INVOICE",
"paymentType": "FULL",
"merchantId": "merchant_001",
"customerFullName": "John Doe",
"shippingDetails": "Bangalore, India",
"invoiceNumber": "INV-2026-00321",
"purposeCode": "P0102",
"fxRate": "83.12",
"fileName": "invoice_INV-2026-00321.pdf",
"presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
'import requests
url = "https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned"
payload = {
"amount": "1000.00",
"currency": "USD",
"invoiceType": "INVOICE",
"paymentType": "FULL",
"merchantId": "merchant_001",
"customerFullName": "John Doe",
"shippingDetails": "Bangalore, India",
"invoiceNumber": "INV-2026-00321",
"purposeCode": "P0102",
"fxRate": "83.12",
"fileName": "invoice_INV-2026-00321.pdf",
"presignedUrl": "https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=..."
}
headers = {
"x-gl-auth": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.post("https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned")
.header("x-gl-auth", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": \"1000.00\",\n \"currency\": \"USD\",\n \"invoiceType\": \"INVOICE\",\n \"paymentType\": \"FULL\",\n \"merchantId\": \"merchant_001\",\n \"customerFullName\": \"John Doe\",\n \"shippingDetails\": \"Bangalore, India\",\n \"invoiceNumber\": \"INV-2026-00321\",\n \"purposeCode\": \"P0102\",\n \"fxRate\": \"83.12\",\n \"fileName\": \"invoice_INV-2026-00321.pdf\",\n \"presignedUrl\": \"https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=...\"\n}")
.asString();const url = 'https://gcc.prod.payglocal.in/gcc/v1/ffms/external/transaction/{gid}/upload-presigned';
const options = {
method: 'POST',
headers: {'x-gl-auth': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: '1000.00',
currency: 'USD',
invoiceType: 'INVOICE',
paymentType: 'FULL',
merchantId: 'merchant_001',
customerFullName: 'John Doe',
shippingDetails: 'Bangalore, India',
invoiceNumber: 'INV-2026-00321',
purposeCode: 'P0102',
fxRate: '83.12',
fileName: 'invoice_INV-2026-00321.pdf',
presignedUrl: 'https://your-bucket.s3.amazonaws.com/invoice.pdf?X-Amz-Signature=...'
})
};
fetch(url, options)
.then(res => res.json())
.then(json => console.log(json))
.catch(err => console.error(err));{
"gid": "gl_XXXXXXXXXXXXXXXX",
"status": "201 CREATED",
"message": "Request completed",
"timestamp": "05/03/2026 17:35:10",
"reasonCode": "GL-201-001",
"data": null,
"errors": null
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": null,
"errorDetails": [
{
"fieldName": "paymentData.totalAmount",
"message": "This field is required"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "UNAUTHORIZED",
"data": {},
"errors": null,
"errorDetails": [
{
"fieldName": "authorization",
"message": "Invalid x-gl-token-external"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}{
"gid": "gl_9c2645ed09edb22e",
"timestamp": "10/01/2026 15:00:00",
"reasonCode": "VALIDATION_ERROR",
"data": {},
"errors": {},
"errorDetails": [
{
"field": "panNumber",
"message": "Required field is missing"
}
]
}
