Payouts API returning duplicate/incorrect data - Endpoint unusable

[StoneSet]

Hi,

I'm experiencing an issue with the Payouts API endpoint that makes it currently unusable for production.

Issue:
When calling GET https://api.sumup.com/v1.0/merchants/MERCHANT_ID/payouts?start_date=2025-09-01&end_date=2025-12-05, the endpoint returns all individual transactions instead of consolidated payouts.

For example, on 2025-12-05, instead of getting 1 payout entry with the total amount for that day, I receive 20+ transaction entries with the same reference SUMUP PID1449450 PAYOUT 051225 but different amounts and transaction codes.

Example

[ { "amount": 0.98, "currency": "EUR", "date": "2025-12-05", "fee": 0.02, "id": $, "reference": "SUMUP PID1449450 PAYOUT 051225", "status": "SUCCESSFUL", "transaction_code": "$", "type": "PAYOUT" }, { "amount": 0.98, "currency": "EUR", "date": "2025-12-05", "fee": 0.02, "id": $, "reference": "SUMUP PID1449450 PAYOUT 051225", "status": "SUCCESSFUL", "transaction_code": "$", "type": "PAYOUT" }, // ... more identical duplicates ]

Expected behavior:
The endpoint should return consolidated payouts (one entry per payout per day/period) with aggregated amounts, not individual transaction records.

Impact:
This makes the endpoint unsuitable for syncing payouts into our database, as we cannot reliably identify and consolidate payouts on our end.

Could you please investigate and clarify the intended behavior of this endpoint? I've also opened a support ticket on developer.sumup.com for tracking.

Thanks,

[marielakas]

Hey @StoneSet,

Thank you for reaching out. The behavior you observed is intentional and by design; there is no inconsistency.

This endpoint does not return consolidated payouts, but rather the individual transactions (sales) that were included in the payout. A single payout reference may encompass multiple transactions.

To obtain the net amount for each payout, you must group the returned transactions by their payout reference and sum their respective totals (amount). This approach provides a granular overview of the transactions included within each payout. We guarantee that all payout references returned are unique.

Important Note: This API is marked as deprecated, and new integrations are strongly discouraged. While we plan to implement a new API that will return consolidated payouts, this project is not scheduled for the coming months.

To help us suggest a better solution, could you please share more details about your use case? Specifically, are you using this endpoint for accounting or reconciliation?

Looking forward to hearing from you!

[StoneSet]

Hi,

Thank you for your answer.

I would like to clarify a few points, as there seems to be a discrepancy between the documented behavior and what the API currently returns.

The documentation for the Payouts API (v1.0) does not state that the endpoint is deprecated.
Only the legacy v0.1 payout endpoint is marked as deprecated on developer.sumup.com. (see https://developer.sumup.com/api/payouts/list
Could you please confirm whether v1.0 is officially deprecated, and if so, where this is documented?

The description for the endpoint explicitly mentions payouts, not individual transactions included in payouts. Today, the returned data structure is effectively equivalent to listing transactions with a payout reference.
If the intended behavior is indeed to return transactions instead of consolidated payout entries, this should be stated clearly in the documentation, as it leads to incorrect assumptions on the integrator’s side.

The main problem for our use case is not only the consolidation logic, but the volume and efficiency of the calls.

If the /v1.0/merchants/{id}/payouts endpoint always returns all underlying transactions instead of a single consolidated payout entry, then:

For days with many small payments (micro-transactions), we are forced to fetch hundreds or thousands of items just to reconstruct one payout.

This becomes very inefficient both for your API and for our systems: large payloads, longer response times, more processing on our side, and more potential for timeouts or rate limit issues.

In practice, it makes it very hard to simply “get one payout” with its net amount and date, which is the core need for accounting and reconciliation.

From an API design point of view, the name and path of the endpoint (/payouts) strongly suggest that it returns payout objects, not raw transactions. If the official design is “transactions grouped by payout reference”, then this should be clearly documented, together with explicit guidance or examples for safely reconstructing payouts.

Our use case:
We use payouts for accounting reconciliation and financial reporting in our internal system. Consolidated entries are mandatory for this workflow, and relying on raw transactions complicates reconciliation and increases the risk of inconsistencies.

Thanks a lot,
Regards

[marielakas]

@StoneSet, you are absolutely right. I will immediately create a ticket to update the documentation, ensuring the descriptions and intended behavior of the API are clear and accurate.

As I mentioned previously, our long-term goal is to release a brand new API that returns consolidated payouts, and this is currently on our roadmap. However, it is a lower-priority item for us at this time. For your specific use case, my current recommendation is to create your own service to aggregate the total amounts, as suggested earlier, and integrate it into your internal system.

Alternatively, for a more consistent and manual approach to financial reconciliation, please utilize our monthly payout reports. They are automatically sent to your email address: tresorerie@bde-enssat.fr.

Hope this helps.

[StoneSet]

Hi,

Thanks for the update.

We'll move forward by aggregating all transactions on our side as you suggested. That will let us keep things working until a consolidated payouts API is available.

Thanks again.

Regards,