> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-groups/paymentmethods.md).

# 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`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/accounts/{id}/payment-methods" method="get" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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](/developers/api-groups/accounts.md)).

Requires the `read` scope.

### `POST /api/v1/payment-methods`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/payment-methods" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

**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`](#post-apiv1payment-methodsidset-default) to make it the default.

Requires the `commerce` scope.

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/payment-methods/{id}/set-default" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

**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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.peakcommerce.com/developers/api-groups/paymentmethods.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.