Create hosted one-off or recurring direct-charge Checkout

Customer Payments · createLicensePaymentRequest

Requires current Account ownership and direct Project membership. Persists immutable terms before creating direct-charge Checkout in the connected merchant account. One-off targets are explicit expiration timestamps; recurring coverage comes only from verified settled invoice lines. Quantity is one commercial License, not seats. Return visits do not settle payments. Retried responses retain the original scope/key/terms; unknown provider outcomes require reconciliation rather than a second payable Session.

POST/projects/{projectId}/licenses/{licenseId}/payments/requests

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
`projectId`	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})$
`licenseId`	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`

oneOf · CreateLicensePaymentRequest

oneOf · 2 alternatives

Alternative 1

object

No additional properties

Field	Type	Required	Description / constraints
`customerId`	string	Yes	Pattern: ^cus_[A-Za-z0-9]+$ · Maximum length: 200
`mode`	string	Yes	Constant: payment
`priceId`	string	Yes	Pattern: ^price_[A-Za-z0-9]+$ · Maximum length: 200
`validUntil`	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)))$

Alternative 2

object

No additional properties

Field	Type	Required	Description / constraints
`customerId`	string	Yes	Pattern: ^cus_[A-Za-z0-9]+$ · Maximum length: 200
`mode`	string	Yes	Constant: subscription
`priceId`	string	Yes	Pattern: ^price_[A-Za-z0-9]+$ · Maximum length: 200

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.

`201` Resource created.

Content type: application/json

object · LicensePaymentRequestResponse

No additional properties

Field	Type	Required	Description / constraints
`checkoutUrl`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 string Format: uri Alternative 2 null
`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)))$
`currency`	string	Yes
`customerId`	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)$
`interval`	string \| null	Yes
`intervalCount`	anyOf	Yes	View nested schema anyOf anyOf · 2 alternatives Alternative 1 integer Minimum: -9007199254740991 Maximum: 9007199254740991 Alternative 2 null
`lastError`	string \| null	Yes
`lastReconciledAt`	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
`licenseId`	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})$
`mode`	string	Yes	Values: payment, subscription
`paymentState`	string	Yes	Values: pending, settled, failed
`priceId`	string	Yes
`state`	string	Yes	Values: creating, open, complete, expired, needs_attention
`subscriptionBindingConfirmed`	boolean	No
`unitAmount`	string	Yes
`validUntil`	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

`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: license_not_renewable, invalid_payment_target, payment_target_already_covered, price_unsupported, recurring_source_exists, checkout_recovery_required, merchant_connection_changed, merchant_not_ready, payment_source_conflict, 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

Create hosted one-off or recurring direct-charge Checkout

Authentication

Idempotency-Key required

Parameters

Request body

`application/json`

Responses

`201` Resource created.

`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.

`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.

Create hosted one-off or recurring direct-charge Checkout

Authentication

Idempotency-Key required

Parameters

Request body

application/json

Responses

201 Resource created.

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.

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`

`201` Resource created.

`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.

`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.