Payment methods
The payment methods endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.
The payment method object
| Field | Type | About |
|---|
id | string | An id that starts pm_. |
object | string | Always "payment_method". |
type | enum | One of card. |
status | enum | One of active, detached, processing, failed. |
customer | string or null | An id that starts cu_. |
card | object or null | |
card.brand | string | |
card.last4 | string | |
card.exp_month | integer or null | |
card.exp_year | integer or null | |
card.funding | enum | One of credit, debit, prepaid, unknown. |
card.country | string or null | |
livemode | boolean | |
created | integer | Unix seconds. |
{
"id": "pm_1a2B3c4D5e6F7g8H9i0J1k2L",
"object": "payment_method",
"type": "card",
"status": "active",
"customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
"card": {
"brand": "visa",
"last4": "4242",
"exp_month": 12,
"exp_year": 2030,
"funding": "credit",
"country": "US"
},
"livemode": false,
"created": 1762473600
}
POST /v1/payment_methods
Save a card for a customer from a single-use card token.
- Scope
payment_methods:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Required. This endpoint moves money. See Idempotency.
Parameters
| Name | In | Type | Required | About |
|---|
Idempotency-Key | header | string | Required | Required. Retry with the same key and get the same result. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
| Field | Type | Required | About |
|---|
customer | string | Required | An id that starts cu_. |
token | string | Required | A card token (tok_) from Kashu's card form. This request spends it. An id that starts tok_. |
Errors
| Status | Codes |
|---|
| 400 | invalid_json, parameter_missing, parameter_invalid, parameter_unknown, api_version_invalid, idempotency_key_missing, idempotency_key_invalid, idempotency_key_reused, token_already_used, token_expired |
| 401 | api_key_missing, api_key_invalid, api_key_expired |
| 403 | livemode_unavailable, insufficient_scope, publishable_key_not_allowed, payments_not_enabled |
| 404 | resource_missing |
| 409 | idempotency_key_in_use, operation_in_progress |
| 429 | rate_limited |
| 500 | api_error |
Examples
curl https://api.kashupay.com/v1/payment_methods \
-H "Authorization: Bearer $KASHU_SECRET_KEY" \
-H "Idempotency-Key: payment-methods-create-1001" \
-H "Content-Type: application/json" \
-d '{"customer":"cu_1a2B3c4D5e6F7g8H9i0J1k2L","token":"tok_1a2B3c4D5e6F7g8H9i0J1k2L"}'
const paymentMethod = await kashu("POST", "/v1/payment_methods", {
"customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
"token": "tok_1a2B3c4D5e6F7g8H9i0J1k2L"
}, { idempotencyKey: "payment-methods-create-1001" });
console.log(paymentMethod.status);
GET /v1/payment_methods
List a customer's saved cards, newest first.
- Scope
payment_methods:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
customer | query | string | Required | An id that starts cu_. |
limit | query | integer | Optional | At least 1. Up to 100. Defaults to 10. |
cursor | query | string | Optional | |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl "https://api.kashupay.com/v1/payment_methods?customer=cu_1a2B3c4D5e6F7g8H9i0J1k2L&limit=3" \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const list = await kashu("GET", "/v1/payment_methods?customer=cu_1a2B3c4D5e6F7g8H9i0J1k2L&limit=3");
console.log(list.has_more);
GET /v1/payment_methods/{id}
Retrieve a payment method.
- Scope
payment_methods:read- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Not used. A read changes nothing.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts pm_. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Errors
Examples
curl https://api.kashupay.com/v1/payment_methods/pm_1a2B3c4D5e6F7g8H9i0J1k2L \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const paymentMethod = await kashu("GET", "/v1/payment_methods/pm_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(paymentMethod.status);
POST /v1/payment_methods/{id}/detach
Detach a saved card from its customer. It can no longer be charged.
- Scope
payment_methods:write- Keys
- Secret, or restricted with the scope below.
- Idempotency-Key
- Optional. Without one, Kashu makes one and returns it. See Idempotency.
Parameters
| Name | In | Type | Required | About |
|---|
id | path | string | Required | An id that starts pm_. |
Idempotency-Key | header | string | Optional | Optional. When absent, Kashu mints one and returns it. Up to 255 characters. |
Kashu-Version | header | string | Optional | The API version to answer in. Defaults to the key's pinned version. |
Request body
Send no body, or an empty JSON object.
Errors
Examples
curl https://api.kashupay.com/v1/payment_methods/pm_1a2B3c4D5e6F7g8H9i0J1k2L/detach \
-X POST \
-H "Authorization: Bearer $KASHU_SECRET_KEY"
const paymentMethod = await kashu("POST", "/v1/payment_methods/pm_1a2B3c4D5e6F7g8H9i0J1k2L/detach");
console.log(paymentMethod.status);