Payouts Overview

Payouts send money from your Payment Labs ledger account to people and businesses you pay (payees). This page explains the objects involved and the order you use them in. Each later page in this section covers one step in detail.

Before you start

You have API credentials and a token from Create Access Token. See Environments and Authentication.
To try the whole flow once before reading the details, run the Payouts Quickstart.

The objects

Object	ID	What it is
Ledger account	`A-…`	Your funding account in one currency. Every payment is paid from one ledger account. See Funding and Ledger Accounts.
Payee	`U-…` (`userId`, `payeeId`)	A person or business you pay. Identified in your system by its `referenceId` and email. See Payees and Onboarding.
Batch	`B-…`	A container for payments. It supplies defaults (payment category, tax jurisdiction, allowed payout methods) to the payments inside it. See Batches.
Payment	`P-…`	One payout to one payee, for one amount, from one ledger account. See Creating and Submitting Payments.
Payment method	—	Where the payee receives the money: bank transfer, PayPal, Venmo, debit card and others. The payee chooses it, not you. See Payment Methods and Costs.

Treat every ID as an opaque string. See IDs, Amounts and Dates.

The lifecycle

fund ledger account ──► create batch ──► create payment (DRAFT) ──► payee onboards (payable)
                                                     │
                                                     ▼
                                    submit ──► SUBMITTED ──► PROCESSING ──► COMPLETED
                                                     │                           │
                                                     └──► FAILED / RETURNED ◄────┘

Fund a ledger account. Payments are paid from its balance.
Create a batch with Create Batch.
Create payments in the batch with Create Payment, or upload a spreadsheet with a payment import. Each payment names its payee by email and reference ID. A payee who does not exist yet is created and invited by email.
The payee onboards: they enter their personal details, a payout method and, where required, a tax form and an identity check. You can host this step in your own site with the Payee Widget. When the payee is complete they become payable.
Submit the payment (or the whole batch). Payment Labs debits your ledger account and sends the money on the payee's chosen rail.
Track the status with webhooks or by reading the payment. See Payment Statuses.

You do not have to wait for step 4 before step 5. Submit with autoSubmit: true and Payment Labs sends each payment the moment its payee becomes payable.

Permissions

Reading needs any payout role. Creating and editing needs the Write permission (roles Administrator, Expert User and User), and submitting needs the Payment Approval permission (roles Administrator, Expert User and Approver). A call without the permission it needs returns 403 FORBIDDEN_INSUFFICIENT_TAGS. The full role table is in Permissions, and the permission that wallets and payment requests need is in Wallets, wallet disputes and payment requests.

What is asynchronous

Several operations accept the request and finish the work in the background:

Creating a payment returns DRAFT straight away; the service fee is charged in the background.
Submitting returns 202 Accepted. The payment is queued; the response does not mean it was sent.
Search results come from an index that can be a few seconds behind. Read a single object (for example Get Payment) before you act on it.

Use webhooks to learn about results instead of polling. Register them with Add Webhook; the events for payouts are payment-created, payment-changed, payment-status-changed, batch-created, batch-changed, payee-payability-changed and ledger-account-credited. See Webhooks.

Retries and duplicates

No payout create operation is idempotent: retrying a create that timed out can create a second batch or payment. Submitting is protected: a payment that is already queued or in flight cannot be sent twice. See Idempotency and Retries for how to retry each operation safely.