Settlements and Reconciliation

Your payment processor pays out the money from your payins in batches, net of fees, refunds and chargebacks. A settlement is Payment Labs' record of one such batch: everything the processor reported for one settlement date, matched to your checkouts and subscription payments. Use it to reconcile your bank deposits with your sales.

The settlement API is read-only. You cannot create or change a settlement.

Before you start

• Get a token with Create Access Token, the same login payors use, from a credential with the Merchant Read permission. See Permissions.
• Settlement data comes from your processor's settlement reports. If you see no settlements, ask Payment Labs whether settlement reporting is enabled for your account.
• The search operations use the request format in Search, Exports and Pagination.

Settlements

A settlement (E-…) has a settlementDate, counts of its items, and a summary of totals by item type and currency.

Find settlements with Search Settlements. You can filter and sort on id, settlementDate, settlementStatus, processingStatus, the item counts, and auditInfo.createdAt / auditInfo.updatedAt.

curl -X POST https://api-sandbox.paymentlabs.io/settlements/search \
  -H "Authorization: Bearer $PAYMENT_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "all": [
        { "fact": "settlementDate", "operator": "inRange", "value": ["2026-10-01", "2026-10-31"] },
        { "fact": "settlementStatus", "operator": "equals", "value": "FINAL" }
      ]
    },
    "sort": [{ "fieldName": "settlementDate", "order": "desc" }],
    "pageSize": 50
  }'

For totals across many settlements, send the same filter to Summarize Settlements. It returns one group per settlementStatus, each with a count and totals per item type and currency.

Settlement items

Each item is one line of the processor's report:

When Payment Labs matches an item to your payin, the item carries checkoutId, transactionId, and for subscriptions subscriptionId and paymentId. settlementDate is the date the processor reported.

• All items of one settlement: List Settlement Items. The response holds items, totalItems and the settlement's summary.
• Has this checkout settled? Search Settlement Items filtered on checkoutId (or transactionId, paymentId, subscriptionId, type, processingStatus):

curl -X POST https://api-sandbox.paymentlabs.io/settlements/items/search \
  -H "Authorization: Bearer $PAYMENT_LABS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "all": [{ "fact": "checkoutId", "operator": "equals", "value": "S-01JBX7Z3K9M2N4P6Q8R0S2T4V6" }] }
  }'

No items means the processor has not reported the payment yet. How long that takes depends on your processor's payout schedule.

Errors and edge cases

An item that could not be matched or processed has processingStatus: "ERROR". Read why with:

• List Settlement Errors: problems reading the processor's files, grouped by file.
• List Settlement Item Errors: problems with individual items.

Common codes:

List Settlement Items and both error operations return 404 for an unknown settlement and 403 for a settlement that belongs to another account.

Next steps

• Refunds
• Payins Overview