This guide walks your platform through creating a payout via API:

1. Check the merchant balance to confirm the merchant's available balance covers the payout.
2. Create a payout config for the merchant the payout is sent from.
3. Preview the payout timing to show the merchant when the payout will process before it is created. This step is optional.
4. Create the payout to schedule it to the payout receiver.
5. Listen to webhooks to keep your platform in sync with each status change of the payout.

For how payouts work, see Payouts.

Check the merchant balance

---

A payout can only be created when the merchant's available balance covers it. For a merchant on net billing, the available balance must cover the payout amount plus the payout fee.

Call the Get merchant balance endpoint to see the merchant's available balance before you create a payout.

Create a payout config

---

Create a payout config to set up a payout with information such as metadata before the payout is created. Every payout is created from a payout config.

A payout config can only be associated to one active payout, which is a payout in the status of Scheduled, In Review, Processing, Succeeded, or Returned. If the payout is in the status of Failed or Canceled, then the payout config can be re-utilized to create a new payout. To create a payout for a different event, create a new payout config.

If a create payout request matches the payout config's active payout exactly while it is still Scheduled, Rainforest returns that payout instead of creating a second one, so a retried request is safe.

Preview the payout timing

---

Before you create the payout, preview the payout timing to show the merchant when the payout will process and when the funds are estimated to arrive. Pass the date the merchant wants the payout to process as the requested_payout_date. Without a requested_payout_date, the response previews the earliest available date.

The response includes:

• scheduled_payout_date: The date the payout will process.
• estimated_arrival_date: Two business days after the scheduled payout date, which can be used to tell the payout receiver when to expect the funds.

The scheduled payout date can differ from the requested payout date:

• A requested payout date on a weekend or US banking holiday moves to the next banking day.
• A requested payout date earlier than the earliest available date moves to the earliest available date. A payout cannot process on the day it is created, so the earliest available date is the next business day, or the business day after that once the 9:00 PM ET cutoff has passed.

Create the payout

---

Create the payout from the payout_config_id with the payout receiver, their bank account, the amount, and optionally the requested_payout_date.

If the request does not set a payout receiver, the payout is sent to the payout config's default payout receiver.

The payout receiver must be Active to be paid. To onboard a payout receiver, see Payout receiver integration options.

Response

A created payout has the status of SCHEDULED. Check these fields in the response:

• scheduled_payout_date: The date the payout will process. It can differ from the requested_payout_date, such as when the requested date falls on a weekend or US banking holiday. See Preview the payout timing.
• estimated_arrival_date: Two business days after the scheduled payout date, which can be used to tell the payout receiver when to expect the funds.
• billing_fee: The payout fee incurred for the payout.

Listen to webhooks

---

Subscribe to the payout webhooks to keep your platform in sync with each status change. If a payout is Failed or Returned, the amount is back in the merchant's available balance. Resolve the cause, such as an invalid bank account, and create a new payout.

To change or cancel a scheduled payout, see Edit or cancel a payout.

Sandbox simulation

---

In the Sandbox environment, payments and payouts do not move on an automatic schedule, which allows you to have more control over testing.

To test payouts via API in Sandbox:

1. Activate the payout receiver. A third-party payout receiver stays Verifying in Sandbox after they are submitted. Move them to Active via the simulate payout receiver endpoint. A merchant paying themselves is already Active.
2. Make funds available. Simulate the merchant's payments completing via the simulate merchant complete payments endpoint. This transitions all the merchant's payments with the status of Processing to Succeeded, so the funds are in the merchant's available balance.
3. Create the payout. Create the payout config and the payout as described above.
4. Simulate the payout status. Move the payout through its statuses via the simulate payout status endpoint: Processing, Succeeded, Failed with a failure code, Returned with an ACH return code, or Canceled. This allows you to test all webhooks for payouts that you will receive in Production.