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

# Check payment progress

> Group charges and payouts by status and inspect payments that may still be canceled.

Find where payments are in their lifecycle and identify the records that need attention. This workflow produces counts and amounts by status, plus a list of payments whose stored status is eligible for a cancellation review.

## 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). SaaS and marketplace integrations select the account being investigated.
* Use the same environment, acting account, and database throughout. For a custom database, add the same `--db PATH` to each `sync` and `pipeline` command.

## 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`. The environment is the API origin. Direct account integrations show a `null` acting account.

    For SaaS or marketplace, select the account if needed, then check the context 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
    ```

    This fetches charges and payouts from the start of the resource, without the default page limit. 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 relying on the report; those findings can accompany exit code zero.
  </Step>

  <Step title="Inspect the status groups">
    ```bash theme={null}
    straddle pipeline --json
    ```

    The report groups all stored payments in the selected context by status. To list the individual cancellation candidates:

    ```bash theme={null}
    straddle pipeline --cancelable --json
    ```
  </Step>

  <Step title="Retrieve current payment details">
    Use the candidate's `type` to choose the command. Replace `PAYMENT_ID` with its `id`.

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

    For a payout:

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

    Review the current status and status details before deciding how to handle the payment.
  </Step>
</Steps>

## Interpret the results

| Field | Meaning |
| - | - |
| `by_status` | Status groups sorted alphabetically. Each contains `status`, `count`, `total`, and `cancelable`. |
| `total` | Sum of full payment amounts in the group, in cents. Charges and payouts are added together. |
| `cancelable_count` and `cancelable_total` | Count and total amount of payments stored as `created`, `scheduled`, or `on_hold`. |
| `cancelable` | Whether the stored status is one of those three candidate statuses. |

The `--cancelable` result is an array of payments with `id`, `type`, `status`, `amount`, and `cancelable`. A value of `12500` in an amount field represents \$125.00.

<Note>
  Cancellation candidates are selected from stored statuses. A payment may have progressed since synchronization. Its current status, hold details, and the permissions of your API key determine the action available when you make the request.
</Note>

## Complete the investigation

Use the [payment status guide](/guides/payments/statuses) to interpret the current state. Record the payment ID and the action or follow-up it requires. For `failed` or `reversed` payments, continue with [failure and return investigation](/playbooks/returns). For funding questions, [reconcile the payment](/playbooks/reconcile-payments).


## Related topics

- [Payment operations playbooks](/playbooks/overview.md)
- [Verifying customers and KYC](/guides/identity/customers.md)
- [Investigate payment data](/playbooks/investigate-data.md)
- [Build your Straddle integration with AI](/developer-tools/overview.md)
- [Charges: collect ACH bank payments](/guides/payments/charges.md)


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