Skip to main content
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 and configure an API key for the environment you want to inspect.
  • Confirm your integration type and acting account.
  • 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

1

Confirm the account and environment

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:
2

Refresh payment records

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

List failed and reversed payments

Inspect payments created within the past 30 days:
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:
4

Inspect the current reason

Retrieve a charge from the result:
For a result with type: payout, use:
Inspect its current status and status_details before deciding on customer follow-up or another payment attempt.

​
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. 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 to interpret the state. If the issue affects a funding transfer, continue with reconciliation. If the paykey is blocked, inspect paykeys that need attention.