> 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/payments.md).

# Payments

The **Payments API** is the public surface for the platform's *payment session* model. A payment session is a short-lived, tenant-scoped record that ties together an account, an amount, an optional invoice, and the payment page (CMS slug) that will collect the funds. The collection itself happens in the gateway (Stripe Elements, Zuora hosted page, etc.); this API is the orchestrator and the audit boundary, not the card-data path.

A typical flow:

1. `POST /api/v1/payments` — create a session for `(accountId, amountCents, currency)`, optionally bound to an `invoiceId` and a `paymentPageSlug`.
2. The customer is redirected to the rendered payment page; the gateway widget completes the charge.
3. `POST /api/v1/payments/{id}/complete` — the gateway callback (or a webhook handler) marks the session complete; the corresponding invoice (if any) is settled.
4. `GET /api/v1/payments/{id}` — read the resolved session for receipts / reconciliation.

All endpoints require an API key. Writes use the `commerce` scope, reads use `read`. Card data is never accepted by this API; it always flows through the gateway directly.

`paymentPageSlug` is resolved within the tenant scope of the calling API key — page slugs are unique per tenant, not globally, so two tenants may safely reuse the same slug.

See also: [Invoices](https://docs.peakcommerce.com/developers/api-groups/invoices.md) (`POST /invoices/{id}/pay` is the invoice-driven entry point), [PaymentMethods](https://docs.peakcommerce.com/developers/api-groups/paymentmethods.md).

## Endpoints

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

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

*Notes, examples, or caveats for `POST /payment-links` go here.*

### `GET /api/v1/payments`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/payments" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Returns every payment session for the calling tenant in a single page (no cursor pagination yet). Useful for reconciliation and reporting; not intended as a customer-facing list. Filter / sort client-side by `status`, `accountId`, or `createdAt`.

Requires the `read` scope. Sessions stay in the response after completion; treat the row as immutable once `status` reaches a terminal state.

### `POST /api/v1/payments`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/payments" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Creates a new payment session. The session captures *intent*, not a charge — no funds move until the gateway widget confirms.

Provide `paymentPageSlug` to bind the session to a specific CMS-authored payment page (recommended; the rendered page knows which gateway widget to mount). Provide `invoiceId` to bind the session to an open invoice; on completion the invoice will be marked paid via the active billing adapter.

Requires the `commerce` scope. Returns `201` and a `nextActions` hint pointing to the rendered payment-page URL and `POST /payments/{id}/complete`.

### `GET /api/v1/payments/{id}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/payments/{id}" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Returns the full payment-session record including its current `status`, the linked `invoiceId` (if any), the resolved gateway transaction id once the session has completed, and the audit metadata. Safe to poll while waiting for a webhook to mark the session complete.

Requires the `read` scope.

### `POST /api/v1/payments/{id}/complete`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/payments/{id}/complete" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

Idempotent terminator for a session. Use this from the gateway success callback or from a webhook handler once the gateway confirms funds. Settles the linked invoice through the active billing adapter, writes `payment.complete` to the audit log, and emits the `payment.succeeded` event to subscribed [webhooks](https://docs.peakcommerce.com/developers/api-groups/webhooks.md).

Calling `complete` on a session that is already in a terminal state is a no-op (returns `200`). Calling it on a session whose gateway transaction has not actually succeeded is a programming error — this endpoint trusts the caller and does **not** re-verify the gateway side.

Requires the `commerce` scope.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
