Payments

Authenticated API

Payment endpoints require a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/payments/*.

Create Payment

POST /v1/commerce/payments

Process a payment for an order.

Request

Field	Type	Required	Description
order_id	string (UUID)	No	Order to pay for
amount	number	Yes	Payment amount
currency	string	Yes	ISO 4217 currency code (e.g., "USD")
payment_method_id	string	Yes	Stripe or Square payment method token
capture	boolean	No	true to charge immediately, false for auth-only (default: true)
idempotency_key	string	No	Unique key for safe retries
metadata	object	No	Custom metadata

Example

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "amount": 26.98,
    "currency": "USD",
    "payment_method_id": "pm_card_visa",
    "capture": true,
    "idempotency_key": "pay-abc123"
  }'

Response

{
  "payment_id": "pay-uuid",
  "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
  "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "amount": 26.98,
  "currency": "USD",
  "status": "captured",
  "processor": "stripe",
  "processor_transaction_id": "pi_3abc123...",
  "requires_action": false,
  "client_secret": null,
  "captured_at": "2026-02-19T15:35:00Z",
  "refunded_at": null,
  "metadata": {},
  "created_at": "2026-02-19T15:35:00Z",
  "updated_at": "2026-02-19T15:35:00Z"
}

Create Payment Intent

POST /v1/commerce/payments/intent

Create a Stripe PaymentIntent for client-side confirmation (3D Secure, Apple Pay, etc.).

Field	Type	Required	Description
amount	number	Yes	Payment amount
currency	string	Yes	Currency code
order_id	string (UUID)	No	Order UUID
customer_id	string	No	Stripe customer ID
payment_method_types	array of strings	No	e.g., ["card", "apple_pay"]

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/payments/intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "amount": 26.98,
    "currency": "USD",
    "order_id": "ORDER_ID"
  }'

Refund Payment

POST /v1/commerce/payments/:payment_id/refund

Field	Type	Required	Description
amount	number	Yes	Refund amount (can be partial)
reason	string	No	"guest_complaint", "mistake", "fraud"
idempotency_key	string	No	Unique key for safe retries

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/payments/PAYMENT_ID/refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "amount": 14.99,
    "reason": "guest_complaint"
  }'

Adjust Tip

POST /v1/commerce/payments/:payment_id/tip

Adjust the tip on an existing payment (common for post-meal tip adjustments on signed receipts).

Field	Type	Required	Description
tip_amount_cents	integer	Yes	Tip amount in cents (e.g., 500 = $5.00)

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/payments/PAYMENT_ID/tip \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"tip_amount_cents": 500}'

Get Payment

GET /v1/commerce/payments/:payment_id

curl https://dev.api.olympuscloud.ai/v1/commerce/payments/PAYMENT_ID \
  -H "Authorization: Bearer $TOKEN"

Payment Status Values

Status	Description
pending	Payment created, not yet processed
processing	3D Secure verification in progress
authorized	Auth-only, not yet captured
captured	Charge completed successfully
partially_refunded	Partial refund issued
refunded	Fully refunded
failed	Payment failed
cancelled	Payment cancelled before capture