Durably provision one merchant; replay contains no onboarding link

Customer Payments · setupMerchantPayments

POST/accounts/{accountId}/customer-payments/setup

Base URL: https://api.businessmode.io/v1

Authentication

Developer bearer token

The requirement above comes from this operation's OpenAPI security declaration. See Authentication.

Idempotency-Key required

Retain one UUID for this logical mutation and reuse it with the same request after an ambiguous result. See Idempotency & retries.

Parameters

Name	In	Required	Type and constraints
`accountId`	path	Yes	stringFormat: uuid · Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
`Idempotency-Key`	header	Yes	stringIdentifies one logical mutation for the 24-hour BusinessMode replay window. UUID v4 is recommended. Reuse the same value only when retrying the same request.Pattern: ^[A-Za-z0-9._~:-]{1,255}$ · Minimum length: 1 · Maximum length: 255

Request body

Required

`application/json`

anyOf · MerchantSetupRequest

anyOf · 2 alternatives

Alternative 1

object

No additional properties

Field	Type	Required	Description / constraints
`contactEmail`	string	No	Format: email · Pattern: ^(?:[A-Za-z0-9_'+\-]+\.)[A-Za-z0-9_'+\-][A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ · Maximum length: 254
`country`	string	Yes	Pattern: ^[A-Z]{2}$
`displayName`	string	Yes	Minimum length: 1 · Maximum length: 200

Alternative 2

object

No additional properties

Responses

For status codes, request IDs, and safe retry decisions, see Errors & recovery. Known-code descriptions below are operation-specific, not a complete global error enum.

`200` Successful response.

Content type: application/json

object · MerchantConnection

No additional properties

Field	Type	Required	Description / constraints
`accountId`	string	Yes	Format: uuid · Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
`cardStatus`	string	Yes	Values: unknown, active, pending, restricted, unsupported
`createdAt`	string	Yes	Format: date-time · Pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`dashboardUrl`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 string Format: uri Alternative 2 null
`displayName`	string	Yes
`id`	string	Yes	Format: uuid · Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$
`lastCheckedAt`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 string Format: date-time Pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$ Alternative 2 null
`lastError`	string \| null	Yes
`mode`	string	Yes	Values: test, live
`pausedAt`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 string Format: date-time Pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$ Alternative 2 null
`payoutsStatus`	string	Yes	Values: unknown, active, pending, restricted, unsupported
`providerClosed`	boolean	Yes
`provisioningError`	string \| null	Yes
`requirementsStatus`	string	Yes	Values: unknown, action_required, pending, clear
`state`	string	Yes	Values: active, paused
`stripeAccountId`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 string Pattern: ^acct_[A-Za-z0-9]+$ Maximum length: 200 Alternative 2 null

`400` Invalid request. Known error codes: invalid_request, idempotency_key_required, invalid_idempotency_key.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`401` Authentication failed.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`403` The authenticated human is not permitted to perform this operation. Known error codes: customer_payments_forbidden.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`409` The request conflicts with current resource state. Known error codes: merchant_context_mismatch, merchant_creation_requires_attention, merchant_identity_conflict, merchant_setup_terms_required, idempotency_request_in_progress.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`422` The Idempotency-Key was reused for a different logical request. Known error codes: idempotency_key_reused.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`429` Too many requests. Honor Retry-After before retrying with the same logical Idempotency-Key, where required. Known error codes: rate_limit_exceeded.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`500` An unexpected server error occurred.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

`503` A required operation-specific provider or PostgreSQL is unavailable. Known error codes: customer_payments_not_configured, customer_payments_unavailable.

Content type: application/json

object · ErrorResponse

No additional properties

Field Type Required Description / constraints

error

object

Yes

No additional properties

View nested schema

object

No additional properties

Field	Type	Required	Description / constraints
`code`	string	Yes	Minimum length: 1
`message`	string	Yes	Minimum length: 1

← All API operations

Company access

Manage customers

Company sales

Beyond manual work

Get started

Reference

Build

Company access

Explore the choices

Durably provision one merchant; replay contains no onboarding link

Authentication

Idempotency-Key required

Parameters

Request body

`application/json`

Responses

`200` Successful response.

`400` Invalid request. Known error codes: invalid_request, idempotency_key_required, invalid_idempotency_key.

`401` Authentication failed.

`403` The authenticated human is not permitted to perform this operation. Known error codes: customer_payments_forbidden.

`409` The request conflicts with current resource state. Known error codes: merchant_context_mismatch, merchant_creation_requires_attention, merchant_identity_conflict, merchant_setup_terms_required, idempotency_request_in_progress.

`422` The Idempotency-Key was reused for a different logical request. Known error codes: idempotency_key_reused.

`429` Too many requests. Honor Retry-After before retrying with the same logical Idempotency-Key, where required. Known error codes: rate_limit_exceeded.

`500` An unexpected server error occurred.

`503` A required operation-specific provider or PostgreSQL is unavailable. Known error codes: customer_payments_not_configured, customer_payments_unavailable.

Durably provision one merchant; replay contains no onboarding link

Authentication

Idempotency-Key required

Parameters

Request body

application/json

Responses

200 Successful response.

400 Invalid request. Known error codes: invalid_request, idempotency_key_required, invalid_idempotency_key.

401 Authentication failed.

403 The authenticated human is not permitted to perform this operation. Known error codes: customer_payments_forbidden.

409 The request conflicts with current resource state. Known error codes: merchant_context_mismatch, merchant_creation_requires_attention, merchant_identity_conflict, merchant_setup_terms_required, idempotency_request_in_progress.

422 The Idempotency-Key was reused for a different logical request. Known error codes: idempotency_key_reused.

429 Too many requests. Honor Retry-After before retrying with the same logical Idempotency-Key, where required. Known error codes: rate_limit_exceeded.

500 An unexpected server error occurred.

503 A required operation-specific provider or PostgreSQL is unavailable. Known error codes: customer_payments_not_configured, customer_payments_unavailable.

`application/json`

`200` Successful response.

`400` Invalid request. Known error codes: invalid_request, idempotency_key_required, invalid_idempotency_key.

`401` Authentication failed.

`403` The authenticated human is not permitted to perform this operation. Known error codes: customer_payments_forbidden.

`409` The request conflicts with current resource state. Known error codes: merchant_context_mismatch, merchant_creation_requires_attention, merchant_identity_conflict, merchant_setup_terms_required, idempotency_request_in_progress.

`422` The Idempotency-Key was reused for a different logical request. Known error codes: idempotency_key_reused.

`429` Too many requests. Honor Retry-After before retrying with the same logical Idempotency-Key, where required. Known error codes: rate_limit_exceeded.

`500` An unexpected server error occurred.

`503` A required operation-specific provider or PostgreSQL is unavailable. Known error codes: customer_payments_not_configured, customer_payments_unavailable.