Create a Stripe Connect onboarding link
const url = 'https://apisandbox.puurk.com/organizations/example/merchant-account/onboarding-link';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"return_url":"https://partner.example.com/onboarding/done","refresh_url":"https://partner.example.com/onboarding/retry","uid":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apisandbox.puurk.com/organizations/example/merchant-account/onboarding-link \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "return_url": "https://partner.example.com/onboarding/done", "refresh_url": "https://partner.example.com/onboarding/retry", "uid": "example" }'Mints a Stripe Connect account link for the organization, creating the merchant account and gateway account on the first call. Send the provider to url to complete onboarding; poll GET /organizations/{oid}/merchant-account until it reports active.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Organization ID
Request Bodyrequired
Section titled “Request Bodyrequired”Redirect targets
object
Where Stripe sends the provider after onboarding. Must be absolute https, and the host must not imitate puurk.com (for example puurk.com.evil.example); puurk.com and its subdomains are allowed.
Example
https://partner.example.com/onboarding/doneWhere Stripe sends the provider if the link expires before they finish. Same rules as return_url.
Example
https://partner.example.com/onboarding/retryThe provider user the link is for. Defaults to the organization’s first owner from its roles map.
Responses
Section titled “Responses”Link created
object
Send the provider here to complete onboarding.
Stripe account links expire within minutes. Mint a new one rather than reusing an expired link.
Examplegenerated
{ "url": "example", "expires_at": "2026-04-15T12:00:00Z"}Invalid parameter (this service’s 400 code is not snake_case). One of: a blank oid; a non-object body; a missing, unparseable or non-https redirect URL; a redirect host imitating puurk.com (such as puurk.com.evil.example or mypuurk.com — puurk.com and its subdomains are allowed); a uid that is blank, not a string, or not a member of the organization; or no owner to attach the link to and no uid supplied.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}Unauthorized
forbidden — the token lacks the write action on organizations for this organization.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}not_found — the organization does not exist.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}merchant_account_active — onboarding is already complete. The current status is returned instead of a link.
The 409 body when onboarding is already complete: the standard error plus the current status.
object
setup — onboarding started but not complete. active — the organization can be priced. disabled — set by Puurk; payouts and scheduled payments stop for the organization. Onboarding only ever moves status forward to active; use charges_enabled / payouts_enabled for the live picture.
Example
{ "error": "merchant_account_active", "status": "setup"}rate_limited — too many links requested for this organization. The Retry-After header carries the wait in seconds.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}Server Error — unexpected failure creating the link.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}gateway_error — Stripe rejected the request. The gateway’s own message is never forwarded.
The standard error body. error is a stable, machine-readable code — branch on it rather than on message, which is for humans and may change.
object
Machine-readable error code.
Human-readable detail.
Example
{ "error": "merchant_account_missing", "message": "The organization has no merchant account. Complete Stripe Connect onboarding for this organization before generating pricing."}