Skip to main content

Save Card On File

POST 
/api/customers/:customer/payment-methods

Save a tokenized card on file for a customer. The client tokenizes the card with the processor SDK (Square / Stripe) and sends ONLY the resulting reusable token — a raw card number (PAN) or CVV is never accepted. Requires explicit, affirmative customer consent.

Required scope: customers:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token (PAT). Permission: customers.update.

Request body fields:

  • processor (string, required) — the tokenizing processor. One of: square, stripe.
  • processor_token (string, required, max 255) — the processor's reusable card token from client-side SDK vaulting (e.g. a Square card nonce or Stripe PaymentMethod id). NEVER a raw PAN or CVV.
  • processor_customer_id (string, nullable, max 255) — the processor's customer/vault id the token is attached to.
  • consent_given (required, must be accepted — true, 1, "yes", or "on") — explicit customer consent to store the card. Error when missing/false: "Explicit customer consent is required to store a card on file."
  • brand (string, nullable, max 50) — safe display card brand (e.g. Visa, Mastercard).
  • last_four (nullable, exactly 4 digits) — safe display last four of the card.
  • exp_month (integer, nullable, 1–12) — card expiry month.
  • exp_year (integer, nullable, 2020–2100) — card expiry year.
  • cardholder_name (string, nullable, max 255) — name on the card.
  • is_default (boolean, nullable) — make this the customer's default card. Defaults to false.

Returns 201 with { data: <card on file>, message: "Card saved on file." } (no token field).

Request​

Responses​

Created

Response Headers
    Content-Type