customerPayments

Project-isolated payments for a customer’s end users. This is separate from Korve organization billing; processor credentials are write-only.

customerPayments.getConfig

Get payment readiness and webhook configuration without returning secrets.

GET /v1/orgs/{orgId}/projects/{projectId}/payments

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Payment configuration.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`status`	string	One of: `not_configured`, `ready`, `disabled`.
`credentialConfigured`	boolean	—
`credentialHint`	string or null	—
`webhookUrl`	string or null	Format: `uri`.
`webhookSecretConfigured`	boolean	—
`credentialScopes`	string[]	Korve-side operation allowlist. This does not claim or replace the connected processor’s credential permissions.
`allowedRedirectOrigins`	string[]	—
`connectedAt`	string or null	Format: `date-time`.
`updatedAt`	string or null	Format: `date-time`.

customerPayments.connect

Connect a customer-owned payment account with a write-only restricted credential. Korve rejects full-access credentials, validates authenticated resource access, and enforces the declared Korve operation allowlist; the connected processor remains authoritative for credential permissions.

PUT /v1/orgs/{orgId}/projects/{projectId}/payments

Auth: Dashboard session only — organization API keys are rejected.
Minimum role: owner
Billing: requires active organization billing — returns 402 otherwise.
Risk: write · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`secretKey`	string	Yes	—
`webhookSecret`	string	Yes	—
`credentialScopes`	string[]	Yes	Exact Korve operation allowlist. These values constrain Korve and are not self-attested processor permission claims.
`allowedRedirectOrigins`	string[]	Yes	—

Example

curl -X PUT "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments?environment=example" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "secretKey": "examplexxxxxxxxx",
  "webhookSecret": "examplexxxxxxxxx",
  "credentialScopes": [
    "customers:write",
    "products:write",
    "prices:write",
    "checkout_sessions:write",
    "subscriptions:write"
  ],
  "allowedRedirectOrigins": [
    "https://app.acme.com/callback"
  ]
}'

Responses

Status	Description
`200`	Connected configuration.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`status`	string	One of: `not_configured`, `ready`, `disabled`.
`credentialConfigured`	boolean	—
`credentialHint`	string or null	—
`webhookUrl`	string or null	Format: `uri`.
`webhookSecretConfigured`	boolean	—
`credentialScopes`	string[]	Korve-side operation allowlist. This does not claim or replace the connected processor’s credential permissions.
`allowedRedirectOrigins`	string[]	—
`connectedAt`	string or null	Format: `date-time`.
`updatedAt`	string or null	Format: `date-time`.

customerPayments.disconnect

Revoke the local connection and permanently delete payment projections and audit events.

DELETE /v1/orgs/{orgId}/projects/{projectId}/payments

Auth: Dashboard session only — organization API keys are rejected.
Minimum role: owner
Risk: destructive · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments?environment=example" \
  -b "$SESSION"

Responses

Status	Description
`200`	Payments disconnected.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

customerPayments.listProducts

List products in ascending creation order, with UUID as the stable tie-breaker.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/products

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/products?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Product page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].name`	string	—
`items[].description`	string or null	—
`items[].active`	boolean	—
`items[].metadata`	object	At most 20 application-defined string entries. Map of string values.
`items[].createdAt`	string	Format: `date-time`.
`items[].updatedAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

customerPayments.createProduct

Create a product idempotently.

POST /v1/orgs/{orgId}/projects/{projectId}/payments/products

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`name`	string	Yes	—
`description`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/products?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront"
}'

Responses

Status	Description
`201`	Created product.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`name`	string	—
`description`	string or null	—
`active`	boolean	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

customerPayments.updateProduct

Update or archive a product idempotently.

PATCH /v1/orgs/{orgId}/projects/{projectId}/payments/products/{productId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: write

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`name`	string	Yes	—
`description`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.
`active`	boolean	No	—

Example

curl -X PATCH "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/products/$PRODUCT_ID?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront"
}'

Responses

Status	Description
`200`	Updated product.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`id`	string	Format: `uuid`.
`name`	string	—
`description`	string or null	—
`active`	boolean	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

customerPayments.listPrices

List immutable prices in ascending creation order, with UUID as the stable tie-breaker.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/prices

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/prices?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Price page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].productId`	string	Format: `uuid`.
`items[].currency`	string	Pattern: `^[a-z]{3}$`.
`items[].unitAmount`	integer	—
`items[].mode`	string	One of: `one_time`, `subscription`.
`items[].interval`	string or null	One of: `day`, `week`, `month`, `year`, `null`.
`items[].intervalCount`	integer or null	—
`items[].active`	boolean	—
`items[].metadata`	object	At most 20 application-defined string entries. Map of string values.
`items[].createdAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

