API reference
Every endpoint of the Kashu API, generated from its OpenAPI document. Send requests to https://api.kashupay.com with your API key as a Bearer token. The Node examples use the kashu() helper from the quickstart.
Download the document itself as openapi.json.
Account
| Endpoint | What it does |
|---|---|
GET /v1/account | Retrieve the account the API key belongs to. |
API keys
| Endpoint | What it does |
|---|---|
GET /v1/api_keys | List the API keys of the calling key's mode, newest first. |
POST /v1/api_keys | Create an API key in the calling key's mode. The response is the only place a secret key's token appears. |
GET /v1/api_keys/{id} | Retrieve an API key. |
POST /v1/api_keys/{id}/roll | Replace an API key with a new one of the same access. The old key ends now, or after expires_in seconds. |
POST /v1/api_keys/{id}/revoke | Revoke an API key at once. Revoking a revoked key returns it unchanged. |
Customers
| Endpoint | What it does |
|---|---|
POST /v1/customers | Create a customer. |
GET /v1/customers | List customers, newest first. |
GET /v1/customers/{id} | Retrieve a customer. |
POST /v1/customers/{id} | Update a customer. A field sent as null is cleared; an address replaces the one held. |
Card tokens
| Endpoint | What it does |
|---|---|
POST /v1/card_tokens | Turn the card form's single-use card into a card token. Kashu.js calls this for you. |
Payment methods
| Endpoint | What it does |
|---|---|
POST /v1/payment_methods | Save a card for a customer from a single-use card token. |
GET /v1/payment_methods | List a customer's saved cards, newest first. |
GET /v1/payment_methods/{id} | Retrieve a payment method. |
POST /v1/payment_methods/{id}/detach | Detach a saved card from its customer. It can no longer be charged. |
Payments
| Endpoint | What it does |
|---|---|
POST /v1/payments | Charge a saved card or a card token, or authorize it with capture_method manual. A decline is a payment with status failed. |
GET /v1/payments | List payments, newest first. |
GET /v1/payments/{id} | Retrieve a payment. |
POST /v1/payments/{id}/capture | Capture an authorized payment, once, for at most the amount held. Without an amount, all of it. |
POST /v1/payments/{id}/void | Release an authorized payment that has not been captured. |
Refunds
| Endpoint | What it does |
|---|---|
POST /v1/refunds | Refund part or all of a captured payment. Without an amount, all that is left. |
GET /v1/refunds | List refunds, newest first. |
GET /v1/refunds/{id} | Retrieve a refund. |
Subscriptions
| Endpoint | What it does |
|---|---|
POST /v1/subscriptions | Bill a customer's saved card on a schedule. The first charge is made at once; it and every renewal arrive as payments that name the subscription. |
GET /v1/subscriptions | List subscriptions, newest first. |
GET /v1/subscriptions/{id} | Retrieve a subscription. |
POST /v1/subscriptions/{id}/cancel | Cancel a subscription at the end of its period, or now with at_period_end false. Either way nothing more is billed after it ends. |
POST /v1/subscriptions/{id}/resume | Undo a cancel scheduled for the end of the period. A canceled subscription cannot be resumed. |
POST /v1/subscriptions/{id}/charge_now | Bill the subscription now if its next charge is due within 12 hours. Otherwise nothing is charged and it is returned unchanged. |
Disputes
| Endpoint | What it does |
|---|---|
GET /v1/disputes/{id} | Retrieve a dispute. |
GET /v1/disputes | List disputes, newest first. |
POST /v1/disputes/{id}/evidence | Send evidence for a dispute. Not available yet: every request answers feature_unavailable. |
POST /v1/disputes/{id}/accept | Accept a dispute and give up the disputed amount. Not available yet: every request answers feature_unavailable. |
Checkout sessions
| Endpoint | What it does |
|---|---|
POST /v1/checkout_sessions | Create a checkout session for Kashu.js to take payment for. The response is the only place its client secret appears. |
GET /v1/checkout_sessions | List checkout sessions, newest first. |
GET /v1/checkout_sessions/{id} | Retrieve a checkout session. |
POST /v1/checkout_sessions/{id}/expire | Expire an open checkout session now, so it takes no payment. A session whose payment is in flight or made cannot be expired. |
GET /v1/checkout_sessions/{id}/client | Read what the card form shows of a session, with the publishable key and the session's client secret. |
POST /v1/checkout_sessions/{id}/pay | Pay a checkout session with a card token. Kashu's card form calls this for you. |
Webhook endpoints
| Endpoint | What it does |
|---|---|
POST /v1/webhook_endpoints | Create a webhook endpoint. The response is the only place its signing secret appears. |
GET /v1/webhook_endpoints | List the webhook endpoints of the calling key's mode, newest first. |
GET /v1/webhook_endpoints/{id} | Retrieve a webhook endpoint. |
POST /v1/webhook_endpoints/{id} | Update a webhook endpoint: its URL, description and event types, or disable and enable it. |
DELETE /v1/webhook_endpoints/{id} | Delete a webhook endpoint. Kashu sends it nothing more. |
POST /v1/webhook_endpoints/{id}/roll | Replace the endpoint's signing secret at once. The response is the only place the new secret appears. |
Events
| Endpoint | What it does |
|---|---|
GET /v1/events | List events, newest first, each with its object as it is now. |
GET /v1/events/{id} | Retrieve an event, with its object as it is now. |
POST /v1/events/{id}/redeliver | Send an event again, now: to one endpoint, or to every enabled endpoint that takes its type. |