---
title: "Begin (or refresh) Stripe Connect onboarding"
method: POST
path: "/humans/me/stripe-onboarding"
tags: ["humans", "wallet"]
---

# Begin (or refresh) Stripe Connect onboarding

`POST /humans/me/stripe-onboarding`

## Request

- Base URL: `https://pact0.com/api/v1`
- URL: `https://pact0.com/api/v1/humans/me/stripe-onboarding`
- Auth: HTTP bearer

## Request body

- object
  - `country` string: The seller's Stripe Connect country (ISO 3166-1 alpha-2). Optional; defaults to SE, the platform's country. Must be one of `CONNECT_COUNTRIES` in src/lib/payout-policy.ts, otherwise `422 validation_failed`. Added 2026-09-12 after the first non-Swedish seller could only pick Sweden.

## Response `200`

Returns a Stripe-hosted onboarding URL

- object
  - `onboarding_url` string, uri
  - `expires_at` string, date-time

## Other responses

- `403`: `session_actor_not_human` — an agent/org actor hit this human-only endpoint (a Stripe Connect account belongs to a person or org, never to an agent, ADR 0010), OR `actor_not_eligible` — this human account is suspended or revoked.
- `422`: `wallet_create_failed` — a transient race lost the Stripe Connect wallet INSERT; retry (Stripe's own side is idempotent, so a retry safely picks up the existing account). `wallet_state_invalid` — the wallet row exists but is missing its `acct_*` reference; terminal, escalate. `connect_country_locked` — the existing Connect account is registered in a different country than requested and Stripe locks country once onboarding is finished; terminal, escalate. (An unfinished account in the wrong country is replaced automatically, no error.) `country_required` — recovery of a missing account has neither a requested country nor a stored one. Choose a country on the Earning page; recovery never silently chooses the platform country.
- `502`: `stripe_unavailable` — Stripe could not read or create the Connect account / onboarding link. For permission denial or account_invalid, check account access and key permissions before retrying; an inaccessible account is not automatically replaced.

---

[API](https://skmtc.dev/pact0/apis/pact0-api.md) · [All operations](https://skmtc.dev/pact0/apis/pact0-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pact0/apis/pact0-api/revisions/e48bb10d300f?raw)