What Toku’s mass payouts API does
Global payouts at volume need more than a transfer endpoint. Toku’s API covers the steps around the money as well, so a payout is tied to a signed agreement, a verified contributor and the work it pays for.
- Bulk invoice submission: one request carries many contractors’ invoices, each with line items such as accepted tasks and bonuses.
- Any cadence: monthly, every two weeks, weekly or on demand mid-cycle, from a balance you top up.
- Local currency or stablecoins: each contractor chooses a local bank account or USDC or USDT to a wallet.
- Contracts and IP: Toku can sign as contractor or agent of record and collect an IP transfer that is valid in each contractor’s country.
- Onboarding in your product: identity checks, agreement signing and payout setup through the API or MCP connections.
- Reconciliation: every payout stays matched to its invoice, contractor and agreement for finance and audits.
Separate the work ledger from the payment ledger
Keep task acceptance and earnings calculation in your platform. Pass approved invoice records into the payment workflow and store the identifiers needed to reconcile them later. Do not let an API success response overwrite your own evidence of which tasks were approved.
The contributor’s agreement, verification status, and payout setup need to be complete under the agreed process. Define which system is authoritative for each check and what the contributor sees if a step is incomplete.
Submit a documented invoice batch
The endpoint, authorization headers, and request fields below match the public Toku documentation. The identities, dates, and amounts are illustrative. Confirm the invoice identifiers and operational prerequisites with Toku before using production credentials.
The published response indicates submission success. It does not establish bank receipt or final settlement. Never expose API credentials in a browser or contributor-facing application.
// Server-side example using the documented invoice submission endpoint.
// Submitting invoices is not confirmation that recipients have been paid.
const response = await fetch(
"https://app.toku.com/api/tokuApi/v1/submitBulkInvoicePayments",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TOKU_API_TOKEN}`,
"x-role-type": "CLIENT_ORG_ADMIN",
"Content-Type": "application/json",
},
body: JSON.stringify({
submissionTimestamp: new Date().toISOString(),
invoices: [{
invoiceID: "example-invoice-001",
contractorEmail: "contributor@example.com",
contractorName: "Example Contributor",
invoiceNumber: "EXAMPLE-001",
invoiceDate: "2026-10-13",
dueDate: "2026-10-20",
totalAmount: 45,
currencyCode: "USD",
lineItems: [{
description: "30 accepted annotation tasks",
quantity: 30,
rate: 1.5,
amount: 45,
type: "EARNING",
}],
}],
}),
},
);
if (!response.ok) {
// Reconcile uncertain outcomes before resubmitting a payment operation.
throw new Error(`Invoice submission returned ${response.status}`);
}
const result = await response.json();
if (result.success !== true) throw new Error("Submission not confirmed");Design for incomplete and uncertain outcomes
Before launch, document what happens after a timeout, a rejected record, or a returned payment. Do not automatically retry a money-moving request unless you have established that the first submission did not execute or the provider has documented safe retry semantics.
The public bulk-invoice schema does not establish an idempotency-key contract or a per-invoice settlement response. Confirm duplicate protection, batch limits, partial failures, and the status-reconciliation interface during integration.
- Persist the intended batch and stable invoice references before submitting
- Distinguish validation failure from an unknown outcome
- Restrict the integration credential to the agreed role and organization
- Avoid writing tokens, full identity documents, or unnecessary personal data to logs
- Agree a manual exception process before the first production run
Funding and frequency are part of the design
A task event does not have to produce an immediate bank transfer. Aggregate approved earnings on the agreed schedule, keep bonuses explicit, and ensure the funded balance and approval process cover the planned run.
Test a realistic low-value payment and a failed or corrected payment as well as the happy path. Confirm the contributor’s final net amount rather than looking only at the amount submitted.
Mass payouts API or payout platform?
Payout platforms such as Tipalti, Trolley, Payoneer and PayPal Payouts move money in bulk, and some collect tax forms, while the contracts and IP stay with you. HR platforms such as Deel and Remote add contracts but charge a monthly fee for each contractor. Toku combines bulk payouts with the contract and a country-specific IP transfer, priced on the contributors you pay.
Our comparison of mass payout platforms lists each provider’s published prices and payout options, with sources.
Plan the integration with Toku
Bring your countries, active contributor volume, task and bonus structure, and desired payout cadence. Discuss how the API and MCP connections fit your product and which operations are supported for your account.
Compare the amount the contributor can use
Record the sending fee, conversion, any recipient charge, and the final usable amount. Compare the same payment size and timing. A low headline transfer fee does not establish the lowest total cost.
General information for teams planning contributor programs. Classification, tax, payment eligibility, and data obligations depend on the actual arrangement and applicable local requirements.