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

Returns 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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).