LIlightsparkdev
Cross-Currency Transfers

Upload a payment document

Changed on

Upload a supporting document for a payout that requires one. Supporting Documents lists which payouts need documents, the documents each purposeOfPayment needs, and what the payout partner checks in them. Upload each file here, then pass the returned id values in documentIds on POST /quotes. Grid attaches the files to the payment before it returns the quote.

The request must use multipart/form-data with the file in the file field and metadata in the remaining fields. Each request uploads one file. To upload several files, send one request per file. You can send them in parallel. A quote accepts up to 3 documents.

Supported formats are PDF, JPEG, and PNG. Grid detects the format from the file contents, not the file name. The file must be from 1 to 8,000,000 bytes. An empty file, a larger file, and any other format return 400 INVALID_INPUT.

A payment document:

  • can be used until its expiresAt, 24 hours after upload
  • can be used on one quote only, and only on a quote for the customer in customerId, or on the platform's own quote when customerId is omitted
  • has its file deleted by Grid once it is attached to the payment

Grid does not check what a document says. The payout partner reviews each document after Grid attaches it, and may reject or delay the payout. A successful attachment means the payout partner received the file, not that it approved it.

post/payment-documents

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/payment-documents
  • Auth
    HTTP basic

Request body multipart/form-data

filestring binary required

The document file, from 1 to 8,000,000 bytes. Grid accepts PDF, JPEG, and PNG files and detects the format from the file contents, not the file name. An empty file, a larger file, and any other format return 400 INVALID_INPUT.

documentType'PURCHASE_ORDER' | 'LOGISTICS_BILL' | 'CUSTOMS_DECLARATION' | 'INVOICE' | 'CONTRACT' | 'DELIVERY_SLIP' | 'BILL_OF_LADING' | 'FLIGHT_TICKET' | 'TRAVEL_DOCUMENT' | 'HOTEL_BOOKING_CONFIRMATION' required

What a supporting document is. These are kinds of evidence, not file formats: INVOICE means the file is an invoice.

Supporting Documents lists the types each requirement accepts. When you upload a file with POST /payment-documents, documentType declares which type the file is.

customerIdstring

ID of the sending customer whose payment this document supports. The document can only be used on this customer's quotes. Omit it when the platform itself is the sender, as on a quote with no customerId. The document can then only be used on the platform's own quotes.

Example request

{
  "documentType": "INVOICE",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
}

Response

Payment document uploaded successfully

idstring required

Unique identifier for this payment document

customerIdstring

ID of the sending customer whose payment this document supports. The document can only be used on this customer's quotes. Absent when the platform itself is the sender.

documentType'PURCHASE_ORDER' | 'LOGISTICS_BILL' | 'CUSTOMS_DECLARATION' | 'INVOICE' | 'CONTRACT' | 'DELIVERY_SLIP' | 'BILL_OF_LADING' | 'FLIGHT_TICKET' | 'TRAVEL_DOCUMENT' | 'HOTEL_BOOKING_CONFIRMATION' required

What a supporting document is. These are kinds of evidence, not file formats: INVOICE means the file is an invoice.

Supporting Documents lists the types each requirement accepts. When you upload a file with POST /payment-documents, documentType declares which type the file is.

fileNamestring required

File name of the uploaded file

sizeBytesinteger required

Size of the uploaded file in bytes. It never exceeds the largest file POST /payment-documents accepts, which is 8,000,000 bytes today.

contentTypestring required

File format as a MIME type, as Grid detected it from the file contents. Today one of application/pdf, image/jpeg, or image/png. Treat it as an open value, because Grid may accept more formats later.

status'UPLOADED' | 'ATTACHED' | 'EXPIRED' required

Where the payment document is in its lifecycle.

StatusTerminalMeaning
UPLOADEDNoReady to use. Pass the id in documentIds on POST /quotes before expiresAt.
ATTACHEDYesAttached to the payment behind the quote in quoteId. Grid has deleted the file.
EXPIREDYesNot attached to a quote before expiresAt. The document can no longer be used.
expiresAtstring date-time required

When the document stops being usable if it has not been attached to a quote. This is 24 hours after createdAt.

quoteIdstring

ID of the quote whose payment this document is attached to. Present only when status is ATTACHED.

createdAtstring date-time required

When this document was uploaded

Example response

{
  "id": "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "documentType": "INVOICE",
  "fileName": "invoice-2025-0142.pdf",
  "sizeBytes": 482133,
  "contentType": "application/pdf",
  "status": "UPLOADED",
  "expiresAt": "2025-10-04T12:00:00Z",
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "createdAt": "2025-10-03T12:00:00Z"
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 715332dcb111Revision changes
    • warning

      added the new EXACT_AMOUNT_UNAVAILABLE enum value to the response property for the response status