> ## 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.

# Investigate failed and returned payments

> Find failed or reversed payments, inspect their reasons, and identify repeated failures.

Identify payments with a recorded status of `failed` or `reversed`, then inspect the reason for each result. You can also group repeated failures by paykey or customer to prioritize follow-up.

## Before you begin

* Install the [Straddle CLI](/developer-tools/cli/install) and configure an API key for the environment you want to inspect.
* Confirm your [integration type and acting account](/developer-tools/cli/auth-context).
* Choose a payment creation window. The report's `--days` filter uses the payment's `created_at`, rather than the date it failed or was returned.
* Keep the same context and database throughout. Add the same `--db PATH` to each `sync` and `returns` command if you use a custom database.

## Run the workflow

<Steps>
  <Step title="Confirm the account and environment">
    ```bash theme={null}
    straddle agent-context --pretty
    ```

    Check `runtime_context.environment`, `runtime_context.integration_type`, and `runtime_context.acting_account`. For SaaS or marketplace, select the account if needed and check again:

    ```bash theme={null}
    straddle use-account ACCOUNT_ID
    straddle agent-context --pretty
    ```
  </Step>

  <Step title="Refresh payment records">
    ```bash theme={null}
    straddle sync --resources payments --full --max-pages 0 --strict --json
    ```

    Confirm a `sync_complete` event and a final `sync_summary` with `success: 1`, `warned: 0`, and `errored: 0`. Review any `sync_warning` or `sync_anomaly` before using the results. Exit code zero can accompany those findings.
  </Step>

  <Step title="List failed and reversed payments">
    Inspect payments created within the past 30 days:

    ```bash theme={null}
    straddle returns --days 30 --json
    ```

    Use `--days 0` to include all stored history. Records with missing or unparseable creation dates remain in the result and sort after records with known dates.

    To identify repeated failures over a wider creation window:

    ```bash theme={null}
    straddle returns --days 90 --repeat-offenders --json
    ```
  </Step>

  <Step title="Inspect the current reason">
    Retrieve a charge from the result:

    ```bash theme={null}
    straddle charges get PAYMENT_ID --data-source live --no-cache --json
    ```

    For a result with `type: payout`, use:

    ```bash theme={null}
    straddle payouts get PAYMENT_ID --data-source live --no-cache --json
    ```

    Inspect its current status and `status_details` before deciding on customer follow-up or another payment attempt.
  </Step>
</Steps>

## Interpret the results

The standard report contains `window_days`, `count`, `total`, and a `returns` array when matches exist. `count` includes both failed and reversed payments. `total` is their summed amount in cents.

| Payment field | Meaning |
| - | - |
| `id`, `type`, and `status` | Payment to investigate and its recorded state. |
| `code` | Stored `status_details.code`, when present. Read the code and reason together to identify the failure. |
| `reason` | Stored `status_details.reason`, falling back to `status_details.message`. |
| `paykey` and `customer_id` | Related payment method and customer, when available. |
| `created_at` | Payment creation time used for the window and newest-first ordering. |

With `--repeat-offenders`, the report includes an `offenders` array when repeated-failure groups exist. Each group has more than one matching payment. The CLI groups by paykey, or by customer ID when the paykey is absent. Payments without either identifier contribute to the overall count and total but cannot form a group. Groups are ranked by their `returns` count, then `total` amount.

The report's top-level count and total cover all matching failed and reversed payments, including those outside the repeated-failure groups. Each amount is in cents: `12500` represents \$125.00.

## Complete the investigation

Record the payment ID, current reason, related paykey or customer, and required follow-up. Use the [payment status guide](/guides/payments/statuses) to interpret the state. If the issue affects a funding transfer, continue with [reconciliation](/playbooks/reconcile-payments). If the paykey is blocked, [inspect paykeys that need attention](/playbooks/expiring-paykeys).


## Related topics

- [Payment operations playbooks](/playbooks/overview.md)
- [Investigate payment data](/playbooks/investigate-data.md)
- [Payment status and lifecycle reference](/guides/payments/statuses.md)
- [Funding events and reconciliation](/guides/payments/funding.md)
- [ACH return codes and Nacha thresholds](/help/nacha-rules/ach-return.md)


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