Card tokens

The card tokens endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

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.

The card token object

Field	Type	About
`id`	string	An id that starts `tok_`.
`object`	string	Always `"card_token"`.
`used`	boolean
`livemode`	boolean
`created`	integer	Unix seconds.
`expires_at`	integer	Unix seconds.

{
  "id": "tok_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "card_token",
  "used": false,
  "livemode": false,
  "created": 1762473600,
  "expires_at": 1762473600
}

POST `/v1/card_tokens`

Turn the card form's single-use card into a card token. Kashu.js calls this for you.

Scope: card_tokens:write
Keys: Publishable, for the card form, or secret.
Idempotency-Key: Optional. Without one, Kashu makes one and returns it. See Idempotency.
Answers: 201 with the Card token.

Parameters

Name	In	Type	Required	About
`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

Field	Type	Required	About
`token`	string	Required	What the card form's tokenizer returned. It is kept sealed and never shown again. Up to 4096 characters.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `payments_not_enabled`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/card_tokens \
  -H "Authorization: Bearer $KASHU_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"single-use-card-from-the-form"}'

const cardToken = await kashu("POST", "/v1/card_tokens", {
  "token": "single-use-card-from-the-form"
});
console.log(cardToken.id);