Payment methods

The PaymentMethods API exposes the saved payment instruments on an account: cards, bank accounts, wallets. The actual card data lives in the gateway (Stripe, Zuora payment vault, etc.); this API surfaces references — last four, brand, expiry, default flag — and orchestrates which one is the default.

The two write endpoints (POST /payment-methods, POST /payment-methods/{id}/set-default) are currently stubs that record the reference locally without driving the gateway side; the production flow is to attach the payment method through the gateway widget on a payment page, then call this API to mark it default. The list endpoint, by contrast, goes through the active billing adapter for the source of truth.

Reads require the read scope; writes require commerce.

Endpoints

GET /api/v1/accounts/{id}/payment-methods

List payment methods for an account via the billing adapter

get

/accounts/{id}/payment-methods

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

Responses

200

Paginated list of payment methods

401

API key missing or invalid

application/json

404

No billing integration configured

application/json

get/accounts/{id}/payment-methods

GET /api/v1/accounts/{id}/payment-methods HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Returns every saved payment method for the account, sourced from the active billing adapter (fetchPaymentMethods). Each entry carries the gateway-side id, type (card / ach / sepa / wallet), lastFour, brand (when applicable), expMonth / expYear, and isDefault.

Use this in customer portals to render the "saved payment methods" list. For the id you'll need a valid external billing-account id (see the Accounts overview).

Requires the read scope.

POST /api/v1/payment-methods

Add a payment method reference for an account

post

/payment-methods

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Body

accountIdstringRequired

typestringOptional

lastFourstringOptional

Responses

201

Payment method added (stub)

No content

post/payment-methods

POST /api/v1/payment-methods HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "accountId": "text",
  "type": "text",
  "lastFour": "text"
}

201

Payment method added (stub)

No content

Stub. Records a payment-method reference locally for traceability. Does not create the underlying instrument in the gateway — the live flow is to capture the card / bank account on a payment page (Stripe Elements, Zuora hosted page, etc.), which attaches the instrument to the gateway customer; this endpoint then captures the metadata for portal display.

Send { accountId, type, lastFour }. The response (201) carries the local reference id. Pair with POST /payment-methods/{id}/set-default to make it the default.

Requires the commerce scope.

POST /api/v1/payment-methods/{id}/set-default

Set a payment method as the default for its account

post

/payment-methods/{id}/set-default

Authorizations

X-API-KeystringRequired

Scoped secret API key — send an sk_live_… value (keys issued before the typed format carry a bare pk_<hex> prefix and are also secret; they still work). A publishable pk_live_…/pk_test_… key is browser-safe, carries no scopes, and is refused by every endpoint in this spec with publishable_key_not_allowed. Coarse scopes: read, commerce, admin (admin covers everything below). Narrow per-resource scopes: journeys|pages :read|write|publish|delete, productsets :read|write|publish|delete, components|rules :read|write|delete, context :read (read-only context tier), catalog :read|write-native. publish is never implied by write.

Path parameters

idstringRequired

Responses

200

Default payment method set (stub)

No content

post/payment-methods/{id}/set-default

POST /api/v1/payment-methods/{id}/set-default HTTP/1.1
Host: api.peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Default payment method set (stub)

No content

Stub. Marks the local payment-method reference as the default for its account. The intent is for the call to also flip the default in the connected gateway; that part of the flow is not yet wired and must be done out of band today (or via the adapter's own API).

Requires the commerce scope. Idempotent — re-calling on an already-default reference returns 200.