Connect a Stripe account

POST

/v1/settings/stripe

curl --request POST \
  --url http://localhost:8080/v1/settings/stripe \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "livemode": true, "secret_key": "example", "publishable_key": "example", "webhook_secret": "example" }'

• Local development

Saves your own Stripe keys for one mode (livemode in the body picks the mode, not the caller’s mode). Calling it again for the same mode replaces the keys. Key prefixes must match the mode: sk_test_/rk_test_ and pk_test_ for test, sk_live_/rk_live_ and pk_live_ for live. Secrets are stored encrypted and are never returned.

Hardcount then calls Stripe to check the key. A failed check still returns 200: the keys are saved and last_verified_error says why the check failed. On success, verified_at and the account fields are set, and invoices that were stuck waiting for Stripe keys are retried in the background (retries_queued gives the count).

Stripe sends payment webhooks to /v1/webhooks/stripe/{id}, where {id} is the returned id. Writes an audit row.

Authorizations

• BearerAuth

Parameters

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body^required

Media typeapplication/json

object

livemode

required

False = test-mode keys, true = live-mode keys.

boolean

secret_key

required

Secret (sk_) or restricted (rk_) key for this mode.

string

publishable_key

required

Publishable (pk_) key for this mode.

string

webhook_secret

Optional. The whsec_ signing secret of the Stripe webhook endpoint. Can be added later with PATCH.

string

Example ^generated

{
  "livemode": true,
  "secret_key": "example",
  "publishable_key": "example",
  "webhook_secret": "example"
}

Responses

200

Keys saved. Check last_verified_error to see whether Stripe accepted them.

Media typeapplication/json

object

id

required

Also the {id} in the Stripe webhook URL /v1/webhooks/stripe/{id}.

string

tenant_id

required

string

livemode

required

boolean

stripe_account_id

Set after Stripe accepted the key.

string

stripe_account_name

string

secret_key_prefix

First 12 characters of the secret key.

string

secret_key_last4

required

string

publishable_key

required

string

webhook_secret_last4

string

has_webhook_secret

required

boolean

verified_at

Last time Stripe accepted the key.

string format: date-time

last_verified_error

Why the last Stripe check failed, in Stripe’s own words (or the network error when Stripe was not reached). Empty when it passed.

string

last_verified_error_kind

What kind of failure last_verified_error is. rejected: Stripe answered and refused the key (invalid, revoked, or without access). unavailable: Stripe was not reached, or answered 429/5xx, so the key was not checked; connecting again may work. Absent when the check passed, and on keys that failed before this field existed.

string

Allowed values: rejected unavailable

created_at

required

string format: date-time

updated_at

required

string format: date-time

retries_queued

Connect response only. Number of stuck invoices being retried in the background.

integer

Example

{
  "last_verified_error_kind": "rejected"
}

400

Body is not valid JSON

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

A key has the wrong prefix for the mode. error.param names the field.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}