Skip to main content
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 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.
  • 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. 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.
1

Confirm the account and environment

Inspect the resolved context:
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:
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.
2

Refresh payments and funding events

Download both sets of records into the local store:
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.
--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.
3

Group payments by funding event

Generate the reconciliation report:
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:
This returns one group with its funding amount, payment count, payment total, and payment list.
4

Review payments without funding references

List the payments that need a closer look:
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.

​
Interpret the results

Use the following fields to investigate a funding event: 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:
For an empty or incomplete payment group, compare the local result with the API’s payment search:
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. 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.