Payments

Payment gateways define how a cart can initialize a payment session. Payments and transactions record the operational payment lifecycle after an attempt is created.

Payment gateways

Thor supports manual, Stripe, and Stripe Connect gateway configurations through PaymentGatewayCreateInput. A gateway exposes whether it can capture and refund, and can include a cart predicate that controls availability.

Use predicates for rules that are truly known from the cart, such as currency, customer group, or total. Keep provider secrets in the gateway configuration path and out of Storefront code.

Storefront payment flow

For custom checkout:

  1. Build the cart until lines, customer details, addresses, shipping, discounts, tax, and totals are current.
  2. Query paymentGateways in the cart context and let the buyer choose an eligible gateway.
  3. Call cartPaymentSessionInitialize with the selected gateway.
  4. Use the returned payment session according to its concrete GraphQL type.
  5. Complete the cart only after the provider-side flow has reached the state required by that gateway.

Payment session types are GraphQL interfaces. Request __typename and provider-specific fragments so your client can handle each configured gateway explicitly.

Payments and transactions

A payment records intended, paid, and refunded amounts, the provider reference, gateway, method, and transactions. Admin operations support payment creation, capture, cancellation, and refunding. Check the gateway capability flags before exposing an operational action.

The order’s paymentState summarizes payment progress, including pending, authorized, paid, partially refunded, refunded, failed, balance due, and overpaid states. Use the returned state rather than inferring it from a single transaction.

Reliability

Provider operations can be ambiguous when a network failure occurs after the provider accepted a request. Retain the cart or order ID and provider reference, use idempotency features offered by the provider integration, and query the latest Thor state before retrying a capture or refund.

Never log payment credentials or raw provider payloads containing sensitive payment data.

API reference