Methods to manage and update credit cards stored on a customer's account. The following examples assume an account is assigned to the session by either logging in or creating an account.

List saved credit cards

Use to get a list of credit cards on file for the account. These are stored automatically when a non-guest user checks out and chooses to save their information for later.

Returns all saved credit cards, with offset pagination using limit and page.

List saved credit cards
await swell.account.listCards()

Create a new credit card

Use to save a tokenized credit card to the account for future use. Swell accepts Stripe card tokens and payment methods from Stripe, as well as payment methods from Braintree.

Create an account card with a Stripe payment method.

Stripe payment method token
await swell.account.createCard({
  gateway: 'stripe',
  token: 'pm_...',
  // If the payment method is not already attached to a customer in Stripe,
  // passing `stripe_customer` will automatically attach it to the customer.
  stripe_customer: 'cus_MuTOALQlOD1SKv',
  billing: {
    name: 'Julia Sanchez',
    address1: 'Apartment 16B',
    address2: '2602 Pinewood Drive',
    city: 'Jacksonville',
    state: 'FL',
    zip: '32216',
    country: 'US',
    phone: '904-504-4760'
  },
});

Create an account card with a Stripe card token.

Stripe card token
await swell.account.createCard({
  gateway: 'stripe',
  token: 'card_...',
  stripe_token: 'card_1Nuc0kJWwXLFlFUJZfG6yD9f',
  stripe_customer: 'cus_MuTOALQlOD1SKv', // Required if this card is attached to a Stripe customer.
  billing: {
    name: 'Julia Sanchez',
    address1: 'Apartment 16B',
    address2: '2602 Pinewood Drive',
    city: 'Jacksonville',
    state: 'FL',
    zip: '32216',
    country: 'US',
    phone: '904-504-4760'
  },
});

Create an account card with a Braintree payment method.

Braintree payment method token
await swell.account.createCard({
  gateway: 'braintree',
  token: 'ftvymsam',
  // If not passed, the Swell account ID will be used instead.
  gateway_customer: '63b3fdfed87db42c15d878bf',
  billing: {
    name: 'Julia Sanchez',
    address1: 'Apartment 16B',
    address2: '2602 Pinewood Drive',
    city: 'Jacksonville',
    state: 'FL',
    zip: '32216',
    country: 'US',
    phone: '904-504-4760'
  },
  // Required for Braintree
  $vault: true,
});

When creating a card with a token, `brand`, `last4`, `exp_month`, and `exp_year` are set automatically by the gateway.

Update an existing card

Used to update information on an existing card on file by ID.

The details you can change are the expiry, through exp_month and exp_year, and the card's billing details. The token, brand, last four digits, and fingerprint are set when the card is tokenized and are not changed here.

Swell updates the stored card, then sends the change on to the payment gateway holding it. What the gateway accepts differs:

  • stripe: the billing name, phone, and address, plus the expiry month and year. Only cards stored as Stripe payment methods can be updated. A card saved as an older Stripe card token returns an error stating that updating details for this card is not supported.
  • braintree: the cardholder name, taken from the billing name, the billing address, the expiry month and year, and cvc. Braintree re-verifies the card as part of the update.
  • Other gateways: updating card details at the gateway is not implemented, so only the card stored in Swell changes.

A gateway that rejects the change does not fail the request. The stored card in Swell is updated either way and the gateway error is logged, so the two can end up holding different details.

When the card being updated is the account's default, the account's own billing details are updated from the same request.

Update an existing card
await swell.account.updateCard('5c15505200c7d14d851e510f', {
  exp_month: 11,
  exp_year: 2050,
  billing: {
    name: 'Julia Sanchez',
    address1: 'Apartment 16B',
    address2: '2602 Pinewood Drive',
    city: 'Jacksonville',
    state: 'FL',
    zip: '32216',
    country: 'US',
    phone: '904-504-4760'
  }
})

Delete a credit card

Use to remove a saved credit card from the account by ID.

Delete a credit card
await swell.account.deleteCard('5c15505200c7d14d851e510f')

Update a default card

When fetching an account, the default payment method is listed account.billing.account_card_id. The account's default card can be updated by passing the desired card ID to account.billing.account_card_id

Update the default card
import swell from 'swell-js'
swell.init('my-store', 'public-key')

const account = await swell.account.get()

Swell supports deleting the default card. If the default card that is deleted is associated with an active subscription, it will remain associated with the subscription unless the subscription itself is modified.