A merchant's system of record is wherever they go to check on the status of their business including payment processing. Where that system of record is hosted will impact your integration with Rainforest. It can be Rainforest itself, your platform, or a third-party system the merchant relies on outside of your platform. This guide will walk through the various system of record integration options and the solution to keep the merchant's payments in sync.

Identify where the system of record lives

---

The system of record can be an external system, your platform, or Rainforest.

If your platform is the system of record, then one more factor determines the right integration approach:

This matters because the integration to keep payments in sync will follow different approaches. For single-tenant, deployment behaves like an isolated, often on-premises system, when your platform owns the instance and the solution will utilize the same approach as if the merchant's external system is the system of record.

Rainforest as the system of record

---

In this scenario, your platform embeds the Rainforest Reporting Components, so the merchant goes directly to Rainforest to check payment statuses. Your platform does not need to store or sync any payment records itself, since the Reporting Components render live data straight from Rainforest.

This is the lowest-effort way to give merchants visibility into their payments, and data is guaranteed to automatically stay up to date since there is no syncing required by your platform.

You can use the following Components to give merchants visibility into their payments:

• Payment report component
• Deposit report component

Your platform as the system of record

---

In this scenario, your platform is where merchants expect to see payments inside your own dashboards and reports. Rainforest is still the source of the payment data, but your platform ingests this data and keeps it's own copy in sync. Which integration approach applies depends on whether your platform's deployment is multi-tenant or single-tenant.

Multi-tenant deployments

If your platform runs one shared instance across all of your merchants, which is the common case for a cloud SaaS product, then your platform should integrate with Rainforest's webhooks and API to keep payments in sync.

Ingest with webhooks

Subscribe to the payin, refund, chargeback, ACH return, and deposit webhooks that are relevant to what you display to your merchants, and update your own records as each event arrives. See webhooks for the full event list, retry schedule, and signing model.

Reconcile with the API

Webhooks are delivered at least once, not exactly once. Your integration can query List payments or List deposits on a schedule to catch anything a webhook-only integration might have missed.

Single-tenant or on-premises deployments

If each merchant runs their own isolated instance of your platform, whether that's on-premises or a single-tenant deployment provisioned per merchant in the cloud, the same networking constraints apply as an external system of record. There's often no public inbound HTTPS endpoint for Rainforest to deliver a webhook to. See the on-premises webhook integration guide for patterns to reach a system in that position. Reconcile with the API as described above once connectivity is established.

An external system as the system of record

---

In this scenario, the merchant relies on a third-party system that's separate from both Rainforest and your platform, and expects payments to be reported there too. This system is inherently single-tenant from your platform's perspective, since it belongs to one merchant. Your platform is responsible for pulling payment data from Rainforest, using webhooks or the API as described above, and then pushing the resulting status updates into the merchant's system through a solution that the merchant's system of record supports.

Integration types

How to integrate with the external system will depend on the solution that system supports. Common integrations include:

• Open API systems of record — some vendors publish a documented, self-serve API that your platform can build a direct connector against. This is the most flexible pattern, but your platform takes on the full cost of that flexibility: a connector per system, each with its own authentication model and rate limits, plus ongoing maintenance as vendors ship breaking changes.
• Certified or gated systems of record — other vendors require a formal certification process before an outside platform can integrate, such as an application, a technical review, a sandbox period, and sometimes a fee. Certification typically gates specific endpoints, and read access is often approved faster than write access, so it's worth confirming early which operations you actually need. Certification timelines run from weeks to months and are outside your control, so plan for them on the project's critical path from day one, and design for asynchronous writes rather than assuming a request will succeed immediately, since certified endpoints tend to carry tighter rate limits than the vendor's general infrastructure.
• Aggregator or middleware layer — instead of certifying with each vendor directly, you can integrate with a specialized third party that has already built and certified connectors across various systems of record in a given vertical. This can shorten time to market considerably when you need to support many systems of record at once, in exchange for a new dependency in the data path, less control over data mapping and latency, and typically a per-merchant or per-payment fee.
• AI agent or robotic process automation (RPA) — for systems with no API, certification path, or aggregator coverage, a platform can use a standard user login to the external system and drive an AI agent or RPA tool to log in and post payment updates the same way a person would, through the system's own screens. This generally requires no cooperation from the external system's vendor, since it only relies on standard user credentials, but it's the most fragile option: it depends on the external system's UI staying stable, can raise questions around the vendor's terms of service, and needs careful credential handling and monitoring for silent failures when the UI changes underneath it.
• File-based or batch sync — some legacy systems of record don't expose an API at all, only a flat-file export and import, often over SFTP on a nightly or hourly schedule. This is typically a fallback used when no API or certification path exists, and it introduces latency between when a payment happens and when it's reflected in the merchant's system.

