saleor-payments

# Saleor Payment Processing

## Before writing code

**Fetch live docs**:
1. Web-search `site:docs.saleor.io transaction payment flow` for the transaction-based payment model
2. Web-search `site:docs.saleor.io payment app sync webhooks` for payment App implementation patterns
3. Web-search `site:docs.saleor.io transaction events CHARGE_REQUESTED` for transaction event types
4. Fetch `https://docs.saleor.io/docs/developer/payments` and review the full payment lifecycle
5. Web-search `site:docs.saleor.io refund transactionRequestAction` for refund processing flow
6. Fetch `https://docs.saleor.io/docs/developer/app-store/apps/stripe` and review Stripe App integration patterns

## Transaction Payment Flow

Saleor uses a transaction-based payment model (replacing the legacy `Payment` model):

| Step | Component | Description |
|------|-----------|-------------|
| 1. List gateways | `checkout.availablePaymentGateways` | Query available payment Apps for the checkout |
| 2. Initialize session | `transactionInitialize` | Send payment request to the payment App |
| 3. Process (if needed) | `transactionProcess` | Handle additional steps (3DS, redirect) |
| 4. Transaction events | Automatic | Payment App reports events via webhooks |
| 5. Complete checkout | `checkoutComplete` | Finalize order after successful payment |

> The transaction flow is designed for asynchronous payment processing. The payment App controls the actual charge timing and reports results back via transaction events.

## Transaction Events

Transaction events track the lifecycle of a payment:

### Request Events (Saleor to Payment App)

| Event Type | Description |
|------------|-------------|
| `AUTHORIZATION_REQUEST` | Request to authorize (hold) funds |
| `CHARGE_REQUEST` | Request to capture payment |
| `REFUND_REQUEST` | Request to refund payment |
| `CANCEL_REQUEST` | Request to void/cancel authorization |

### Success Events (Payment App to Saleor)

| Event Type | Description |
|------------|-------------|
| `AUTHORIZATION_SUCCESS` | Funds successfully authorized |
| `CHARGE_SUCCESS` | Payment successfully captured |
| `REFUND_SUCCESS` | Refund successfully processed |
| `CANCEL_SUCCESS` | Authorization successfully cancelled |

### Failure Events (Payment App to Saleor)

| Event Type | Description |
|------------|-------------|
| `AUTHORIZATION_FAILURE` | Authorization failed |
| `CHARGE_FAILURE` | Charge failed |
| `REFUND_FAILURE` | Refund failed |
| `CANCEL_FAILURE` | Cancellation failed |

### Action Required Events

| Event Type | Description |
|------------|-------------|
| `AUTHORIZATION_ACTION_REQUIRED` | Additional customer action needed (e.g., 3DS) |
| `CHARGE_ACTION_REQUIRED` | Additional step required to complete charge |

> **Fetch live docs** for the complete `TransactionEventTypeEnum` -- additional event types may exist for pending states and information events.

## Payment App Pattern

Payment processing in Saleor is handled by Apps that implement sync webhooks:

| Component | Description |
|-----------|-------------|
| Payment App | A Saleor App that handles payment gateway communication |
| Sync webhooks | Synchronous webhook calls from Saleor to the App |
| Transaction events | App reports payment status back to Saleor |
| Gateway config | Per-channel payment gateway configuration |

### Key Sync Webhook Events

| Webhook Event | When Triggered | Expected Response |
|---------------|----------------|-------------------|
| `PAYMENT_GATEWAY_INITIALIZE_SESSION` | When storefront queries payment gateways | Gateway configuration and client-side data |
| `TRANSACTION_INITIALIZE_SESSION` | On `transactionInitialize` mutation | Payment session data (e.g., client secret) |
| `TRANSACTION_PROCESS_SESSION` | On `transactionProcess` mutation | Updated payment status and next actions |
| `TRANSACTION_CHARGE_REQUESTED` | On `transactionRequestAction` with `CHARGE` | Charge result event |
| `TRANSACTION_REFUND_REQUESTED` | On `transactionRequestAction` with `REFUND` | Refund result event |
| `TRANSACTION_CANCELATION_REQUESTED` | On `transactionRequestAction` with `CANCEL` | Cancellation result event |

### Payment App Implementation Pattern

A payment App must:

