Shopify Payments

---
name: shopify-payments
description: Integrate Shopify payments — Shopify Payments (Stripe-powered), Payment Apps API, payment session flow, Billing API for app charges, refund processing, and PCI compliance. Use when working with Shopify payment processing.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch
---

# Shopify Payments Integration

## Before writing code

**Fetch live docs**:
1. Web-search `site:shopify.dev payments apps api` for Payment Apps API
2. Web-search `site:shopify.dev billing api app charges` for app billing
3. Web-search `site:shopify.dev shopify payments` for Shopify Payments overview
4. Web-search `site:shopify.dev payment session resolve reject` for payment session flow
5. Web-search `site:shopify.dev app subscription create usage record` for billing mutations

## Shopify Payments

Shopify's built-in payment processor (powered by Stripe):
- No third-party gateway needed
- Supports credit/debit cards, Shop Pay, Apple Pay, Google Pay
- Lower transaction fees than third-party gateways
- PCI DSS Level 1 compliant (Shopify handles compliance)

### Payment Flow

```
Customer → Checkout → Payment Method Selection → Authorization → Capture
```

- Authorization happens at checkout
- Capture happens when order is fulfilled (or immediately, based on settings)
- Auto-capture can be enabled for immediate charge

### Supported Payment Methods

| Method | Details |
|--------|---------|
| Credit/Debit cards | Visa, Mastercard, Amex, Discover |
| Shop Pay | Shopify's accelerated checkout |
| Apple Pay | On supported devices/browsers |
| Google Pay | On supported devices/browsers |
| Local methods | Varies by country (iDEAL, Bancontact, etc.) |

> **Fetch live docs** for supported payment methods by country — availability varies by region and changes over time.

## Payment Apps API

For building custom payment gateways as Shopify apps:

### Payment Session Flow

```
1. Customer selects your payment method at checkout
2. Shopify creates payment session → calls your app's payment endpoint
3. Your app processes payment with your gateway
4. Return: RESOLVE (success) or REJECT (failure)
5. Optional: REDIRECT for additional auth (3D Secure, bank redirect)
6. Optional: CONFIRM for pending/async payments
```

### Key Mutations

| Operation | Mutation | When |
|-----------|----------|------|
| Approve payment | `paymentSessionResolve` | Payment succeeded |
| Decline payment | `paymentSessionReject` | Payment failed |
| Redirect customer | `paymentSessionRedirect` | 3D Secure, bank auth |
| Confirm payment | `paymentSessionConfirm` | Async/pending payment settled |
| Approve refund | `refundSessionResolve` | Refund succeeded |
| Decline refund | `refundSessionReject` | Refund failed |
| Approve capture | `captureSessionResolve` | Manual capture succeeded |
| Decline capture | `captureSessionReject` | Manual capture failed |
| Approve void | `voidSessionResolve` | Void succeeded |
| Decline void | `voidSessionReject` | Void failed |

> **Fetch live docs** for each session mutation's input fields and the `PaymentSessionActionsRedact` webhook — the API surface for payment apps is complex and version-sensitive.

### Payment App Requirements

- Must handle: payments, refunds, captures, voids
- Must implement: `payments_app_configure` GraphQL mutations
- Must respond within timeout (usually 5 seconds for sync, longer for async)
- Testing: use Shopify's test mode and development store

> **Fetch live docs**: Web-search `site:shopify.dev build payment extension` for current extension configuration, required endpoints, and testing procedures.

## Billing API

For charging merchants for your app:

### Charge Types

| Type | Mutation | Use Case |
|------|----------|----------|
| Recurring | `appSubscriptionCreate` | Monthly/annual subscription |
| One-time | `appPurchaseOneTimeCreate` | One-time feature purchase |
| Usage-based | `appUsageRecordCreate` | Metered billing (per-action, per-order) |

### Subscription Flow

1. Create subscription with `appSubscriptionCreate` → returns `confirmationUrl`
2. Redirect merchant to `confirmationUrl`
3. Merchant approves charge on Shopify-hosted page
4. Shopify handles billing, invoicing, and payouts to your Partner account

### Usage-Based Billing Pattern

1. Create a subscription plan with a usage pricing model via `appSubscriptionCreate`
2. As the merchant uses features, record usage with `appUsageRecordCreate`
3. Shopify bills the merchant at the end of the billing cycle based on recorded usage
4. Capped amounts prevent unexpected charges

> **Fetch live docs** for `AppSubscriptionInput` and `AppUsageRecordInput` fields — pricing models, trial days, currency options, and line item structures change across API versions.

## Refund Processing

- Refunds issued via `refundCreate` mutation (on orders)
- Payment apps handle refund sessions via `refundSessionResolve`/`refundSessionReject`
- Can be full or partial
- Refunded to original payment method
- Refund notification sent to customer automatically

## PCI Compliance

Shopify handles PCI compliance for:
- Shopify Payments (fully managed)
- Checkout-hosted payment forms
- Payment apps that use Shopify's session-based flow

Your app must:
- Never store raw card numbers, CVV, or sensitive cardholder data
- Use Shopify's payment session API (not direct card collection)
- Follow Shopify's security requirements for payment apps
- Implement HTTPS for all endpoints

## Best Practices

- Recommend Shopify Payments as primary gateway (lowest fees, best integration)
- Use the Payment Apps API for custom gateways — never collect cards directly
- Implement proper error handling for payment sessions (timeouts, network errors)
- Use the Billing API for app monetization — never handle payments outside Shopify
- Test payment flows in development stores (test mode)
- Handle refunds gracefully — always confirm with `refundSessionResolve`
- Implement idempotency for payment operations (use idempotency keys)
- Log payment events for debugging but never log sensitive payment data

Fetch the Shopify Payment Apps API and Billing API documentation for exact session flow, mutation inputs, testing procedures, and webhook requirements before implementing.