Bulk Payouts

Merchants often have to schedule many payouts, which can be time-consuming if done individually. MoneyHash provides a solution by allowing customers to schedule payouts for multiple clients simultaneously through the API. This option eliminates the need to enter data for each client using the embed payout manually. When creating a bulk payout request, you will provide all the necessary data with one API request. MoneyHash will schedule tasks to execute the request without any user intervention. As a result, the scheduling payouts process becomes more efficient for merchants.

Bulk payouts functionalities

To simplify the management of bulk payouts, MoneyHash offers several endpoints for creating, retrieving, editing, and canceling payouts.

Create

API

Schedule up to a thousand payouts at once.

Retrieve

API

Retrieve all your created bulk payout request.

Cancel

API

Call off all payouts inside a bulk payout request.

Edit

API

Edit information from payouts inside a bulk payout request.

Creating bulk payout

Each bulk request facilitates scheduling up to 1000 payouts simultaneously, serving as a valuable tool to expedite a high volume of processes. This method eliminates the need to create an API call for each payout, ensuring an efficient and streamlined process.

The primary goal of bulk payouts is to automate the execution of each payout on the scheduled date. Unlike an individual payout that provides an embed URL for a customer presentation, payouts from a bulk request do not offer this option as their primary objective is automation.

To ensure proper functionality, detailed information such as billing data and payout method must be provided for each payout within the bulk request.

Missing information

Failure to provide the payout method for execution and the customer's billing data to auto-fill the required form will result in payout failure

Each payout is treated as a separate transaction, identifiable through a reference provided for tracking the status of each payout via messages received at the webhook_url.

Updating bulk payouts

The ability to update specific payout information can be beneficial, particularly if the scheduled date requires adjustment or if the payment amount for certain customers has changed.

You can edit one, some, or all associated payouts with a single request. Replicating the request structure used when creating the bulk payouts is necessary. Notably, adding new payouts to an existing bulk is not supported; only existing payouts can be edited.

Editable payouts

You are allowed to edit any scheduled payout that has a SCHEDULED or VALIDATION_FAILED status.

How do bulk payouts work?

The process of creating bulk payouts undergoes a series of stages until the completion and execution of the transactions. All potential statuses of each payout inside the bulk request within MoneyHash are summarized in the following table.

Status	Description
`VALIDATION_PENDING`	Initial status after submission, pending validation.
`VALIDATION_IN_PROGRESS`	Ongoing validation of payout in the bulk request. Validation results will be communicated via webhook upon completion.
`SCHEDULED`	Successful validation, with items scheduled for processing at specified times.
`VALIDATION_FAILED`	Completed validation with invalid items; reasons for failure will be communicated via webhook.
`CANCELLED`	Initiated request to cancel the payout.
`PROCESSING_IN_PROGRESS`	The payout is currently in the processing phase.
`PROCESSED`	Successful completion of payouts and results communicated (success or failure).
`INTENT_CREATION_FAILED`	Unsuccessful payout due to user action or additional routing instructions.

Initially, a bulk payout undergoes a validation process. If any information is invalid, the payout status changes to VALIDATION_FAILED, and you're notified about the issue via the webhook_url. The Edit bulk endpoint can be used to rectify any incorrect data.

When the payout data is valid, it progresses to the SCHEDULED status. At this stage, three options are available:

Wait until the scheduled date for payout processing.
Edit the bulk information, triggering the validation process again until returning to the SCHEDULED status.
Cancel the bulk payout, after which it transitions each payout inside to the CANCELLED status, with no further actions possible.

Each payout in the bulk request is processed upon reaching their respective scheduled dates, generating their own payout intent. This intent is automatically processed. A successful intent creation results in a change of status to PROCESSED, while any intent creation failure prompts a status change to INTENT_CREATION_FAILED, with notification provided via the webhook_url. Consequently, failed intents can be recreated as necessary in a new bulk payout request.

The diagram below succinctly illustrates the stages and statuses of each payout in the bulk payout request within MoneyHash after its creation.