Statements
Luqra generates a monthly statement for each originator: a PDF report and a CSV export itemizing every transaction in the period. Use the Statements API to list available statements and download either format.
List statements
curl "https://{api-host}/v1/statements" \
-H "Authorization: Bearer $YOUR_API_KEY"
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor | string | -- | Opaque pagination token. Omit on the first request; pass the nextCursor from the previous response to fetch the next page. |
limit | integer | 20 | Results per page (1--100) |
originatorId | UUID | -- | Filter to a single originator |
periodYear | integer | -- | Filter by year (2000--2999) |
periodMonth | integer | -- | Filter by month (1--12) |
Response
All total*MinorUnits fields are numbers in minor units (cents for USD). For example, 5000000 = $50,000.00.
{
"data": [
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"originatorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"periodYear": 2026,
"periodMonth": 3,
"timezone": "America/New_York",
"generatedAt": "2026-04-01T02:00:00.000Z",
"pdfReady": true,
"csvReady": true,
"pdfSizeBytes": 102400,
"csvSizeBytes": 8192,
"totalPaymentCount": 150,
"totalReturnCount": 3,
"totalProcessingVolumeMinorUnits": 5000000,
"totalReturnVolumeMinorUnits": 75000,
"totalDiscountFeesMinorUnits": 5000,
"totalTransactionFeesMinorUnits": 3750,
"totalReturnFeesMinorUnits": 7500,
"totalServiceFeesMinorUnits": 3000
}
],
"meta": {
"timestamp": "2026-05-01T10:00:00.000Z",
"pagination": {
"limit": 20,
"nextCursor": null
}
}
}
Fields
| Field | Type | Description |
|---|---|---|
id | UUID | Statement ID |
originatorId | UUID | Originator this statement belongs to |
periodYear | integer | Billing year |
periodMonth | integer | Billing month (1--12) |
timezone | string | IANA timezone used for period boundaries |
generatedAt | ISO 8601 | When the statement was generated. Generation is anchored to the 1st of the month following the period end in the originator's configured timezone, then shifted forward by the originator's configured delay. As a result, generatedAt can vary across originators even for the same period |
pdfReady | boolean | Whether the PDF is available for download |
csvReady | boolean | Whether the CSV export is available for download |
pdfSizeBytes | integer | null | PDF file size in bytes. null until the PDF is rendered. |
csvSizeBytes | integer | null | CSV file size in bytes. null until the CSV is generated. |
totalPaymentCount | integer | Payments in the period, including payments that were returned before completing |
totalReturnCount | integer | Returns in the period |
totalProcessingVolumeMinorUnits | number | Total payment volume, including payments that were returned before completing |
totalReturnVolumeMinorUnits | number | Total returned payment volume |
totalDiscountFeesMinorUnits | number | Volume-based discount fees charged in the period |
totalTransactionFeesMinorUnits | number | Per-transaction flat fees |
totalReturnFeesMinorUnits | number | Return fees charged |
totalServiceFeesMinorUnits | number | Monthly service fees charged |
Error responses
| Code | Reason |
|---|---|
400 | Invalid query parameters |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
5xx responses aren't listed here. See Errors for the full status and error-code reference.
Get a statement download URL
Returns a short-lived signed URL for downloading the statement PDF or its CSV export. The URL expires in 15 minutes.
curl "https://{api-host}/v1/statements/STATEMENT_ID/download" \
-H "Authorization: Bearer $YOUR_API_KEY"
To download the CSV export instead:
curl "https://{api-host}/v1/statements/STATEMENT_ID/download?format=csv" \
-H "Authorization: Bearer $YOUR_API_KEY"
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | pdf | Which rendition to download: pdf or csv |
The CSV export contains every line item in the statement period -- one row per transaction with the columns Date, Type, Contact, Description, External ID, Amount, Discount Fee, Transaction Fee, and Return Fee. Type is one of PAYMENT, RETURN, FEE_COLLECTION, or REFUND, and amounts are decimal dollar values. Outbound payments carry a negative Amount; all other rows are positive. Refund rows only appear for refunds paid back to the originator. Unlike the PDF, which summarizes activity by day, the CSV is the complete transaction ledger.
Response
{
"data": {
"url": "https://storage.googleapis.com/luqra-statements/...",
"expiresAt": "2026-05-01T10:15:00.000Z"
},
"meta": { "timestamp": "2026-05-01T10:00:00.000Z" }
}
The url is a pre-signed download URL that streams the file directly with an attachment content disposition (application/pdf or text/csv). Use it before expiresAt; request a fresh URL whenever you need to download again.
Error responses
| Code | Reason |
|---|---|
400 | Invalid statement ID format, or format is not pdf or csv |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | Statement not found or does not belong to your organization |
409 | Requested file is not yet generated -- check pdfReady: true (or csvReady: true for format=csv) before requesting a download URL |
5xx responses aren't listed here. See Errors for the full status and error-code reference.