For the complete documentation index, see llms.txt. This page is also available as Markdown.

Payments

Payment sessions track money movement: their status, amount, currency, and (when applicable) the invoice they are paying.


GET /api/v1/payments

List payment sessions.

  • Auth scope: read

Response 200

{
  "data": [
    {
      "id": "pmt_01H...",
      "status": "success",
      "amountCents": 4900,
      "currency": "USD",
      "createdAt": "2026-05-02T14:01:23Z"
    }
  ],
  "nextActions": [
    { "rel": "createPaymentSession", "method": "POST", "href": "/api/v1/payments" }
  ]
}

cURL


POST /api/v1/payments

Create a payment session. The session records intent — actual money movement is performed by the provider on the relevant payment page or adapter call. Webhooks finalize the session into a terminal state.

  • Auth scope: commerce

Body

Field
Type
Required
Description

accountId

string (1–64)

yes

[a-zA-Z0-9_-]+

amountCents

integer > 0

yes

currency

string ISO-4217 (3 upper)

yes

e.g. USD, EUR

invoiceId

string (≤255)

no

Pay a specific invoice

paymentPageSlug

string (≤255)

no

Tie session to a payment page

Response 201

Errors

Status
When

400

Validation failed

cURL


GET /api/v1/payments/{id}

Retrieve a payment session.

  • Auth scope: read

Response 200

Same shape as POST.

Errors

Status
When

404

Payment session not found

cURL


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

Force-mark a payment session as success. Use only when you have external proof of payment and are not relying on the provider's webhook.

  • Auth scope: commerce

Response 200

Errors

Status
When

400

Already in a terminal status

404

Not found

cURL


POST /api/v1/invoices/{id}/pay

Initiate payment for a specific invoice. Same body as POST /payments minus the optional fields.

  • Auth scope: commerce

Body

Field
Type
Required

accountId

string

yes

amountCents

integer > 0

yes

currency

string ISO-4217

yes

Response 201

cURL


POST /api/v1/payment-methods

Record a payment-method reference. Actual payment-method creation must happen at the billing provider; this endpoint stores the local reference (last four, type) for your own integration to display.

  • Auth scope: commerce

Body

Field
Type
Required

accountId

string

yes

type

string

no, defaults to card

lastFour

string

no, defaults to 0000

Response 201

Errors

Status
When

400

accountId missing

cURL


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

Mark a payment-method reference as default.

  • Auth scope: commerce

Response 200

cURL


  • Accounts — list invoices, subscriptions, payment methods

  • Subscriptions — renewals create payment sessions

Last updated

Was this helpful?