# Payments

## Payment lifecycle

created → authorized → captured
       ↘             ↘ refunded / partially_refunded
        → cancelled
        → failed

A sale skips authorization and goes directly to captured in one call.

## Create a payment

POST /v1/payments
Authorization: Bearer sk_live_...
Content-Type: application/json

{
  "amount_minor": 5000,
  "currency": "USD",
  "method": "card",
  "processor": "stripe",
  "customer_id": "01927b3e-...",
  "description": "Pro plan subscription",
  "idempotency_key": "pay_sub_june_2026"
}

amount_minor is always in the currency's minor unit (cents for USD).

## Capture

Capture an authorized payment:

POST /v1/payments/{id}/capture

## Cancel

Cancel a pending or authorized payment:

POST /v1/payments/{id}/cancel

## Refund

Refund fully or partially:

POST /v1/payments/{id}/refunds
Content-Type: application/json

{
  "amount_minor": 2500,
  "reason": "customer_request",
  "idempotency_key": "refund_order_1234_1"
}

Omit amount_minor to refund the full remaining amount.

## Idempotency

Always pass a unique idempotency_key on POST requests. Replaying the same key within 24 hours returns the cached response — safe to retry on network failures.

## Scopes required

Operation
Scope

Create, capture, cancel, refund
payment:write

Retrieve, list
payment:read