Merchant routing

In order for your platform to orchestrate syncing to an external system of record, your platform will need to store which external system each merchant utilizes and how to integrate with it.

For each merchant, you should store the following information in your platform:

• The external system of record the merchant uses
• The credentials or API key to authenticate to the external system on the merchant's behalf
• Any merchant specific identifiers, such as an account ID within the external system, required to route the syncing correctly

This will allow your platform to support syncing to multiple external systems.

Reconcile payments across systems

The external system will need a way to match a Rainforest payment back to it's own record of the payment. When syncing the payment to the external system, there are two common approaches to passing an identifier:

• Record the Rainforest Payment ID directly into the external system by passing the Rainforest Payment ID in an appropriate field.
• Maintain a mapping table in your platform that will create a relationship between a platform-generated unique ID and the Rainforest Payment ID, and then pass the platform-generated unique ID into the external system. This platform ID can be passed into the payin config's metadata to easily lookup the payment within the Rainforest Reporting Components and API. This allows your platform to support multi-processors since the Rainforest specific identifiers are not passed into the external system.

Payment data to sync

Determine which payments and their status updates your merchants want to sync to their external system. This typically includes the following:

Subscribe to the corresponding payin, refund, ACH return, and chargeback webhooks to drive real-time writes into the external system as these events occur.

If the external system generates an invoice or keeps a running account balance based on payment activity, then decide if the external system needs that data in real time or whether a period job is sufficient. A webhook-driven write keeps the external system up to date in real-time as each even happens. Whereas a scheduled job that queries List payments will update the system on a periodic basis. Many integrations will use both and provide real-time updates with webhooks and a scheduled query as a reconciliation backup.

Billing details

Rainforest's standard billing model is net billing. Billing fees are calculated at the time of processing and the amount the merchant receives for the payin in a deposit will have the fees netted out. If the external system tracks it's own balance or reconciles deposits, then you may need to sync the fee breakdown into the external system to provide clarity to the merchant.

The fee breakdown is available through the API on the following endpoints:

• List payments
  • merchant_fees - the amount of the payment billed to the merchant
• Get deposit activity
  • gross_amount - the gross amount of the payment
  • billing_fees_amount - the amount of the billing fees for the payment
  • split_remainder_amount - the total amount of the amount splits deducted from the merchant
  • net_amount - the net amount of the payment deposited to the merchant (net amount is the gross amount minus the billing fees and split remainder amounts)

Best practices

• Only acknowledge a webhook once the event is queued, not just received. Rainforest only retries delivery when it does not receive a successful response. If your platform returns a 200 and then drops the event before the write completes, Rainforest has no way to know anything went wrong, and that event is gone for good. Accepting the request and queuing it, in that order, before returning a 200 will ensure your system has the event.
• Make writes idempotent. Use the payment ID and event_type as an idempotency key when receiving the webhook, since manual replays from the Rainforest portal and normal at-least-once delivery can both redeliver an event you've already processed.
• Reconcile on a schedule, not just on event. A periodic pass comparing Rainforest payment data against what's recorded in the merchant's external system catches gaps caused by certification rate limits, missed webhooks, or downtime.
• Validate the webhook signature at the point of the write, not just at the edge of your network, per Validate the webhook — this matters even more when a certification requires routing events through an intermediary service.
• Log every event with its outcome, whether received, queued, written, or failed, before the write is attempted, since that log is what makes reconciling a discrepancy with a merchant traceable. that log is what makes reconciling a discrepancy with a merchant traceable.