Customers and saved cards

A customer is a buyer you charge more than once. Save a card for a customer, and you can charge it later from your server without the buyer typing it again.

Make a customer

curl https://api.kashupay.com/v1/customers \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"jenny@example.com","name":"Jenny Rosen","metadata":{"account":"4471"}}'

Every field is optional, but a card can be saved only for a customer with an email. Saving a card for a customer without one answers 400 parameter_invalid, with param customer.

Update a customer

POST /v1/customers/{id} changes only the fields you send:

A field sent as null is cleared.
An address replaces the whole address Kashu holds.
A metadata key sent with an empty string is removed. Other keys you send are added or replaced, and keys you leave out stay.

Find a customer

GET /v1/customers lists customers, newest first. Add email to find the customers with that email.

A checkout session that names no customer makes one from the email the buyer types into the card form. Those customers are in the list too.

Save a card for a customer

Collect the card with the card form, which gives you a card token, then save it:

curl https://api.kashupay.com/v1/payment_methods \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: customer-4471-card" \
  -H "Content-Type: application/json" \
  -d '{"customer":"cu_...","token":"tok_..."}'

The answer is a payment method, with an id that starts pm_, status active, and the card's brand, last4, expiry, funding and country. Saving a card spends the token, which works once, so this endpoint requires an Idempotency-Key.

A charge with a token saves the card as well, so you often do not need this step. Payments shows both.

Charge a saved card

Name the card in payment_method when you make a payment:

const payment = await kashu("POST", "/v1/payments", {
  amount: 2500,
  currency: "USD",
  customer: "cu_...",
  payment_method: "pm_...",
}, { idempotencyKey: `renewal-${invoice.id}` });
console.log(payment.status);

List a customer's cards

GET /v1/payment_methods lists one customer's saved cards, newest first. The customer parameter is required:

curl "https://api.kashupay.com/v1/payment_methods?customer=cu_...&limit=10" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

Remove a saved card

POST /v1/payment_methods/{id}/detach detaches a card from its customer. Its status becomes detached, and it can no longer be charged.

What is not available yet

You cannot delete a customer.