> 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](/developers/api-groups/invoices.md) (`POST /invoices/{id}/pay` is the invoice-driven entry point), [PaymentMethods](/developers/api-groups/paymentmethods.md).

## Endpoints

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/payments" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/payments" method="post" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/payments/{id}" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/payments/{id}/complete" method="post" %}
<https://api.peakcommerce.com/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](/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 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/payments.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.