> For the complete documentation index, see [llms.txt](https://docs.optty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optty.com/payouts/bulk-payouts.md). # Bulk Payouts Bulk Payouts lets a merchant disburse funds to many beneficiaries in a single upload. You select a payout-enabled provider and currency, upload a CSV, review the validation result, then submit. Payouts can be sent immediately or scheduled for a future date. ![Bulk Payouts end-to-end flow](/files/JLAielnWI2zOYIjEJ50F) At a glance: the customer prepares and uploads the CSV; Optty validates it and either bounces it back for fixes or schedules and dispatches each payout to the chosen APM; the APM moves the funds and reports back; Optty updates statuses live in the portal for the customer to review. > **This page uses Volt (AUD) as the worked example.** Optty applies the column set and validation rules of whichever APM and currency you select in step 1, so other providers may require different fields, accept different formats, or enforce slightly different rules. The CSV template downloaded from the portal is always the source of truth for the combination you are uploading against. ## Before you start: enabling a provider for payouts Bulk Payouts is only available when the provider has been enabled with **every** credential field populated — including fields that look optional. For payout-capable providers, leaving an "optional" field blank is the most common cause of failed payouts. For **Volt (AUD)** that means filling all five fields on the API Credentials page: Username, Password, Public Key ID, Private Key, **and** Payout Notification Secret. Without the Payout Notification Secret every payout will fail at submission. ![Volt API credentials — all fields required for payouts](/files/6HGc8wzkeE4DZvl7Kbzu) > **Leave Channel Name empty.** The APM must be enabled without a channel selected — payouts use the "default" (empty) channel APMs. If you link the provider to a specific channel, it will not be available for Bulk Payouts. ![Volt API credentials — Channel Name left empty for payouts](/files/6JZhdDj1xfa4yjGUOFB8) ### Configuring the Payout Notification in Fuzebox The Payout Notification Secret is generated in **Volt's Fuzebox** (Volt's merchant portal) — not in Optty. In the same place you generate the secret, you must also set the **Payout Notification URL** so that Volt sends payout status updates back to Optty. Without this URL, payouts will be submitted successfully but their statuses will never progress past `PROCESSING` in the Optty portal, because Optty never receives the callback. In Fuzebox, set the Payout Notification URL to the appropriate Optty webhook endpoint for your environment: | Environment | Payout Notification URL | | ----------- | ------------------------------------------------ | | Sandbox | `https://api.qa.optty.com/webhook?provider=VOLT` | | Production | `https://api.optty.com/webhook?provider=VOLT` | In Fuzebox this is set under **Connect → Notifications → Payout notifications**. Enable the toggle, paste the URL above (matching your environment), and copy the generated Notification Secret. ![Volt Fuzebox — Connect notifications, Payout notifications section](/files/jv7e8p1sf1oB3pKw5dum) Then paste the Payout Notification Secret into the matching field on the Volt API Credentials page in Optty. Both sides — the URL in Fuzebox and the secret in Optty — must be configured together for payout notifications to flow. ## Uploading a batch The flow is a three-step wizard reached from the **Payouts** page using the **Batch Upload** button in the top-right. ![Payouts dashboard — Batch Upload entry point](/files/fW55RlvHZ5JulgjyMLHw) ### 1. Select provider and currency Pick the provider/currency combination you want to pay out from. The page shows the available balance for that combination and lists the required and optional columns for the CSV. A "Download CSV Template" link gives you a header-only template tailored to the currency you selected. ![Step 1 — Select Provider](/files/pPIdxEDSBDyMJ4Dfrckv) ### 2. Upload the CSV Drop the file into the upload card or browse for it. Maximum file size is 10 MB. The file is parsed and validated on the server before you move on. ![Step 2 — Upload](/files/6aEuijIXZGpKDvGvs4yP) ### 3. Review and submit The review screen shows the count of valid and invalid rows. Invalid rows are listed individually with the specific reasons they failed, so you can fix them in your source data and re-upload. Only valid rows are submitted when you press **Submit Batch** — invalid rows are discarded. ![Step 3 — Review](/files/mnnk6fJnnwE7Qzjvpgrd) After submission you are taken to the batch detail page, where each accepted row begins moving through the payout lifecycle. The example below shows two payouts already settled (`PAID`), three queued for a future maturation date (`SCHEDULED`), and one that the provider rejected (`ERROR`). Not pictured: if the merchant's APM balance is insufficient at submission time, payouts sit in `WAITING_FOR_BALANCE` and Optty re-submits them automatically once funds become available — see the lifecycle table below. ![Batch detail with successful and other states](/files/MDgPmZSJjCBUfdWJBQJU) ## Payout lifecycle Every accepted row becomes a payout that progresses through these statuses. The batch detail page shows live counts for each status as the batch processes. | Status | Meaning | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INITIATED` | Row accepted and queued. No provider call yet. Submissions are globally rate-limited across all providers at 2 per second, so large batches drain at that rate. | | `SCHEDULED` | Maturation date is in the future; the payout will be submitted automatically at that time. | | `PROCESSING` | Submitted to the provider; awaiting confirmation. | | `PAID` | Provider confirmed the funds were sent. Terminal. | | `WAITING_FOR_BALANCE` | Provider rejected for insufficient funds. Optty re-checks balance every 5 minutes and re-submits automatically once funds are available. | | `FAILED` | Provider rejected for a reason other than balance (e.g. invalid beneficiary). Terminal — fix the source data and re-submit as a new payout. | | `ERROR` | Submission failed before the provider accepted the request (e.g. missing credential, validation enforced provider-side). The failure reason is shown on the batch detail page. Terminal. | | `CANCELED` | A `SCHEDULED` payout was cancelled by the merchant before its maturation date. Terminal. | ## CSV field reference > The fields and validation rules below describe **VOLT\_AU — AUD**. Each APM (and each currency on that APM) defines its own column set and validation rules, applied automatically based on the provider/currency you selected in step 1. The CSV template downloaded from that step is always the source of truth for the combination you are uploading against. Optty uses a **shared field schema across all APMs**: where a field is used by more than one provider it always carries the same column name and the same shape. `Maturation Date` means the same thing on every APM that supports scheduling; `BSB` is the same six-digit Australian bank-state-branch code on every APM that requires it; `Amount` is always a positive decimal. What varies between APMs is *which* fields are required and which are not used at all — not the schema of the fields themselves. The header row in the template must be present and spelled exactly as shown. The table below reflects **VOLT\_AU — AUD**. | Column | Required | Format / rules | Notes | | ----------------- | ------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `Name` | Yes | Non-empty text | Beneficiary name as it should appear to the receiving bank. | | `Email` | Yes (AUD) | Standard email format | Required for AUD payouts. Optional for GBP/EUR. | | `Amount` | Yes | Positive number, ≤ 2 decimal places | Commas in the value are stripped before parsing, so `1,046.50` is accepted. | | `Reference` | Optional | ≤ 255 chars, unique within the file | Your internal reference. Auto-generated as a UUID if left blank. Maps to Volt `externalReference`. | | `Maturation Date` | Optional | `dd/mm/yyyy`, `dd/mm/yyyyThh:mmTZ±hhmm`, or ISO 8601 | Blank or past date = process immediately. Future date = scheduled and submitted automatically at that time. | | `Description` | Yes | Letters, numbers and spaces only | No punctuation or special characters. Maps to Volt `paymentTitle`. | | `BSB` | Yes (AUD) | 6 digits | Dashes are tolerated, e.g. `062-000` and `062000` are both accepted. | | `Account Number` | Yes (AUD/GBP) | 6–10 digits | AUD/GBP only. | For GBP, replace `BSB` with `Sort Code`; `Account Number` is still required. For EUR, use `IBAN` (required) and `SWIFT/BIC` (optional) instead of `BSB` and `Account Number`. ## Validation errors Validation runs server-side as soon as you upload. The errors below are those enforced for **VOLT\_AU — AUD**; other APMs apply their own rules, surfaced in the same review screen. | Error message | Cause | Fix | | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------- | | `Name is required` | The `Name` cell is empty. | Populate the beneficiary name. | | `Amount is required` | The `Amount` cell is empty. | Add a positive amount with up to 2 decimal places. | | `Amount must be a positive number` | Non-numeric value, zero, or negative. | Use a positive decimal, e.g. `100.50`. | | `Amount must have at most 2 decimal places` | Value like `100.555`. | Round to 2 decimals. | | `Description is required` | The `Description` cell is empty. | Populate the description. | | `Description may only contain letters, numbers, and spaces` | Punctuation such as `'`, `,`, `&` in `Description`. | Remove special characters. Spaces are allowed. | | `Email must be a valid email address` | Malformed email. | Use a standard email format. | | `BSB must be 6 digits (e.g. 062-000)` / `Missing required account field: BSB` | BSB is missing or wrong length. | Provide a 6-digit BSB. | | `Account Number must be 6–10 digits` / `Missing required account field: Account Number` | Account number is missing, contains letters, or out of range. | Use 6–10 numeric digits. | | `Maturation Date is not a valid date (expected dd/mm/yyyy or dd/mm/yyyyThh:mmAEDT+1000)` | Unrecognised date format. | Use `dd/mm/yyyy` or full ISO 8601. | | `payoutReference is duplicated within this CSV` | Two rows share the same `Reference`. | Make each reference unique within the file. | | `payoutReference already has an in-progress (INITIATED) payout` | The same reference is already in flight from an earlier batch or API call. | Use a new reference, or wait for the prior payout to complete. | If a row passes all CSV validation but is later rejected by the provider — for example because the provider performs additional checks against the beneficiary record — the payout is created in the batch and surfaced with status **ERROR** and a failure reason. This is why you may still see error states on the batch detail page even when the upload was clean. ## Monitoring and cancelling payouts The **Payouts** list page shows every individual payout across all batches, with filters by status, currency and date range. `SCHEDULED` payouts have a **Cancel** action; once a payout has moved to `PROCESSING` it cannot be cancelled. ![Payouts list](/files/9KuY5n0am8bqPn0LwFl8) ### Jumping back to a batch Each row in the Payouts list shows the **Batch** the payout came from. Clicking that batch link opens the same batch detail page you saw at the end of the upload flow, with the full row list and live status counts — useful for reviewing a batch after the fact without navigating through the upload wizard. ## Getting help If a batch behaves unexpectedly or a payout sits in `ERROR` without an obvious reason, capture the batch ID from the batch detail URL and email ****. Including the batch ID lets us pull the full processing log immediately.