---
id: api
title: API reference
summary: Every route your server calls, generated from the OpenAPI document so it cannot drift.
faces: ["public", "agent"]
section: back-end
group: API reference
slug: reference
order: 10
next: ["api-checkout-sessions"]
---
# API reference

These are the routes your own server calls. The routes the checkout calls from the shopper's browser are in
[Routes the checkout calls for you](/js/routes).

To take your first payment from a server, start with the Server API panel of the
[Quickstart](/quickstart) — it creates a session with the same route documented here, and hands it to the
browser.

**Authentication.** Your secret key in `X-Ripper-Api-Key`, from an environment variable, server-side only.
Never put a secret key in a page, an app or a repository. The Stripe-compatible routes take the same key as
a bearer token instead, because that is what a Stripe client sends.

**Idempotency.** Every write takes `Rip-Idempotency-Key`. Use a new key for each logical create. After a
refusal a new key is always safe, because the refused request created nothing. After a timeout it is the
opposite: reuse the same key, because that request may have created a session and the key is what gives it
back. A corrected body is a different request and needs its own key. `idempotency_key_reused` covers two
situations — a key already used for a different request, and a key whose first request is still running — so
do not branch on the code alone.

**Shapes.** Wire JSON is snake_case throughout, enums are strings, and nulls are written rather than omitted,
so a field you can read once you can always read. The SDK is camelCase; that difference is deliberate and
stated once here.

**The document itself** is published at [/openapi.json](/openapi.json) and its source is
`docs/api/openapi.yaml`. Everything below, and every page in this section, is generated from it.

<!-- generated from docs/api/openapi.yaml — edit the spec, not this -->

| group | route | what it does | operation id |
|---|---|---|---|
| Checkout sessions | `POST /v1/checkout/sessions` | Create a checkout session | `createCheckoutSession` |
| Checkout sessions | `GET /v1/checkout/sessions/{session_id}` | Retrieve a checkout session | `getCheckoutSession` |
| Payments | `GET /v1/payments/{payment_id}` | Retrieve a payment | `getPayment` |
| Stripe compatibility | `POST /v1/compat/stripe/payment_intents` | Create a PaymentIntent (Stripe-compatible) | `createStripePaymentIntent` |
| Stripe compatibility | `GET /v1/compat/stripe/payment_intents/{session_id}` | Retrieve a PaymentIntent (Stripe-compatible) | `getStripePaymentIntent` |
| Webhook deliveries | `GET /v1/webhooks/deliveries` | List webhook deliveries | `listWebhookDeliveries` |
| Webhook deliveries | `POST /v1/webhooks/deliveries/{delivery_id}/replay` | Replay a webhook delivery | `replayWebhookDelivery` |
| Webhook endpoints | `POST /v1/webhooks/endpoints` | Create a webhook endpoint | `createWebhookEndpoint` |
| Webhook endpoints | `DELETE /v1/webhooks/endpoints/{endpoint_id}` | Delete a webhook endpoint | `deleteWebhookEndpoint` |
| Webhook endpoints | `GET /v1/webhooks/endpoints` | List webhook endpoints | `listWebhookEndpoints` |

<!-- end generated -->