# Transactions Reporting API

Use the Transactions Reporting API if you process in-app payments outside the Onside Payment SDK.

You must report settled transactions from apps distributed through the Onside Store. Onside uses these reports to calculate the applicable platform fees.

{% hint style="info" %}
If you use the Onside Payment SDK, you do not need this API.
{% endhint %}

### How it works

1. Process the payment in your own payment stack.
2. Wait until the payment is settled or captured.
3. Upload a transaction report and receive a report ID.
4. Check the report processing status with that report ID.
5. Repeat on a fixed schedule based on your transaction volume.

Use batch uploads. Most merchants report hourly, daily, or weekly.

### Reporting flow

The reporting flow has two steps:

1. Upload the report.
2. Poll or query the processing status with the returned report ID.

Use the report ID as your reference for:

* Delivery tracking
* Retry handling
* Reconciliation

### Duplicate handling

The API tolerates duplicate report submissions. If you submit the same report more than once, Onside returns the same report ID. Duplicate transactions inside submitted reports are ignored. This lets you retry safely when you are unsure whether a previous upload completed successfully.

### OpenAPI reference

Use these references for the exact API contract:

* [Merchant reports transaction](https://app.gitbook.com/o/nvk3UljiUI9NN7xz4cj9/s/vu6GnA9QIMP7iX7RdyRJ/~/edit/~/changes/33/transactions-reporting-api/merchant-reports-transaction) — primary operation for submitting transaction data
* [Transaction report schema](https://store.onside.io/schema/transactions-report.json) — JSON schema for the request payload
* [Transaction report result schema](https://store.onside.io/schema/transactions-report-result.json) — JSON schema for the response payload

### Authentication

Onside provides an API key for this API.

Send it as a Bearer token in the `Authorization` header on every request.

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

If you do not have an API key yet, contact your Onside account contact.

### What to report

Report only transactions that meet all of these conditions:

* The app is distributed through the Onside Store
* The payment was processed outside the Onside Payment SDK
* The payment is settled or captured

Do not report:

* Authorized but uncaptured payments
* Refunds
* Chargebacks

If the OpenAPI schema marks a field as required, always send it. Follow the field names, formats, and enum values exactly as defined in the operation reference.

Validate each request body against the [transaction report schema](https://store.onside.io/schema/transactions-report.json) before sending it.

### Reporting schedule and limits

Send transactions in batches.

Choose a reporting cadence that matches your volume:

* Hourly for high-volume apps
* Daily for most apps
* Weekly for low-volume apps

A single report payload must not exceed `5 MB`.

If your batch would exceed that limit, split it into multiple requests.

### Implementation guidance

When you integrate this API:

* Keep your internal transaction ID for reconciliation
* Log every report attempt and response
* Retry failed submissions safely
* Validate your payload against the request schema before sending
* Validate successful responses against the result schema if you persist them

### Best practices

* Report transactions soon after settlement
* Keep a delivery log for audit and support cases
* Monitor for validation errors and fix them at the source
* Store each returned report ID in your internal logs
* Retry with the same report payload when delivery is uncertain

### Need help?

If you are unsure whether a payment flow must be reported, check the operation reference first. If the flow is still unclear, contact Onside before sending production data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.onside.io/api/transactions-reporting-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.