customerPayments.createPrice

Create an immutable one-time or recurring price idempotently.

POST /v1/orgs/{orgId}/projects/{projectId}/payments/prices

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`productId`	string	Yes	Format: `uuid`.
`currency`	string	Yes	Pattern: `^[A-Za-z]{3}$`.
`unitAmount`	integer	Yes	—
`mode`	string	Yes	One of: `one_time`, `subscription`.
`interval`	string	No	One of: `day`, `week`, `month`, `year`.
`intervalCount`	integer	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/prices?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "productId": "00000000-0000-4000-8000-000000000001",
  "currency": "USD",
  "unitAmount": 1,
  "mode": "one_time"
}'

Responses

Status	Description
`201`	Created price.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`productId`	string	Format: `uuid`.
`currency`	string	Pattern: `^[a-z]{3}$`.
`unitAmount`	integer	—
`mode`	string	One of: `one_time`, `subscription`.
`interval`	string or null	One of: `day`, `week`, `month`, `year`, `null`.
`intervalCount`	integer or null	—
`active`	boolean	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.

customerPayments.archivePrice

Archive an immutable price. Existing subscriptions remain valid.

DELETE /v1/orgs/{orgId}/projects/{projectId}/payments/prices/{priceId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: destructive · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/prices/$PRICE_ID?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Archived price.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`id`	string	Format: `uuid`.
`productId`	string	Format: `uuid`.
`currency`	string	Pattern: `^[a-z]{3}$`.
`unitAmount`	integer	—
`mode`	string	One of: `one_time`, `subscription`.
`interval`	string or null	One of: `day`, `week`, `month`, `year`, `null`.
`intervalCount`	integer or null	—
`active`	boolean	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.

customerPayments.listCustomers

List end-customer projections in ascending creation order, with UUID as the stable tie-breaker.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/customers

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/customers?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Customer page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].email`	string	Format: `email`.
`items[].name`	string or null	—
`items[].externalId`	string or null	—
`items[].metadata`	object	At most 20 application-defined string entries. Map of string values.
`items[].createdAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

customerPayments.createCustomer

Create an end customer idempotently.

POST /v1/orgs/{orgId}/projects/{projectId}/payments/customers

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`email`	string	Yes	Format: `email`.
`name`	string	No	—
`externalId`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/customers?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@acme.com"
}'

Responses

Status	Description
`201`	Created customer.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`email`	string	Format: `email`.
`name`	string or null	—
`externalId`	string or null	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.

customerPayments.eraseCustomer

Erase end-customer personal data at the processor and redact the local projection.

DELETE /v1/orgs/{orgId}/projects/{projectId}/payments/customers/{customerId}

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: destructive · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Example

curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/customers/$CUSTOMER_ID?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Customer erased.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

customerPayments.runtimeCreateCustomer

Create an end customer from the deployed server runtime scoped to exactly one project and environment.

POST /v1/runtime/payments/customers

Auth: Project app-service token (Authorization: Bearer $APP_SERVICE_TOKEN).
Billing: requires active organization billing — returns 402 otherwise.
Risk: write

Request body

Field	Type	Required	Description
`email`	string	Yes	Format: `email`.
`name`	string	No	—
`externalId`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/runtime/payments/customers" \
  -H "Authorization: Bearer $APP_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "dev@acme.com"
}'

Responses

Status	Description
`201`	Created customer.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`email`	string	Format: `email`.
`name`	string or null	—
`externalId`	string or null	—
`metadata`	object	At most 20 application-defined string entries. Map of string values.
`createdAt`	string	Format: `date-time`.

customerPayments.listCheckouts

List checkout sessions in ascending creation order, with UUID as the stable tie-breaker. Hosted URLs are not retained or returned.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/checkouts

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/checkouts?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Checkout page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].priceId`	string	Format: `uuid`.
`items[].customerId`	string or null	Format: `uuid`.
`items[].mode`	string	One of: `one_time`, `subscription`.
`items[].quantity`	integer	—
`items[].status`	string	One of: `open`, `complete`, `expired`.
`items[].paymentStatus`	string	One of: `unpaid`, `paid`, `no_payment_required`, `refunded`, `partially_refunded`.
`items[].settlementStatus`	string	One of: `pending`, `available`, `paid`, `failed`, `not_applicable`.
`items[].url`	string or null	Hosted checkout URL. Present only on the create response. Format: `uri`.
`items[].clientReferenceId`	string or null	—
`items[].expiresAt`	string	Format: `date-time`.
`items[].createdAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

