name: medusa-payments description: Implement Medusa v2 payment processing — payment module, provider abstraction, payment sessions, authorization/capture/refund lifecycle, and Stripe/PayPal integration. Use when adding payment providers. allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Medusa v2 Payment Processing

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com payment module for payment data model and service methods
2. Web-search site:docs.medusajs.com payment provider for the provider abstraction layer
3. Web-search site:docs.medusajs.com stripe payment for Stripe integration setup
4. Fetch https://docs.medusajs.com/resources/references/payment and review the IPaymentModuleService interface
5. Web-search medusajs v2 AbstractPaymentProvider 2026 for latest provider interface

Payment Module Architecture

Entity Relationships

Module Links

Cart Module ──link──> Payment Module (payment collection)
Order Module ──link──> Payment Module (payment collection)
Region Module ──link──> Payment Module (available providers)

Fetch live docs for exact link definitions and how payment collections bridge carts and orders.

Payment Lifecycle

PaymentSession Statuses

Payment Statuses

After authorization, a Payment entity is created from the session:

Payment Provider Abstraction

All payment providers extend AbstractPaymentProvider:

// Skeleton: custom payment provider
// Fetch live docs for AbstractPaymentProvider interface
class MyPaymentProvider extends AbstractPaymentProvider {
  // Implement: initiatePayment, authorizePayment,
  // capturePayment, refundPayment, cancelPayment
  // Fetch live docs for exact method signatures
}

Key Provider Methods

Fetch live docs for the full method list — the provider interface has additional methods beyond those listed above (e.g., createAccountHolder, listPaymentMethods, savePaymentMethod). Always verify the current AbstractPaymentProvider interface.

Stripe Integration

Stripe Webhook Events

Fetch live docs for Stripe provider configuration options and webhook endpoint setup.

PayPal Integration

Fetch live docs for PayPal provider options, redirect handling, and webhook configuration.

Payment Workflows

Key Service Methods

Fetch live docs for workflow input shapes and provider-specific data requirements.

Admin API Routes

Best Practices

Provider Implementation

• Always extend AbstractPaymentProvider — do not implement from scratch
• Store provider-specific data in the session data field (not in metadata)
• Handle requires_more status for providers with multi-step flows (3DS, redirect)
• Implement idempotent operations — captures and refunds may be retried

Webhook Handling

• Validate webhook signatures before processing events
• Use idempotency keys to prevent duplicate payment processing
• Log all webhook events for audit trails and debugging
• Handle out-of-order webhook delivery gracefully

Security

• Never store raw API keys in code — use environment variables
• Never expose payment session secrets to the client
• Use HTTPS-only webhook endpoints
• Implement amount validation — verify captured amount matches the order total

Testing

• Use provider sandbox/test modes during development
• Test the full lifecycle: initiate -> authorize -> capture -> refund
• Test error scenarios: declined cards, insufficient funds, network timeouts

Fetch the Medusa v2 payment module documentation and provider interface references for exact method signatures, webhook configuration, and provider registration patterns before implementing.