> ## Documentation Index
> Fetch the complete documentation index at: https://docs.straddle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconcile payments

> Match charges and payouts to funding events, then investigate payments with missing funding details.

Find the payments associated with a funding event and identify payments that still need investigation. This playbook produces a list of payment IDs, their recorded statuses and amounts, and their links to funding events.

A [funding event](/guides/payments/funding) records money moving between Straddle and your linked bank account. Use its ID to connect the payments in your application with the corresponding bank activity.

## Before you begin

Prepare the following:

* Install the [Straddle CLI](/developer-tools/cli/install).
* Configure an API key for the environment you want to review. Use sandbox for test data and production for actual payment activity.
* Confirm your [integration type and acting account](/developer-tools/cli/auth-context). SaaS and marketplace integrations select the account being reconciled.
* Have the funding event ID available if you're investigating a specific transfer.

The commands use the CLI's configured environment and acting account. Keep that context throughout the workflow. If you use a custom database, add the same `--db PATH` to every `sync` and `reconcile` command.

## Run the workflow

Use the Straddle CLI to download payment and funding records, group them, and inspect any gaps.

<Steps>
  <Step title="Confirm the account and environment">
    Inspect the resolved context:

    ```bash theme={null}
    straddle agent-context --pretty
    ```

    Check `runtime_context.environment`, `runtime_context.integration_type`, and `runtime_context.acting_account`. The environment is the API origin, such as `https://sandbox.straddle.com`. Direct account integrations show a `null` acting account.

    For a SaaS or marketplace integration, select the account before continuing:

    ```bash theme={null}
    straddle use-account ACCOUNT_ID
    ```

    Run `agent-context` again after changing the selection. The local store separates records by API origin and acting account, so changing either selection changes which records reconciliation reads.
  </Step>

  <Step title="Refresh payments and funding events">
    Download both sets of records into the local store:

    ```bash theme={null}
    straddle sync --resources payments,funding-events --full --max-pages 0 --strict --json
    ```

    The `payments` resource includes charges and payouts. `--full` starts from the beginning of each resource, and `--max-pages 0` removes the default 100-page limit. This can take longer for accounts with a large payment history. Sync updates the local records it fetches.

    The command prints one JSON event per line. Confirm that both resources emit `sync_complete` and that the final `sync_summary` reports `success: 2`, `warned: 0`, and `errored: 0`. Review any `sync_warning` or `sync_anomaly` events before using the results.

    <Note>
      `--strict` makes resource errors fail the command. Access warnings and some data anomalies can still leave the command with exit code zero. Resolve those findings and repeat the sync before treating the local records as complete.
    </Note>
  </Step>

  <Step title="Group payments by funding event">
    Generate the reconciliation report:

    ```bash theme={null}
    straddle reconcile --json
    ```

    The report contains `funding_events`, an array of payment groups, and `outstanding`, the payments without a funding reference. It reads the local records refreshed in the preceding step.

    To focus on one transfer, replace `FUNDING_EVENT_ID` with its ID:

    ```bash theme={null}
    straddle reconcile --funding-event FUNDING_EVENT_ID --json
    ```

    This returns one group with its funding amount, payment count, payment total, and payment list.
  </Step>

  <Step title="Review payments without funding references">
    List the payments that need a closer look:

    ```bash theme={null}
    straddle reconcile --outstanding --json
    ```

    Read each payment's `status` alongside its ID and amount. The `outstanding` label means the stored payment has no `funding_id` or nonempty `funding_ids` entry. The list can include payments at different stages, including failed or cancelled payments.
  </Step>
</Steps>

## Interpret the results

Use the following fields to investigate a funding event:

| Field | Meaning |
| - | - |
| `funding_event_id` | Funding event referenced by the grouped payments. |
| `status` and `direction` | Values from the stored funding event, when available. |
| `funding_amount` | Amount from the stored funding event, in cents. |
| `payment_count` | Number of stored payments that reference this event. |
| `payment_total` | Sum of those payments' full amounts, in cents. |
| `payments` | Matching payments, each with `id`, `type`, `status`, and `amount`. |

For the outstanding view, the result contains `payment_count`, `payment_total`, and `payments`. A value of `12500` represents \$125.00.

Funding references establish which records are linked. Read the payment and funding event statuses to determine their processing state. A payment linked to several events appears in each group with its full amount, so adding group totals can count the same payment more than once. Compare `payment_total` and `funding_amount` within the event you're investigating; the report leaves that comparison to you.

If `status` and `direction` are absent and `funding_amount` is zero, the local store may be missing the funding event. Fetch its current details before interpreting that zero as an actual amount:

```bash theme={null}
straddle funding-events get FUNDING_EVENT_ID --data-source live --no-cache --json
```

For an empty or incomplete payment group, compare the local result with the API's payment search:

```bash theme={null}
straddle payments --funding-id FUNDING_EVENT_ID --all --data-source live --no-cache --json
```

The full reconciliation view includes events referenced by stored payments. A specific-event lookup can return an empty group even when the ID has no local record. Use the live reads to establish whether the event exists and which payments the API returns for it, then refresh the local records.

## Complete the investigation

Match the funding event's amount and transfer details to your bank activity using the [funding and reconciliation guide](/guides/payments/funding). Record the funding event ID, related payment IDs, environment, acting account, and when you refreshed the data.

For payments still requiring investigation, use their recorded status to choose the next step: check processing and funding timing, inspect failure or return details, or correct the account selection and refresh. Keep unresolved differences attached to those IDs so the next review starts with the same records.


## Related topics

- [Payment operations playbooks](/playbooks/overview.md)
- [Payments overview](/guides/payments/overview.md)
- [Check payment progress](/playbooks/payment-progress.md)
- [Funding events and reconciliation](/guides/payments/funding.md)
- [Synchronize and query local data](/developer-tools/cli/local-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.