---
name: set-up-payouts
description: Get a seller paid — send them to the Paddle dashboard via a magic link to add bank or Payoneer payout details, and optionally poll `GET /payout-accounts/{currency}` for status (`draft` → `submitted_for_review` → `active`).
metadata:
  internal: true
---

# Set up payout accounts

## When to use this skill

Use this skill after a seller goes live, to get them ready to be paid. A payout account is where Paddle sends a seller's earnings. Setting one up doesn't block go-live, but Paddle can't pay a seller until they have one — so prompt them right after go-live.

Payout details include sensitive bank information, so **send the seller to the Paddle dashboard to enter them** rather than collecting them yourself. The seller adds details directly with Paddle via a magic link, and your platform never touches their bank details. Payouts are set up on **live**.

## 1. Send the seller to their payout settings

Mint a magic session with the seller's **`user_api_key`**, then redirect their browser to the payout settings page.

```bash
curl -X POST https://api.paddle.com/magic-sessions/authorize \
  -H "Authorization: Bearer $USER_API_KEY"
```

A `201` returns a one-time `code` — use it once, and quickly, as it expires shortly after creation. Redirect the seller's browser to the login link with `redirect=payout_settings`:

```text
https://vendors.paddle.com/magic-sessions/login?code=Vh7nQ2pXk9Lm4Rt1Ws8Yz6Bc3Nj0Gd5Fu2Ei7Ol4KaZ&redirect=payout_settings
```

This is a **browser redirect, not a JSON request** — the code is the credential, so there's no Bearer token on the link. The seller lands logged in on the payout settings page and adds their bank or Payoneer details. See [`access-paddle-dashboard`](/partners/embed-billing/manage-sellers/magic-links) for the full magic-link reference.

## 2. Check payout status (optional)

Reflect the seller's payout status in your platform so you know when Paddle can pay them. Call `GET /payout-accounts/{balance_currency_code}` with the seller's **`api_key`**.

```bash
curl https://api.paddle.com/payout-accounts/USD \
  -H "Authorization: Bearer $SELLER_API_KEY"
```

```json
{
  "data": {
    "id": "payacc_01kd1fhj1vkv6xnwfzwq3jv5rp",
    "seller_id": "sel_01jqx8k5z9r2m4n6p8s0t2v4w6",
    "balance_currency_code": "USD",
    "status": "active",
    "payout_method": "wire_transfer",
    "bank_details": {
      "account_holder_name": "AeroEdit",
      "account_number": "********5678",
      "bank_name": "Bank of Paddle",
      "bank_country_code": "GB"
    }
  },
  "meta": { "request_id": "b0021142-3546-47f8-83fa-245162738a9f" }
}
```

A payout account moves through `draft` → `submitted_for_review` → `active` (or `rejected` / `deactivated`). The seller can be paid once `status` is `active`. There's **no webhook** for these transitions, so poll if you want to surface changes.

## Common pitfalls

- **Collecting bank details in your own UI.** Don't — send the seller to the dashboard so Paddle handles sensitive data and compliance.
- **Reusing the magic-session `code`.** It's single-use and short-lived. Mint a fresh one each time.
- **Blocking go-live on payouts.** A seller can go live before a payout account is `active`; just prompt them to complete it so they can be paid.

## Verify

- `POST /magic-sessions/authorize` returns `201` with a `code`, and the login link drops the seller on the payout settings page.
- `GET /payout-accounts/{balance_currency_code}` returns `200`; `status` becomes `active` once the seller finishes and Paddle approves.

## Related docs

- [Set up payout accounts](/partners/embed-billing/seller-go-live/payout-accounts)
- [Generate authenticated links to the Paddle dashboard](/partners/embed-billing/manage-sellers/magic-links)
- [Balance and payouts](/partners/embed-billing/get-started/concepts)