Saved cards

Borga can save a card at the end of a successful checkout. The card is tokenised by the processor, Borga stores only the token plus brand, last four digits and expiry, and the result is a PaymentMethod (pm_…) attached to a Customer (cus_…).

Saved cards are used by subscriptions, which charge the customer's default payment method every period without the payer being present.

Save a card during checkout

Create a customer, then a session with customer and save_payment_method: true. The session can charge a real amount for a purchase, or a small amount if you only want to collect the card.

const customer = await borga.customers.create({
  email: "anna@example.is",
  name: "Anna Jónsdóttir",
});

const session = await borga.paymentSessions.create({
  amount: 2990,
  currency: "ISK",
  customer: customer.id,
  save_payment_method: true, // tokenise the card after this payment
  return_url: "https://yoursite.is/account/cards?saved=1",
  cancel_url: "https://yoursite.is/account/cards",
});

When the payment succeeds, Borga tokenises the card and sends payment_method.attached with the PaymentMethod as data. Store data.id if you need to refer to the card later. If you did not pass customer, Borga creates one from the email the payer typed at checkout.

Sessions with subscription save the card automatically; you do not need to set save_payment_method.

Manage saved cards

const { data: cards } = await borga.paymentMethods.list({
  customer: "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz",
});

for (const pm of cards) {
  console.log(pm.id, pm.card?.brand, pm.card?.last4, pm.status);
}

// Choose which card subscriptions charge.
await borga.paymentMethods.setDefault(cards[0].id);

// Remove a card the customer no longer wants on file.
await borga.paymentMethods.detach(cards[1].id);

• list returns the customer's active cards.
• set_default chooses which card subscriptions charge. The first saved card becomes the default automatically.
• detach removes a card. Detached cards cannot be charged again and stay visible with status: "detached" for your records.

A PaymentMethod's card object has brand, last4, exp_month, exp_year and wallet_type (apple_pay or google_pay when the card came from a wallet). Expired cards move to status: "expired".

Security

Borga never sees the card number. The processor returns an opaque recurring token that is valid only for your merchant, and Borga stores it encrypted. Nothing in the API returns the token.