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

# Get Upload Presigned URL

> Generates a presigned upload URL for attaching a supporting document (e.g. invoice)
to an FFMS transaction. Upload the file to the returned URL via HTTP PUT.


## When to Use

Call this when you receive an `MCA_FUND_RECEIVED` webhook with status `DOCUMENT_PENDING`. It returns a temporary `presignedUrl` you then use to upload the supporting document (e.g. invoice) directly via HTTP PUT.

## Upload Flow

```
Step 1 — POST this endpoint → receive presignedUrl
Step 2 — PUT <presignedUrl> with file binary (no auth headers needed)
```

<Warning>
  The `presignedUrl` is temporary — upload the file immediately. Do not cache or reuse it.
</Warning>

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


## OpenAPI

````yaml POST /gcc/v1/ffms/external/transaction/{gid}/upload-presigned
openapi: 3.0.3
info:
  title: PayGlocal API
  description: >
    PayGlocal REST API covering merchant onboarding, payment initiation,
    refunds,

    capture, reversal, and standing-instruction (subscription) flows.
  version: '2.0'
  contact:
    name: PayGlocal Support
    email: merchant.support@payglocal.in
    url: https://payglocal.in
servers:
  - url: https://api.onboard.payglocal.in
    description: Onboarding — Production
  - url: https://api.onboard.uat.payglocal.in
    description: Onboarding — Sandbox
  - url: https://api.payglocal.in
    description: Payments — Production
  - url: https://api.uat.payglocal.in
    description: Payments — Sandbox
  - url: https://gcc.prod.payglocal.in
    description: MCA — Production
  - url: https://gcc.uat.payglocal.in
    description: MCA — Sandbox
security:
  - ApiKeyAuth: []
    DigestAuth: []
tags:
  - name: Merchant Onboarding
    description: Endpoints to create and manage merchant onboarding records.
  - name: Reference Data
    description: Lookup endpoints for static reference data (categories, codes).
  - name: Payment
    description: Payment initiation, refund, capture, reversal, and status endpoints.
  - name: Standing Instructions
    description: Subscription / recurring-payment mandate operations.
  - name: MCA
    description: >-
      Merchant Collection Account — virtual account fetch and transaction
      document upload.
paths:
  /gcc/v1/ffms/external/transaction/{gid}/upload-presigned:
    servers:
      - url: https://gcc.prod.payglocal.in
        description: MCA — Production
      - url: https://gcc.uat.payglocal.in
        description: MCA — Sandbox
    post:
      tags:
        - MCA
      summary: Get Upload Presigned URL
      description: >
        Generates a presigned upload URL for attaching a supporting document
        (e.g. invoice)

        to an FFMS transaction. Upload the file to the returned URL via HTTP
        PUT.
      operationId: getUploadPresignedUrl
      parameters:
        - name: gid
          in: path
          required: true
          schema:
            type: string
          description: >-
            Unique FFMS transaction identifier (from the MCA_FUND_RECEIVED
            webhook).
          example: glm123456789
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentUploadRequest'
            example:
              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
      responses:
        '200':
          description: Presigned URL generated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  gid:
                    type: string
                    description: Transaction identifier.
                    example: gl_XXXXXXXXXXXXXXXX
                  status:
                    type: string
                    example: 201 CREATED
                  message:
                    type: string
                    example: Request completed
                  timestamp:
                    type: string
                    example: 05/03/2026 17:35:10
                  reasonCode:
                    type: string
                    example: GL-201-001
                  presignedUrl:
                    type: string
                    format: uri
                    description: Temporary URL — upload the file immediately via HTTP PUT.
                  fileName:
                    type: string
                    example: invoice_INV-2026-00321.pdf
                  invoiceType:
                    type: string
                    example: INVOICE
                  paymentType:
                    type: string
                    example: CARD
                  data:
                    type: object
                    nullable: true
                  errors:
                    type: object
                    nullable: true
              example:
                gid: gl_XXXXXXXXXXXXXXXX
                status: 201 CREATED
                message: Request completed
                timestamp: 05/03/2026 17:35:10
                reasonCode: GL-201-001
                data: null
                errors: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Document already uploaded for this transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    DocumentUploadRequest:
      type: object
      required:
        - amount
        - currency
        - invoiceType
        - paymentType
        - merchantId
        - fileName
      properties:
        amount:
          type: string
          description: Transaction amount.
          example: '1000.00'
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        invoiceType:
          type: string
          description: Type of document being uploaded.
          example: INVOICE
        paymentType:
          type: string
          description: Payment type classification.
          example: CARD
        merchantId:
          type: string
          description: Merchant identifier. Must match the transaction.
          example: merchant_001
        customerFullName:
          type: string
          description: Full name of the customer (3–150 characters).
          example: John Doe
          minLength: 3
          maxLength: 150
        shippingDetails:
          type: string
          description: Shipping information (1–120 characters).
          example: Bangalore, India
          maxLength: 120
        invoiceNumber:
          type: string
          description: Invoice reference number (1–100 characters).
          example: INV-2026-00321
          maxLength: 100
        purposeCode:
          type: string
          description: Purpose code for remittance reporting.
          example: P0102
        fxRate:
          type: string
          description: Foreign exchange rate applied.
          example: '83.12'
        fileName:
          type: string
          description: File name including extension (extension max 10 characters).
          example: invoice_INV-2026-00321.pdf
    CommonErrorResponse:
      type: object
      properties:
        gid:
          type: string
          example: gl_9c2645ed09edb22e
        timestamp:
          type: string
          example: 10/01/2026 15:00:00
        reasonCode:
          type: string
          example: VALIDATION_ERROR
        data:
          type: object
        errors:
          type: object
        errorDetails:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          description: Name of the field that failed validation.
          example: panNumber
        message:
          type: string
          description: Human-readable error message.
          example: Required field is missing
  responses:
    BadRequest:
      description: Validation error — missing or invalid fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            validationError:
              summary: Validation error example
              value:
                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
    Unauthorized:
      description: Authentication failed — invalid API key or digest.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
          examples:
            unauthorizedError:
              summary: Unauthorized error example
              value:
                gid: gl_9c2645ed09edb22e
                timestamp: 10/01/2026 15:00:00
                reasonCode: UNAUTHORIZED
                data: {}
                errors: null
                errorDetails:
                  - fieldName: authorization
                    message: Invalid x-gl-token-external
    Forbidden:
      description: The onboardingId does not belong to the authenticated partner.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
    NotFound:
      description: The specified onboardingId does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-gl-auth
      description: Static API Key generated from the PayGlocal Partner Dashboard.
    DigestAuth:
      type: apiKey
      in: header
      name: x-gl-digest
      description: >
        Per-request HmacSHA256 signature, Base64-encoded, using your API Secret
        as the HMAC key.

        - For GET requests: sign the request URI path (e.g.
        `/gcc/v2/partner/merchant/onboard/business-category`), including query
        string if present.

        - For POST/PUT requests: sign the exact raw request body.

````