Payments

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

• GET /api/v1/payments — list

• POST /api/v1/payments — create session

• GET /api/v1/payments/{id} — retrieve

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

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

• POST /api/v1/payment-methods

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

---

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

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/payments

---

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

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

Errors

Status	When
400	Validation failed

cURL

curl -X POST https://api.example.com/api/v1/payments \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "A00000123",
    "amountCents": 4900,
    "currency": "USD"
  }'

---

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

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/payments/pmt_01H...

---

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

{
  "data": {
    "id": "pmt_01H...",
    "status": "success",
    "amountCents": 4900,
    "currency": "USD",
    "createdAt": "2026-05-02T14:01:23Z",
    "completedAt": "2026-05-02T14:05:23Z"
  },
  "nextActions": []
}

Errors

Status	When
400	Already in a terminal status
404	Not found

cURL

curl -X POST https://api.example.com/api/v1/payments/pmt_01H.../complete \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

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

{
  "data": {
    "id": "pmt_01H...",
    "status": "initiated",
    "amountCents": 4900,
    "currency": "USD",
    "invoiceId": "INV-0001",
    "createdAt": "2026-05-02T14:01:23Z"
  },
  "nextActions": [
    { "rel": "self", "method": "GET", "href": "/api/v1/payments/pmt_01H..." }
  ]
}

cURL

curl -X POST https://api.example.com/api/v1/invoices/INV-0001/pay \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "A00000123", "amountCents": 4900, "currency": "USD" }'

---

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

{
  "data": {
    "id": "pmref_01H...",
    "accountId": "A00000123",
    "type": "card",
    "lastFour": "4242",
    "isDefault": false
  },
  "message": "Payment method reference stored. Actual payment method creation should be handled by the billing provider.",
  "nextActions": [
    { "rel": "setDefault", "method": "POST", "href": "/api/v1/payment-methods/pmref_01H.../set-default" }
  ]
}

Errors

Status	When
400	accountId missing

cURL

curl -X POST https://api.example.com/api/v1/payment-methods \
  -H "Authorization: Bearer $PEAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accountId": "A00000123", "type": "card", "lastFour": "4242" }'

---

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

Mark a payment-method reference as default.

• Auth scope: commerce

Response 200

{
  "data": { "id": "pmref_01H...", "isDefault": true },
  "message": "Default payment method updated. Actual update should be handled by the billing provider.",
  "nextActions": [
    { "rel": "setDefault", "method": "POST", "href": "/api/v1/payment-methods/pmref_01H.../set-default" }
  ]
}

cURL

curl -X POST https://api.example.com/api/v1/payment-methods/pmref_01H.../set-default \
  -H "Authorization: Bearer $PEAK_API_KEY"

---

Related

• Accounts — list invoices, subscriptions, payment methods

• Subscriptions — renewals create payment sessions