customerPayments.createCheckout

Create a hosted checkout session idempotently.

POST /v1/orgs/{orgId}/projects/{projectId}/payments/checkouts

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Billing: requires active organization billing — returns 402 otherwise.
Risk: write · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`priceId`	string	Yes	Format: `uuid`.
`quantity`	integer	No	—
`successUrl`	string	Yes	Format: `uri`.
`cancelUrl`	string	Yes	Format: `uri`.
`customerId`	string	No	Format: `uuid`.
`customerEmail`	string	No	Format: `email`.
`clientReferenceId`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/checkouts?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "priceId": "00000000-0000-4000-8000-000000000001",
  "successUrl": "https://app.acme.com/callback",
  "cancelUrl": "https://app.acme.com/callback"
}'

Responses

Status	Description
`201`	Created checkout.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`priceId`	string	Format: `uuid`.
`customerId`	string or null	Format: `uuid`.
`mode`	string	One of: `one_time`, `subscription`.
`quantity`	integer	—
`status`	string	One of: `open`, `complete`, `expired`.
`paymentStatus`	string	One of: `unpaid`, `paid`, `no_payment_required`, `refunded`, `partially_refunded`.
`settlementStatus`	string	One of: `pending`, `available`, `paid`, `failed`, `not_applicable`.
`url`	string or null	Hosted checkout URL. Present only on the create response. Format: `uri`.
`clientReferenceId`	string or null	—
`expiresAt`	string	Format: `date-time`.
`createdAt`	string	Format: `date-time`.

customerPayments.runtimeCreateCheckout

Create a hosted checkout from the deployed server runtime scoped to exactly one project and environment.

POST /v1/runtime/payments/checkouts

Auth: Project app-service token (Authorization: Bearer $APP_SERVICE_TOKEN).
Billing: requires active organization billing — returns 402 otherwise.
Risk: write · sensitive (elevated blast radius)

Request body

Field	Type	Required	Description
`priceId`	string	Yes	Format: `uuid`.
`quantity`	integer	No	—
`successUrl`	string	Yes	Format: `uri`.
`cancelUrl`	string	Yes	Format: `uri`.
`customerId`	string	No	Format: `uuid`.
`customerEmail`	string	No	Format: `email`.
`clientReferenceId`	string	No	—
`metadata`	object	No	At most 20 application-defined string entries. Map of string values.

Example

curl -X POST "https://api.korve.dev/v1/runtime/payments/checkouts" \
  -H "Authorization: Bearer $APP_SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "priceId": "00000000-0000-4000-8000-000000000001",
  "successUrl": "https://app.acme.com/callback",
  "cancelUrl": "https://app.acme.com/callback"
}'

Responses

Status	Description
`201`	Created checkout.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (201)

Field	Type	Description
`id`	string	Format: `uuid`.
`priceId`	string	Format: `uuid`.
`customerId`	string or null	Format: `uuid`.
`mode`	string	One of: `one_time`, `subscription`.
`quantity`	integer	—
`status`	string	One of: `open`, `complete`, `expired`.
`paymentStatus`	string	One of: `unpaid`, `paid`, `no_payment_required`, `refunded`, `partially_refunded`.
`settlementStatus`	string	One of: `pending`, `available`, `paid`, `failed`, `not_applicable`.
`url`	string or null	Hosted checkout URL. Present only on the create response. Format: `uri`.
`clientReferenceId`	string or null	—
`expiresAt`	string	Format: `date-time`.
`createdAt`	string	Format: `date-time`.

customerPayments.listSubscriptions

