Payout reports

Use Report Runs to reconcile a specific payout against the balance movements that contributed to it. For payment records across a date range, use the Exports API.

Choose a report type

report_type Use it to
payout_reconciliation.by_id.summary.1 Compare counts and totals by movement type, such as payments or refunds, for one payout.
payout_reconciliation.by_id.itemized.1 Match individual balance movements to payments, refunds, or other sources and see how much each contributed.
payout_settlement.by_id.itemized.1 Inspect the funding allocations behind each contribution. This report requires additional access. Contact your account manager to enable it.

All three types take one parameters.payout_id and support csv and json. Use a paid payout from the same account and mode as the API request. You can find its ID in the Payouts API or in the payout.paid event.

Create and download a report

  1. Create a Report Run with your API key. For a connected account, include its ID in the Paypercut-Account header. Send an Idempotency-Key and reuse it if you retry the same request.

    {
      "report_type": "payout_reconciliation.by_id.itemized.1",
      "parameters": {
        "payout_id": "po_01M710X7PZPF5Z7JSTWKDCE35V"
      },
      "format": "csv"
    }
    
  2. Store the rrun_… ID from the 201 Created response. Retrieve the run with the same account and mode. While the status is pending, check again after a delay. If it is failed, check failure_code before starting a new run.

  3. Once the status is succeeded, download the file using the Report Run ID and your API key. Save the response body as CSV or JSON. If the download returns 503, retry the download for the same run.

Use List Report Runs to find earlier runs for the same account and mode. If the response returns a non-null last_key, pass it to get the next page.

Read the results

The run's columns lists the columns in output order. Omit columns on creation to use the report type's defaults, or pass an ordered list of distinct column names. For example, all three report types support payout_id, movement_type, and payout_contribution. Add payout_contribution_minor to get the contribution as an integer in the smallest currency unit.

Use payout_contribution to reconcile the amount paid out. The gross, fee, and net columns describe the original movements, whose amounts can differ from their contributions to this payout.

CSV uses a header row and empty cells for missing values. JSON returns a columns array and rows keyed by column name, with null for missing values. Amounts in major currency units are decimal values in CSV and decimal strings in JSON.