Skip to main content
POST
Upload Document via Presigned URL

When to Use

Call this when you receive an MCA_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 the x-gl-auth header. No x-gl-digest is needed for this endpoint.

Request Rules

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.
If the file fails the size or type check after the 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 gid at the same time. The second returns 409.
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

Authorizations

x-gl-auth
string
header
required

Static API Key generated from the PayGlocal Partner Dashboard.

Path Parameters

gid
string
required

Unique FFMS transaction identifier (the gid from the MCA_FUND_RECEIVED webhook). The transaction must be in DOCUMENT_PENDING.

Body

application/json
amount
string
required

Transaction amount.

Example:

"1000.00"

currency
string
required

ISO 4217 currency code.

Example:

"USD"

invoiceType
enum<string>
required

Type of document being uploaded. Send INVOICE.

Available options:
INVOICE
Example:

"INVOICE"

paymentType
enum<string>
required

Payment type of the document. Send FULL.

Available options:
FULL
Example:

"FULL"

merchantId
string
required

Merchant identifier from the webhook. PayGlocal takes the merchant from the transaction itself.

Example:

"merchant_001"

fileName
string
required

File name. Must end in .pdf (case-insensitive); other file types are rejected.

Example:

"invoice_INV-2026-00321.pdf"

presignedUrl
string<uri>
required

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

customerFullName
string

Full name of the customer (3–150 characters).

Required string length: 3 - 150
Example:

"John Doe"

shippingDetails
string

Shipping information (1–120 characters).

Maximum string length: 120
Example:

"Bangalore, India"

invoiceNumber
string

Invoice reference number (1–100 characters).

Maximum string length: 100
Example:

"INV-2026-00321"

purposeCode
string

Purpose code for remittance reporting. Must be one of the purpose codes configured for the merchant, otherwise the request fails with 400. If several comma-separated codes are sent, only the first is used.

Example:

"P0102"

fxRate
string

Accepted but not used by this endpoint. PayGlocal applies the FX rate at settlement.

Example:

"83.12"

Response

Document uploaded successfully.

gid
string

Transaction identifier.

Example:

"gl_XXXXXXXXXXXXXXXX"

status
string
Example:

"201 CREATED"

message
string
Example:

"Request completed"

timestamp
string
Example:

"05/03/2026 17:35:10"

reasonCode
string
Example:

"GL-201-001"

data
object | null
errors
object | null