| Step | Description |
|------|-------------|
| 1. Register webhooks | Subscribe to the sync webhook events above |
| 2. Handle initialize | Create payment session with the gateway (e.g., Stripe PaymentIntent) |
| 3. Return session data | Send client-side data back (e.g., `clientSecret` for Stripe Elements) |
| 4. Handle process | Process additional steps and return updated status |
| 5. Report events | Use `transactionEventReport` to report async payment updates |
| 6. Handle actions | Process charge, refund, and cancel requests |

## Transaction Actions

Staff and Apps can request actions on existing transactions:

| Action | Mutation | Description |
|--------|----------|-------------|
| Charge | `transactionRequestAction` with `CHARGE` | Capture authorized funds |
| Refund | `transactionRequestAction` with `REFUND` | Refund charged amount |
| Cancel | `transactionRequestAction` with `CANCEL` | Void authorization |

### Manual Transaction Creation

For manual or offline payments:

| Mutation | Purpose |
|----------|---------|
| `transactionCreate` | Create a transaction record manually |
| `transactionUpdate` | Update transaction details |
| `transactionEventReport` | Report payment events from external systems |

## Refund Flow

Saleor implements a two-step refund process:

| Step | Mutation | Description |
|------|----------|-------------|
| 1. Grant refund | `orderGrantRefundCreate` | Merchant decides refund amount or lines |
| 2. Process refund | `transactionRequestAction` with `REFUND` | Payment App processes the actual refund |

### Grant Refund Options

| Option | Description |
|--------|-------------|
| Amount-based | Specify a flat refund amount |
| Line-based | Specify order lines and quantities to refund |
| Shipping refund | Include shipping cost in the refund |
| Reason | Optional text reason for the refund |

> The grant-then-process pattern allows merchants to review and approve refunds before the payment is actually reversed.

## Legacy Payments (Deprecated)

| Legacy Mutation | Replacement |
|-----------------|-------------|
| `checkoutPaymentCreate` | `transactionInitialize` |
| `checkoutComplete` (with payment data) | `transactionProcess` + `checkoutComplete` |
| `orderCapture` | `transactionRequestAction` with `CHARGE` |
| `orderRefund` | `orderGrantRefundCreate` + `transactionRequestAction` |
| `orderVoid` | `transactionRequestAction` with `CANCEL` |

> Legacy payment mutations are deprecated. All new integrations should use the transaction-based flow. Existing integrations should migrate to transactions.

## Stripe Integration Pattern

The official Saleor Stripe App follows this flow:

| Step | Client | Server |
|------|--------|--------|
| 1. Initialize | Call `transactionInitialize` | App creates Stripe PaymentIntent |
| 2. Client secret | Receive `data.clientSecret` | -- |
| 3. Confirm | Use Stripe.js to confirm payment | -- |
| 4. Process | Call `transactionProcess` if needed | App checks PaymentIntent status |
| 5. Webhook | -- | Stripe webhook updates transaction |

## Adyen Integration Pattern

The official Saleor Adyen App follows a similar pattern:

| Step | Client | Server |
|------|--------|--------|
| 1. Initialize | Call `transactionInitialize` | App creates Adyen session |
| 2. Session data | Receive Adyen Drop-in config | -- |
| 3. Submit | Use Adyen Web Components | -- |
| 4. Process | Call `transactionProcess` with result | App verifies with Adyen |
| 5. Webhook | -- | Adyen webhook updates transaction |

## Best Practices

- Use the transaction-based flow for all new payment integrations (not legacy payments)
- Implement idempotency keys on `transactionInitialize` to prevent duplicate charges
- Handle `ACTION_REQUIRED` events for 3DS and redirect-based payment methods
- Use `transactionEventReport` for webhook-based async payment updates from gateways
- Separate grant refund (business decision) from payment refund (gateway action)
- Test payment flows with gateway sandbox/test modes before going live
- Subscribe to both success and failure events for comprehensive error handling
- Store gateway-specific data in transaction `metadata` for debugging
- Validate `checkout.totalPrice` matches the amount passed to `transactionInitialize`
- Use channel-specific payment gateway configuration for multi-channel setups

Fetch the Saleor payment and transaction documentation for exact webhook payloads, event types, and App implementation patterns before implementing.