Settlement and Reconciliation

Overview

MoneyHash Settlement & Reconciliation gives your finance team a unified view of all payment settlements across every PSP and acquirer, without spreadsheets, manual column mapping, or month-end surprises.

This guide covers integrating Settlement & Reconciliation via the API - uploading settlement files programmatically and reading back settlement and reconciliation status for every operation. For the no-code dashboard workflow, existing customers can see the full walkthrough in the Knowledge Hub.

What you can do

• Upload settlement files from any supported PSP programmatically - pre-built templates, no column mapping
• Retrieve file-level summaries (gross, fees, net) as soon as a file is processed
• Track every settleable operation and whether it has been matched to a settlement entry
• Detect discrepancies automatically with reconciliation status on each operation
• Pull a unified, normalized operations feed across all providers for audit, escalation, or internal reporting

Integration flow

Uploading and reconciling a settlement file via the API is a three-call sequence:

1. Create a settlement file record and obtain its settlement_file_id
2. Confirm the upload to trigger normalization and matching
3. Retrieve settlement operations to read settlement and reconciliation status

Step 1 - Create a settlement file

Create the settlement file record, specifying the original filename and the PSP template to normalize against.

Request

{
  "file_name": "sample_settlement.csv",
  "template_type": "CHECKOUTCOM"
}

The response returns the created settlement file record, including the id you pass to the confirm step (e.g. oZp3ngM) and the destination to upload the raw file contents to.

Step 2 - Confirm the upload

Once the file contents have been uploaded, confirm the upload to start processing. The request body is empty.

Step 3 - Retrieve settlement operations

Returns a paginated, normalized list of all settleable operations with their settlement and reconciliation status - the API equivalent of the dashboard's Operation View.

Filtering by settlement status, reconciliation status, service provider, settlement file, currency, and more is also supported - see the API Reference for the full parameter list.

Response (truncated to two operations)

{
  "status": {
    "code": 200,
    "message": "success",
    "errors": []
  },
  "data": [
    {
      "transaction_uuid": "4d6e002f-9bd2-40cc-bc68-80fc332e789e",
      "merchant_reference": null,
      "provider_transaction_id": null,
      "arn": "77011384168772813365232",
      "rrn": "116564454628",
      "operation_type": "PURCHASE",
      "settlement_status": "UNSETTLED",
      "reconciliation_status": null,
      "operation_amount": "10",
      "operation_currency": "USD",
      "provider_gross_amount": null,
      "provider_fees": null,
      "provider_tax": null,
      "provider_settled_amount_net": null,
      "settlement_currency": null,
      "transaction_date": "2026-06-28 12:07:25.865562+00:00",
      "settlement_date": null,
      "payment_method": "CARD",
      "provider": "Checkout.com",
      "organization_id": "1",
      "organization_name": "demo org",
      "card_brand": "VISA",
      "issuer": "CKO, WHERE THE WORLD CHECKS OUT",
      "bin": "42424242",
      "authorization_code": "992683",
      "provider_connection": {
        "id": "jZBkM9V",
        "name": "Checkout_S2S_Automation_Don't_Alter"
      }
    },
    {
      "transaction_uuid": "53394ae9-d083-43c2-bf12-0d13ff4a66cb",
      "merchant_reference": null,
      "provider_transaction_id": null,
      "arn": null,
      "rrn": "968820386811",
      "operation_type": "AUTHORIZE",
      "settlement_status": "UNSETTLED",
      "reconciliation_status": null,
      "operation_amount": "0",
      "operation_currency": "USD",
      "provider_gross_amount": null,
      "provider_fees": null,
      "provider_tax": null,
      "provider_settled_amount_net": null,
      "settlement_currency": null,
      "transaction_date": "2026-06-28 12:08:00.022755+00:00",
      "settlement_date": null,
      "payment_method": "CARD",
      "provider": "Checkout.com",
      "organization_id": "1",
      "organization_name": "demo org",
      "card_brand": "Mastercard",
      "issuer": "AFRILAND FIRST BANK",
      "bin": "51234500",
      "authorization_code": "124203",
      "provider_connection": {
        "id": "jZBkM9V",
        "name": "Checkout_S2S_Automation_Don't_Alter"
      }
    }
  ],
  "count": 182572,
  "next": "https://<base-url>/api/v1.4/reconciliations/settlement-operations/?limit=10&offset=10",
  "previous": null
}

Response envelope

Operation object - payment fields

Operation object - settlement & reconciliation fields

Status reference

Settlement Status - did the money move?

Reconciliation Status - does the math add up? (populated once settled)

Automating file uploads

If your team prefers not to upload files manually, two automation paths are available:

• API upload: Push settlement files programmatically using the flow above, as soon as you receive them from your provider.
• Provider-side retrieval: For providers that support SFTP or API-based file delivery, MoneyHash can pull settlement files directly. Ask your account manager whether your provider is supported.