Payments

Payments go through a payment provider. Which providers a buyer can use is set per region. Provider IDs look like pp_<identifier>_<id>.

Concepts

Concept	Meaning
Payment collection	The amount to collect for a cart or an order.
Payment session	One attempt to pay with one provider, inside a collection. Holds the provider's data, such as a client secret.
Payment	Created when a session is authorized. Captured and refunded from here.

Create a payment collection with cart_id.
Create a payment session with a provider_id enabled in the cart's region. Use the session's data to run the provider's own UI.
Complete the cart. This authorizes the session. See Carts and checkout.

List payment providers with region_id to show the choices.
Create the session again if the cart total changes after step 2.
A provider can report pending_authorization for flows confirmed later by webhook. The order is placed, and the payment follows.

Action	Admin call
Capture an authorized payment, fully or partly	`POST /admin/payments/{id}/capture`
Refund a captured payment, with an optional reason	`POST /admin/payments/{id}/refund`
Ask for an outstanding amount on an order	Create payment collection with `order_id` and `amount`
Record a payment made outside the system	Mark as paid

Authorization and capture are separate. A common B2B setup authorizes at checkout and captures when the order ships. Waylo Commerce doesn't add payment timing rules yet, so capture is a separate merchant action.
Authorizations can expire before capture, depending on the provider. There is no reauthorize route: capture before it expires, or create a new payment collection for the amount.
Returns, exchanges, and claims can leave money owed either way. Refund or collect it with the calls above. See Orders.
Canceling an order cancels uncaptured payments and refunds captured ones.

Never send card data to the API. The provider's own UI collects it; the backend only stores the provider's references.