Introduction to Payment Labs

Payment Labs moves money between your business and the people you work with. You send money out to payees (payouts), let payees bill you (payment requests), hold balances for people in a wallet program (wallets), and collect money from buyers (payins). The API covers what a payor or merchant does in the Payment Labs dashboard, except managing team users, branding and accounting integrations, which stay in the dashboard.

Before you start

You need a Payment Labs account and API credentials for the sandbox environment. Payment Labs issues both. See Environments and Authentication.

Who takes part

Actor	Who it is	In the API
Payor	Your business, when it sends money.	Your account. Get Payor returns it. Its ID is your `payorId`.
Payee	A person or business you pay. Payment Labs onboards them, verifies their identity, collects their tax form and their payout destination (the payment method).	Identified by a `payeeReferenceId` you choose and their email. A payee is payable once onboarding is complete.
Merchant	Your business, when it accepts money. A merchant is the same Payment Labs account as the payor, with payins enabled.	Your account ID appears as `merchantId` on payin objects. Get Merchant returns your payin settings.
Buyer	A person who pays you through a checkout or a subscription.	Created automatically from the email you send when you create a checkout or a plan offer. Find one with Search Buyers.
Wallet holder	A payee enrolled in your wallet program, who keeps a balance with you.	Identified by `holderId`. Each holder has one wallet per currency.

Products

Product	What it does	Main objects	Specification	Start with
Payouts	Pay payees by bank transfer, debit card, PayPal, Venmo and other methods, with tax withholding and reporting handled for you.	Batch, payment, payee, ledger account	Payout API	Payouts Quickstart
Payment requests	Payees submit invoices or expense claims to you. You review them, then approve them or approve and pay them in one step.	Payment request	Payout API	Payment Requests
Wallets	Hold a balance for each wallet holder. You credit and charge wallets; holders load money by card.	Wallet, wallet entry, wallet dispute	Payout API	Wallets Overview
Payins	Accept card and bank payments from buyers through a hosted page, an embedded iframe, the Payin SDK or a card reader. Run recurring billing with subscriptions, and reconcile settlements.	Checkout, checkout transaction, refund, subscription plan, plan offer, subscription, terminal, settlement	Payin API	Payins Quickstart

Every product uses the same base URL and the same login: Create Access Token returns one token that works for every API you are allowed to call. The API reference groups the operations in two specifications:

Payout API: the login, your account and ledger accounts, payees, batches, payments, payment imports, payment requests, wallets, wallet disputes, and webhook registration.
Payin API: your merchant account, checkouts, refunds, subscriptions, terminals and settlements.

Webhook registration lives in the Payout API but covers payin events too, such as checkout-status-changed. See Webhooks.

Your credential's roles decide which operations you can call. A credential with only a payout role cannot create checkouts, and the reverse. Wallets, wallet disputes and payment requests need their own permission; see Wallets, wallet disputes and payment requests. See Permissions.

How a payout works

You fund a ledger account: your balance with Payment Labs, in one currency. List Ledger Accounts returns your ledger accounts and their balances.
You create a batch, a container that groups payments (a weekly payroll, a tournament, an invoice run). The batch sets the default payment category and tax jurisdiction for its payments.
You create payments in the batch. Each payment names a payee by email and reference ID, an amount and the ledger account to pay from. A payee who is new to you gets an invitation email.
The payee onboards: identity, tax form and payment method. They do it from the invitation email or inside your site through the Payee Widget.
You submit the payment. Payment Labs charges your ledger account, withholds tax where required, converts currency, and sends the money through the payee's chosen method.
You follow the payment through its statuses with webhooks or by reading it.

How a payin works

You create a checkout for an amount and a buyer email.
The buyer pays on the hosted checkout page, in an embedded iframe, or in the Payin SDK element.
Payment Labs charges the buyer and the checkout moves to PAID.
You confirm the result on your server with the checkout-status-changed webhook or by reading the checkout, then fulfil the order.

Subscriptions follow the same model: you create a plan and an offer for a buyer, the buyer subscribes, and Payment Labs charges them on schedule. See Subscriptions.

Conventions every integration uses

Errors: the error body, status codes, and when to retry.
Idempotency and Retries: which operations are safe to repeat.
Search, Exports and Pagination: filtering, sorting and paging.
IDs, Amounts and Dates: ID formats, reference IDs, money and timestamps.
Webhooks: receive events and verify their signatures.
Tax Guide: tax jurisdictions and payment categories.

Next steps

Get a token: Environments and Authentication.
Run a quickstart end to end in sandbox: Payouts or Payins.