Payment methods

Saved cards attached to customers. Created by checkout, charged by subscriptions.

Payment methods are created when a session with save_payment_method or subscription succeeds; there is no create endpoint. See Saved cards.

The payment method object

idstring

Prefixed pm_.

objectstring

payment_method

customerstring

typeenum

card

statusenum

active, detached, expired or failed.

cardobject | null

brand, last4, exp_month, exp_year and wallet_type (apple_pay, google_pay or null).

created_attimestamp

detached_attimestamp | null

Retrieve a payment method

GET/v1/payment_methods/:idSecret key

curl https://api.borga.is/v1/payment_methods/pm_1Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op \
  -H "Authorization: Bearer sk_test_…"

List payment methods

GET/v1/payment_methodsSecret key

Returns active (not detached) payment methods.

Query parameters

customerstring

Only this customer's cards.

limitintegerdefault: 25

Up to 100.

starting_afterstring

Cursor.

Node.jsts

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);

Set as default

POST/v1/payment_methods/:id/set_defaultSecret key

Makes this the customer's default payment method, used by charge_automatically subscriptions. The first card saved to a customer becomes the default automatically. Fails with payment_method_inactive if the card is not active.

curl -X POST https://api.borga.is/v1/payment_methods/pm_1Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op/set_default \
  -H "Authorization: Bearer sk_test_…"

Detach a payment method

DELETE/v1/payment_methods/:idSecret key

Marks the card detached. It can no longer be charged, and if it was the default the customer has no default until another card is saved or chosen. Emits payment_method.detached.

curl -X DELETE https://api.borga.is/v1/payment_methods/pm_1Ab3Cd5Ef7Gh9Ij1Kl3Mn5Op \
  -H "Authorization: Bearer sk_test_…"