List webhook-reconciled subscriptions in ascending creation order, with UUID as the stable tie-breaker.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/subscriptions

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/subscriptions?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Subscription page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].customerId`	string or null	Format: `uuid`.
`items[].priceId`	string or null	Format: `uuid`.
`items[].status`	string	One of: `incomplete`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`.
`items[].cancelAtPeriodEnd`	boolean	—
`items[].currentPeriodEnd`	string or null	Format: `date-time`.
`items[].createdAt`	string	Format: `date-time`.
`items[].updatedAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

customerPayments.cancelSubscription

Cancel a subscription now or at the end of its current period.

POST /v1/orgs/{orgId}/projects/{projectId}/payments/subscriptions/{subscriptionId}/cancel

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: admin
Risk: write · sensitive (elevated blast radius)

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.

Request body

Field	Type	Required	Description
`atPeriodEnd`	boolean	Yes	—

Example

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/subscriptions/$SUBSCRIPTION_ID/cancel?environment=example" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "atPeriodEnd": true
}'

Responses

Status	Description
`200`	Updated subscription.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`id`	string	Format: `uuid`.
`customerId`	string or null	Format: `uuid`.
`priceId`	string or null	Format: `uuid`.
`status`	string	One of: `incomplete`, `trialing`, `active`, `past_due`, `canceled`, `unpaid`.
`cancelAtPeriodEnd`	boolean	—
`currentPeriodEnd`	string or null	Format: `date-time`.
`createdAt`	string	Format: `date-time`.
`updatedAt`	string	Format: `date-time`.

customerPayments.listEvents

List bounded, deduplicated payment lifecycle events in descending receipt order, with UUID as the stable tie-breaker.

GET /v1/orgs/{orgId}/projects/{projectId}/payments/events

Auth: Organization API key (Authorization: Bearer korve_...) or dashboard session.
Minimum role: member
Risk: read

Query parameters

Name	Type	Required	Description
`environment`	string	No	Pattern: `^[a-z][a-z0-9-]{0,38}$`.
`cursor`	string	No	—
`limit`	integer	No	—

Example

curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/payments/events?environment=example" \
  -H "Authorization: Bearer korve_..."

Responses

Status	Description
`200`	Event page.
`402`	Organization billing is not active.
`404`	Project or payment resource not found.
`409`	Duplicate idempotency key or conflicting resource state.
`422`	Invalid payment request.
`502`	The payment processor rejected the request.
`503`	The payment processor is temporarily unavailable.

Response body (200)

Field	Type	Description
`items`	object[]	—
`items[].id`	string	Format: `uuid`.
`items[].type`	string	—
`items[].processingStatus`	string	One of: `pending`, `processing`, `processed`, `ignored`, `failed`.
`items[].occurredAt`	string	Format: `date-time`.
`items[].receivedAt`	string	Format: `date-time`.
`nextCursor`	string or null	—

​customerPayments.getConfig

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.connect

​Query parameters

​Request body

​Example

​Responses

​Response body (200)

​customerPayments.disconnect

​Query parameters

​Example

​Responses

​customerPayments.listProducts

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.createProduct

​Query parameters

​Request body

​Example

​Responses

​Response body (201)

​customerPayments.updateProduct

​Query parameters

​Request body

​Example

​Responses

​Response body (200)

​customerPayments.listPrices

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.createPrice

​Query parameters

​Request body

​Example

​Responses

​Response body (201)

​customerPayments.archivePrice

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.listCustomers

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.createCustomer

​Query parameters

​Request body

​Example

​Responses

​Response body (201)

​customerPayments.eraseCustomer

​Query parameters

​Example

​Responses

​customerPayments.runtimeCreateCustomer

​Request body

​Example

​Responses

​Response body (201)

​customerPayments.listCheckouts

​Query parameters

​Example

​Responses

​Response body (200)

​customerPayments.createCheckout

​Query parameters

​Request body

​Example

​Responses

​Response body (201)

​customerPayments.runtimeCreateCheckout

customerPayments.getConfig

Query parameters

Example

Responses

Response body (200)

customerPayments.connect

Query parameters

Request body

Example

Responses

Response body (200)

customerPayments.disconnect

Query parameters

Example

Responses

customerPayments.listProducts

Query parameters

Example

Responses

Response body (200)

customerPayments.createProduct

Query parameters

Request body

Example

Responses

Response body (201)

customerPayments.updateProduct

Query parameters

Request body

Example

Responses

Response body (200)

customerPayments.listPrices

Query parameters

Example

Responses

Response body (200)

customerPayments.createPrice

Query parameters

Request body

Example

Responses

Response body (201)

customerPayments.archivePrice

Query parameters

Example

Responses

Response body (200)

customerPayments.listCustomers

Query parameters

Example

Responses

Response body (200)

customerPayments.createCustomer

Query parameters

Request body

Example

Responses

Response body (201)

customerPayments.eraseCustomer

Query parameters

Example

Responses

customerPayments.runtimeCreateCustomer

Request body

Example

Responses

Response body (201)

customerPayments.listCheckouts

Query parameters

Example

Responses

Response body (200)

customerPayments.createCheckout

Query parameters

Request body

Example

Responses

Response body (201)

customerPayments.runtimeCreateCheckout