Payment methods

A payment method is a token from a payment provider, attached to a customer, used to settle their invoices. Paylera never stores PANs or CVVs — see PCI scope.

Object

{
  "id": "pm_…",
  "object": "payment_method",
  "customer_id": "cus_…",
  "type": "card",
  "is_default": true,
  "verified": true,
  "card": {
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2027,
    "country": "US",
    "funding": "credit"
  },
  "bank_account": null,
  "wallet": null,
  "billing_address": { … },
  "metadata": {},
  "created_at": "2026-05-06T12:34:56Z"
}

For non-card types, card is null and the matching object is populated:

`type`	Populated field
`card`	`card`
`bank_account`	`bank_account` (last4, routing, holder, status)
`paypal`	`wallet.kind = "paypal"`, `wallet.email`
`wallet`	`wallet.kind` ∈ `apple_pay`, `google_pay`

Endpoints

Method	Path	What
`POST`	`/v1/customers/{id}/payment-methods`	Attach.
`GET`	`/v1/customers/{id}/payment-methods`	List.
`GET`	`/v1/payment-methods/{id}`	Retrieve.
`PATCH`	`/v1/payment-methods/{id}`	Update billing address, metadata, set default.
`DELETE`	`/v1/payment-methods/{id}`	Detach.
`POST`	`/v1/payment-methods/{id}/verify`	Verify (provider-dependent).
`POST`	`/v1/setup-intents`	Create a SetupIntent for client-side capture.

Verification

Optional but recommended for high-ticket B2B:

POST /v1/payment-methods/{id}/verify

Cards: $0 / $1 auth-and-reverse depending on jurisdiction.
Bank accounts: Plaid Link if not already verified, otherwise micro-deposits.
Wallets: no-op; verified at attach.

payment_method.verified fires on completion. The synchronous response indicates pending for micro-deposits.

Default method

A customer has at most one default. Setting another method as default demotes the previous one:

PATCH /v1/payment-methods/{id}
{ "is_default": true }

Or set on attach:

{ "type": "card", "token": "pm_…", "set_as_default": true }

Subscriptions can override the customer default with their own default_payment_method_id.

Detach

DELETE /v1/payment-methods/{id}

Detaches the method from the customer. Cannot be performed on a method that’s the active default_payment_method_id of any active subscription — the API rejects with payment_method.in_use. Replace the subscription’s default first.

Card expiry

Paylera detects expiring cards (T-30 days) and emits payment_method.expiring. Send the customer a “please update your card” email or open a customer portal session. After expiry, the provider declines charges; Paylera flips the method to expired and emits payment_method.expired.

Webhook events

customer.payment_method_attached, customer.payment_method_detached, payment_method.verified, payment_method.expiring, payment_method.expired.