Statements

Luqra generates a monthly statement for each originator: a PDF report and a CSV export itemizing the originator's payments for 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

ParameterTypeDefaultDescription
cursorstring--Opaque pagination token. Omit on the first request; pass the nextCursor from the previous response to fetch the next page.
limitinteger20Results per page (1--100)
originatorIdUUID--Filter to a single originator
periodYearinteger--Filter by year (2000--2999)
periodMonthinteger--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

FieldTypeDescription
idUUIDStatement ID
originatorIdUUIDOriginator this statement belongs to
periodYearintegerBilling year
periodMonthintegerBilling month (1--12)
timezonestringIANA timezone used for period boundaries
generatedAtISO 8601When 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
pdfReadybooleanWhether the PDF is available for download
csvReadybooleanWhether the CSV export is available for download
pdfSizeBytesinteger | nullPDF file size in bytes. null until the PDF is rendered.
csvSizeBytesinteger | nullCSV file size in bytes. null until the CSV is generated.
totalPaymentCountintegerPayments whose debit to settlement reached the bank within the period, whether or not they have since been returned
totalReturnCountintegerPayments returned within the period, whether or not they reached the bank within it
totalProcessingVolumeMinorUnitsnumberVolume of the payments counted by totalPaymentCount
totalReturnVolumeMinorUnitsnumberVolume of the payments counted by totalReturnCount
totalDiscountFeesMinorUnitsnumberVolume-based discount fees. Sums the CSV's Discount Fee column
totalTransactionFeesMinorUnitsnumberPer-transaction flat fees. Sums the CSV's Transaction Fee column
totalReturnFeesMinorUnitsnumberReturn fees. Sums the CSV's Return Fee column
totalServiceFeesMinorUnitsnumberMonthly account service fees. Has no CSV column, since it is charged per period rather than per payment

Error responses

CodeReason
400Invalid query parameters
401API key is missing, malformed, unknown, revoked, or expired
403The 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

ParameterTypeDefaultDescription
formatstringpdfWhich rendition to download: pdf or csv

The CSV export itemizes the originator's payments for the period, one row per payment, with the columns Date, Status, Type, Contact, Description, External ID, Amount, Discount Fee, Transaction Fee, Return Fee, Completed At, and Returned At. Amounts are decimal dollar values and always positive; Type carries Debit for an inbound payment and Credit for an outbound one. Status is the payment's status at the moment the statement was generated, the same value the Payments API reports (see Payment lifecycle). Rows are ordered oldest first.

A payment appears when its debit to settlement reached the bank within the period, or when it was returned within the period. Date is the day the debit reached the bank, which is also the sort key. Completed At and Returned At are empty until the payment completes or is returned. Every date and time is in the statement's timezone.

A payment that reached the bank in one period and was returned in a later one appears in both exports: its discount and transaction fees on the first, its return fee on the second, and zero in the other columns each time, so a fee is never counted twice. Refunds and fee debits produce no rows. Unlike the PDF, which summarizes activity by day, the CSV is the itemized ledger behind those totals.

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

CodeReason
400Invalid statement ID format, or format is not pdf or csv
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404Statement not found or does not belong to your organization
409Requested 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.