# Payments

Payment submission, split payments, and refunds.

## Submit a payment for an order

 - [POST /orders/{order_id}/payments](https://tote.redocly.app/online-ordering/spec/openapi/payments/submitpayment.md): Attaches a payment to an order. Supports credit cards, debit cards, gift cards,
loyalty points, and digital wallets.

Idempotency: This endpoint requires the Idempotency-Key header. If a request
with the same key is received within 24 hours, the server returns the cached
response without re-processing the payment. Error responses are NOT cached.

Split payments: To pay with multiple tenders, submit separate payment requests
for each tender. Each request must use a different Idempotency-Key.

Ordering rules: Submit tenders in this order: loyalty points first, then gift
cards, then credit/debit cards. This maximizes non-cash tender redemption.

Sequential submission: Wait for each payment to reach a terminal state
(COMPLETED or FAILED) before submitting the next. Concurrent submissions on
the same order may produce undefined behavior.

Failure handling for split payments: If a payment fails mid-sequence,
previous successful payments remain. You must either: (a) retry the failed
tender with the same Idempotency-Key, (b) submit a different tender for the
remaining balance, or (c) cancel the order (which triggers void/refund of
all successful payments).

## Refund an order (full or partial)

 - [POST /orders/{order_id}/refunds](https://tote.redocly.app/online-ordering/spec/openapi/payments/createrefund.md): Processes a full or partial refund for an order. The server determines how
to distribute the refund across the order's payment methods using a
minimize-cash-refund strategy (non-cash tenders are refunded first).

Full refund: Set amount to the order's total paid amount.
Partial refund: Set amount to the desired refund amount.
Item-level refund: Include line_items to record which items are being
refunded (informational -- the amount field determines the refund total).

The refund amount must not exceed the order's refundable balance
(amount_paid - amount_refunded). Multiple partial refunds can be issued
until the full amount has been refunded.