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 (POST /invoices/{id}/pay is the invoice-driven entry point), PaymentMethods.

Endpoints

GET /api/v1/payments

List all payment sessions for the tenant

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

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

sortstringOptional

Field to sort by

sortDirstring · enumOptional

Sort direction

Default: ascPossible values:

statusstringOptional

Filter by status

Responses

200

Paginated list of payment sessions

401

API key missing or invalid

application/json

get/payments

HTTPcURLJavaScriptPython

GET /api/v1/payments HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

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

Create a payment session

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Header parameters

Idempotency-KeystringOptional

Idempotency key to safely retry without creating duplicates

Body

application/json

accountIdstringRequired

amountCentsintegerRequired

currencystringRequired

invoiceIdstringOptional

paymentPageSlugstringOptional

Responses

201

Payment session created

No content

400

Validation error

application/json

post/payments

HTTPcURLJavaScriptPython

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

{
  "accountId": "text",
  "amountCents": 1,
  "currency": "text",
  "invoiceId": "text",
  "paymentPageSlug": "text"
}

No content

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}

Get payment session details

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Payment session details

No content

get/payments/{id}

HTTPcURLJavaScriptPython

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

200

Payment session details

No content

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

Mark a payment session as completed

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/payments/{id}/complete

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Payment session completed

No content

post/payments/{id}/complete

HTTPcURLJavaScriptPython

POST /api/v1/payments/{id}/complete HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Payment session completed

No content

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.

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.