For how payout receivers work, see Payout receivers. The merchant must be Active to add payout receivers.

The merchant's own payout receiver

There is nothing to onboard for a merchant to pay out their own funds with on-demand merchant payouts. When payouts are enabled on the platform, each merchant is automatically onboarded as their own payout receiver of type MERCHANT, with the status of ACTIVE and the bank account they use for deposits.

To find the merchant's own payout receiver, list the merchant's payout receivers filtered to the type MERCHANT. Then create payouts to their payout_receiver_id.

Onboard a third-party payout receiver

Create the payout receiver

Call the Create payout receiver endpoint with the type and identity details.

For a business:

{
  "type": "EXTERNAL_BUSINESS",
  "name": "Pacific Produce",
  "legal_name": "Pacific Produce Co LLC",
  "default_payout_category": "ACCOUNTS_PAYABLE",
  "metadata": {
    "vendor_id": "vnd_1234"
  }
}

For an individual:

{
  "type": "EXTERNAL_INDIVIDUAL",
  "name": "Jane the electrician",
  "first_name": "Jane",
  "last_name": "Doe",
  "default_payout_category": "CONTRACTOR"
}

The payout receiver is created with the status of NEEDS_INFORMATION. Save the payout_receiver_id.

Add the bank account

🚧

Direct PCI integration required

Sending a payout receiver's bank account details to Rainforest via API requires a direct PCI integration, which Rainforest must approve for your platform. See Store payment methods via API. To collect the bank account without a direct PCI integration, create the payout receiver via API, then embed the Payout Receiver Management Component with steps set to payment-method.

Store the payout receiver's bank account as an ACH payment method with the PAYOUT capability, then call the Onboard payout receiver payment method endpoint with its payment_method_id.

{
  "payment_method_id": "mtd_2DrDRpyAdp5MPUJnrJmoZcMmtfF"
}

The bank account is added to the payout receiver with the status of CREATED. It is verified when the payout receiver is submitted.

Submit the payout receiver

Call the Submit payout receiver endpoint with no request body. The payout receiver must be NEEDS_INFORMATION.

The payout receiver moves to VERIFYING while Rainforest verifies them and their bank accounts. When verification completes, they move to:

• ACTIVE: The payout receiver is verified and has a verified bank account. They can be paid.
• NEEDS_METHOD: The payout receiver is verified but does not have a usable bank account. Add and verify one to continue.
• DECLINED: The payout receiver did not pass verification and cannot be paid.

Add a bank account later

To add a bank account to a payout receiver that is ACTIVE or NEEDS_METHOD, call the Onboard payout receiver payment method endpoint, then the Verify payout receiver payment method endpoint. A payout receiver in NEEDS_METHOD moves to ACTIVE once the bank account is verified.

Update a payout receiver

Call the Update payout receiver endpoint with only the fields to change.

• name, default_payout_category, and metadata can be updated until the payout receiver is DECLINED or DEACTIVATED. Metadata is merged by top-level key, and a key set to null is removed.
• legal_name, first_name, and last_name can only be updated while the payout receiver is NEEDS_INFORMATION.

Deactivate a payout receiver

Call the Deactivate payout receiver endpoint, with an optional reason. A deactivated payout receiver can no longer be paid out to, and cannot be reactivated.

{
  "reason": "Vendor relationship ended"
}

Sandbox simulation

In Sandbox, Rainforest does not verify payout receivers, so a submitted third-party payout receiver stays VERIFYING. To test each outcome, call the Simulate payout receiver endpoint with the target status.

{
  "status": "DECLINED",
  "reason": "Failed identity check"
}

The payout receiver must be VERIFYING. A MERCHANT payout receiver is already ACTIVE, so there is nothing to simulate.