Get the payment component's secret
The checkout.hosted.payment_secret operation: GET /api/v1/public/checkout_sessions/{sessionId}/payment_secret in the REST API and the checkout_hosted_payment_secret tool in the MCP server.
GET
/api/v1/public/checkout_sessions/{sessionId}/payment_secretReturns what the browser's payment component needs to show and confirm the session's payment: Stripe's client
secret and the connection's publishable key, read from the processor each time. It is never stored by
Ownrecord. Call it after checkout.hosted.start_payment.
Public: the hosted page calls it with the session key.
At a glance
- REST:
GET /api/v1/public/checkout_sessions/{sessionId}/payment_secret - MCP tool:
checkout_hosted_payment_secret - Operation ID:
checkout.hosted.payment_secret - Scope: Brand
- Permission:
checkout:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: None (a public endpoint, rate-limited per IP address)
- Since: M4
Request
Path parameters
| Field | Type | Description |
|---|---|---|
sessionId | cs_… ID | The checkout session's ID (cs_…). |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
key | string | No | The session key from the hosted URL (?key=…). Required without an API key; signed-in callers with checkout:write don't need it. |
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
component | one of fake, stripe_payment_element | |
clientSecret | string | For the browser component only; never stored or logged by Ownrecord. |
publishableKey | string or null | |
intent | one of payment, setup | Confirm a payment, or set up (save) the card. |
Examples
Stripe
HTTP
GET /api/v1/public/checkout_sessions/cs_01m4tx5nj8emwbyf7y9vcf48aa/payment_secret?key=Zk3tq8Vb2xQ9mN4rP7sL1yH6cJ0wE5aD-uT_fG8hK2o
Response (200):
JSON
{
"component": "stripe_payment_element",
"clientSecret": "pi_3Q0example_secret_example",
"publishableKey": "pk_test_51Qexample",
"intent": "payment"
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
resource_not_found | 404 | No such checkout session for this brand and mode, or (on the hosted page) the session key is missing or wrong. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
checkout_session_not_open | 409 | The session is complete, expired, or a payment for it is being processed (details.status). | The session is complete, expired or waiting for a payment's outcome (details.status). Create a new session for a new purchase. |
checkout_payment_not_started | 409 | The payment step hasn't started (no payment intent yet). | Start the payment step first, so the payment can be prepared for the quoted total. |
processor_request_failed | 502 | The processor couldn't return the intent. | If retryable is true, retry with the same Idempotency-Key after a short wait; otherwise check details.code. |
It can also return these common errors: validation_failed, api_version_unsupported, scope_required, dry_run_not_supported, rate_limited, internal_error.