Get a payment document

Retrieve a payment document by ID. Use it to check whether the document can still be used on a quote, or which quote it is attached to.

GET /payment-documents/{paymentDocumentId}

Get a payment document

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/payment-documents/{paymentDocumentId} \
  --header 'Authorization: Basic <encoded-value>'

200

{
  "id": "PaymentDocument: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",
  "createdAt": "2025-10-03T12:00:00Z",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Path Parameters

paymentDocumentId · string · required

Payment document ID

Example:

"PaymentDocument:019542f5-b3e7-1d02-0000-000000000001"

Response

200

application/json

Successful operation

A supporting document uploaded for a payout that requires one. Pass its id in documentIds on POST /quotes.

id · string · required

Unique identifier for this payment document

Example:

"PaymentDocument:019542f5-b3e7-1d02-0000-000000000001"

documentType · enum<string> · 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.

Available options: PURCHASE_ORDER, LOGISTICS_BILL, CUSTOMS_DECLARATION, INVOICE, CONTRACT, DELIVERY_SLIP, BILL_OF_LADING, FLIGHT_TICKET, TRAVEL_DOCUMENT, HOTEL_BOOKING_CONFIRMATION

Example:

"INVOICE"

fileName · string · required

File name of the uploaded file

Example:

"invoice-2025-0142.pdf"

sizeBytes · integer · 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.

Required range: x >= 1

Example:

482133

contentType · string · 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.

Example:

"application/pdf"

status · enum<string> · required

Where the payment document is in its lifecycle.

Status	Terminal	Meaning
UPLOADED	No	Ready to use. Pass the id in documentIds on POST /quotes before expiresAt.
ATTACHED	Yes	Attached to the payment behind the quote in quoteId. Grid has deleted the file.
EXPIRED	Yes	Not attached to a quote before expiresAt. The document can no longer be used.

Available options: UPLOADED, ATTACHED, EXPIRED

Example:

"UPLOADED"

expiresAt · string<date-time> · required

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

Example:

"2025-10-04T12:00:00Z"

createdAt · string<date-time> · required

When this document was uploaded

Example:

"2025-10-03T12:00:00Z"

customerId · string

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.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000001"

quoteId · string

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

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"