Skip to content
Docs
APISign inStart free

Payment methods

Cards your customers save at your processor, so subscriptions can charge renewals, upgrades and retries without the customer coming back.

A payment method is a card (or another method your processor supports) that a customer saved for later payments. Subscriptions that collect automatically charge it for renewals, upgrades and retries, without the customer being there. The card itself stays at your processor: Ownrecord keeps the processor's reference, the card brand, its last four digits, its expiry and its country, never the number. A saved method belongs to the processor connection it was saved with: a subscription keeps charging it there, even while that connection is degraded, until the customer saves another method. With Mollie, what is saved is a mandate (cst_…/mdt_…): a card mandate, or a SEPA Direct Debit mandate after an iDEAL or Bancontact payment.

How a card gets saved

  • Subscription checkout. When a customer pays the first invoice in a checkout session in subscription mode, the payment also saves the card for later (an off-session payment intent). With a trial, the page saves the card without charging it.
  • Setup checkout. A session in setup mode only saves a card. POST /api/v1/subscriptions answers with such a page (paymentSetup.url) when a subscription should be charged automatically and the customer has no card yet. You can also create one yourself for a customer whose card expired:
HTTP
POST /api/v1/checkout/sessions

{ "mode": "setup", "customer": "cus_01m4…", "successUrl": "https://app.example/billing" }

The method is saved when the processor confirms it, through its webhook, and payment_method.attached is sent to your webhooks. A card is saved once per customer: saving the same card again returns the method already saved.

The default method

Each customer has at most one default method. A newly saved card becomes the default, and the previous default stays saved. A subscription charges its own defaultPaymentMethodId when it has one, and the customer's default otherwise.

  • GET /api/v1/customers/{customerId}/payment_methods lists a customer's methods (add includeDetached=true for removed ones).
  • POST /api/v1/payment_methods/{id}/set_default makes another saved method the default.
  • DELETE /api/v1/payment_methods/{id} detaches a method: it's never charged again and stops being the default. The record stays, with detachedAt, so past payments still show the card they used. The processor detaches it too.

Reading methods needs customers:read; changing them needs customers:write. Changes send payment_method.updated and payment_method.detached.

Charging a saved card

Ownrecord charges a saved card only for an open invoice of a subscription: the first invoice, an upgrade's invoice, or later a renewal or a retry. The charge is made after the invoice is safely recorded, with an idempotency key per invoice and attempt, so a retry never charges twice. The result arrives from the processor's webhook: a successful charge marks the invoice paid; a declined one leaves it open for collection to retry.

In development and tests the fake processor's test cards stand in for real ones: pm_fake_visa is accepted, and pm_fake_decline is declined.