Transactions Reporting API

Transactions Reporting API offers our merchant clients increased flexibility in managing their in-app payments.

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.

If you use the Onside Payment SDK, you do not need this API.

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 — primary operation for submitting transaction data

• Transaction report schema — JSON schema for the request payload

• Transaction report result schema — 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.

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