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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 support@optty.com. Including the batch ID lets us pull the full processing log immediately.
Last updated