Upload Document via Presigned URL

POST

gcc

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": "CARD",
  "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": "CARD",
    "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\": \"CARD\",\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: 'CARD',
    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"
    }
  ]
}

{
  "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 an MCA_FUND_RECEIVED webhook with status DOCUMENT_PENDING and you already have the supporting document (e.g. invoice) hosted at a presigned URL you control. Include that presignedUrl in the request body — the backend downloads the file from it and stores it for the transaction. This is a single-call alternative to uploading the file directly as multipart form data.

Upload Flow

POST this endpoint with presignedUrl in the request body → document is fetched and stored

The presignedUrl you provide must be reachable at the time of the request — the backend fetches it immediately during this call. It is not stored or reused afterward.

Error Scenarios

Scenario	HTTP Code
Missing or invalid fields	`400`
Invalid or missing API key	`401`
`merchantId` does not match the transaction	`403`
`gid` does not exist	`404`
Document already uploaded for this transaction	`409`
Internal server error	`500`

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 (from the MCA_FUND_RECEIVED webhook).

Body

application/json

amount

string

required

Transaction amount.

Example:

"1000.00"

currency

string

required

ISO 4217 currency code.

Example:

"USD"

invoiceType

string

required

Type of document being uploaded.

Example:

"INVOICE"

paymentType

string

required

Payment type classification.

Example:

"CARD"

merchantId

string

required

Merchant identifier. Must match the transaction.

Example:

"merchant_001"

fileName

string

required

File name including extension (extension max 10 characters).

Example:

"invoice_INV-2026-00321.pdf"

presignedUrl

string<uri>

required

A presigned URL you control, pointing to the file to attach. The backend downloads the file from this URL and stores it in GCC's storage. Use this instead of a multipart file upload. The URL must remain accessible when the request is made.

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.

Example:

"P0102"

fxRate

string

Foreign exchange rate applied.

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

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": "CARD",
  "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": "CARD",
    "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\": \"CARD\",\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: 'CARD',
    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"
    }
  ]
}

{
  "gid": "gl_9c2645ed09edb22e",
  "timestamp": "10/01/2026 15:00:00",
  "reasonCode": "VALIDATION_ERROR",
  "data": {},
  "errors": {},
  "errorDetails": [
    {
      "field": "panNumber",
      "message": "Required field is missing"
    }
  ]
}

Partner APIs: Merchant Onboarding

Payment APIs

Partner APIs: MCA

When to Use

Upload Flow

Error Scenarios

Authorizations

Path Parameters

Body

Response

​When to Use

​Upload Flow

​Error Scenarios

Authorizations

Path Parameters

Body

Response

When to Use

Upload Flow

Error Scenarios