Medusa v2 Payment Processing
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com payment module for payment data model and service methods
- Web-search
site:docs.medusajs.com payment provider for the provider abstraction layer
- Web-search
site:docs.medusajs.com stripe payment for Stripe integration setup
- Fetch
https://docs.medusajs.com/resources/references/payment and review the IPaymentModuleService interface
- Web-search
medusajs v2 AbstractPaymentProvider 2026 for latest provider interface
Payment Module Architecture
Entity Relationships
| Entity |
Contains |
Key Fields |
| PaymentCollection |
Sessions, Payments |
status, amount, currency_code |
| PaymentSession |
Provider data |
provider_id, status, amount, data (JSON) |
| Payment |
Captures, Refunds |
provider_id, amount, captured_at |
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
| Status |
Meaning |
pending |
Session initialized, awaiting customer action |
requires_more |
Additional steps needed (e.g., 3DS) |
authorized |
Payment authorized, funds reserved |
canceled |
Payment voided/canceled |
error |
Payment failed |
Payment Statuses
After authorization, a Payment entity is created from the session:
| Status |
Meaning |
captured |
Funds captured to merchant |
partially_refunded |
Partial refund issued |
refunded |
Full refund issued |
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
| Method |
Purpose |
initiatePayment |
Create payment session with provider |
authorizePayment |
Authorize payment (reserve funds) |
capturePayment |
Capture authorized payment |
refundPayment |
Refund captured payment |
cancelPayment |
Cancel/void payment |
deletePayment |
Clean up provider-side session |
getPaymentStatus |
Query current status from provider |
updatePayment |
Update an existing payment session |
retrievePayment |
Retrieve payment data from provider |
getWebhookActionAndData |
Parse incoming webhook events |
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
| Configuration |
Description |
apiKey |
Stripe secret key |
webhookSecret |
Stripe webhook signing secret |
capture |
Auto-capture or manual (true/false) |
Stripe Webhook Events
| Event |
Medusa Action |
payment_intent.succeeded |
Mark session authorized/captured |
payment_intent.payment_failed |
Mark session errored |
charge.refunded |
Mark refund completed |
Fetch live docs for Stripe provider configuration options and webhook endpoint setup.
PayPal Integration
| Configuration |
Description |
clientId |
PayPal client ID |
clientSecret |
PayPal client secret |
sandbox |
Use sandbox environment (true/false) |
Fetch live docs for PayPal provider options, redirect handling, and webhook configuration.
Payment Workflows
| Workflow |
Purpose |
createPaymentCollectionForCartWorkflow |
Create collection linked to cart |
initializePaymentSessionWorkflow |
Start session with specific provider |
authorizePaymentSessionWorkflow |
Authorize a pending session |
capturePaymentWorkflow |
Capture an authorized payment |
refundPaymentWorkflow |
Refund a captured payment |
cancelPaymentWorkflow |
Cancel/void a payment |
Key Service Methods
| Operation |
Method |
| Create collection |
paymentModuleService.createPaymentCollections() |
| Create session |
paymentModuleService.createPaymentSession() |
| Authorize session |
paymentModuleService.authorizePaymentSession() |
| Capture payment |
paymentModuleService.capturePayment() |
| Refund payment |
paymentModuleService.refundPayment() |
Fetch live docs for workflow input shapes and provider-specific data requirements.
Admin API Routes
| Route Pattern |
Method |
Purpose |
/admin/payments |
GET |
List payments |
/admin/payments/:id |
GET |
Retrieve payment |
/admin/payments/:id/capture |
POST |
Capture payment |
/admin/payments/:id/refund |
POST |
Refund payment |
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.
1---2name: medusa-payments3description: Implement Medusa v2 payment processing — payment module, provider abstraction, payment sessions, authorization/capture/refund lifecycle, and Stripe/PayPal integration. Use when adding payment providers.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-payments7---89# Medusa v2 Payment Processing1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com payment module` for payment data model and service methods152. Web-search `site:docs.medusajs.com payment provider` for the provider abstraction layer163. Web-search `site:docs.medusajs.com stripe payment` for Stripe integration setup174. Fetch `https://docs.medusajs.com/resources/references/payment` and review the `IPaymentModuleService` interface185. Web-search `medusajs v2 AbstractPaymentProvider 2026` for latest provider interface1920## Payment Module Architecture2122### Entity Relationships2324| Entity | Contains | Key Fields |25|--------|----------|------------|26| **PaymentCollection** | Sessions, Payments | status, amount, currency_code |27| **PaymentSession** | Provider data | provider_id, status, amount, data (JSON) |28| **Payment** | Captures, Refunds | provider_id, amount, captured_at |2930### Module Links3132```33Cart Module ──link──> Payment Module (payment collection)34Order Module ──link──> Payment Module (payment collection)35Region Module ──link──> Payment Module (available providers)36```3738> **Fetch live docs** for exact link definitions and how payment collections bridge carts and orders.3940## Payment Lifecycle4142### PaymentSession Statuses4344| Status | Meaning |45|--------|---------|46| `pending` | Session initialized, awaiting customer action |47| `requires_more` | Additional steps needed (e.g., 3DS) |48| `authorized` | Payment authorized, funds reserved |49| `canceled` | Payment voided/canceled |50| `error` | Payment failed |5152### Payment Statuses5354After authorization, a **Payment** entity is created from the session:5556| Status | Meaning |57|--------|---------|58| `captured` | Funds captured to merchant |59| `partially_refunded` | Partial refund issued |60| `refunded` | Full refund issued |6162## Payment Provider Abstraction6364All payment providers extend `AbstractPaymentProvider`:6566```ts67// Skeleton: custom payment provider68// Fetch live docs for AbstractPaymentProvider interface69class MyPaymentProvider extends AbstractPaymentProvider {70 // Implement: initiatePayment, authorizePayment,71 // capturePayment, refundPayment, cancelPayment72 // Fetch live docs for exact method signatures73}74```7576### Key Provider Methods7778| Method | Purpose |79|--------|---------|80| `initiatePayment` | Create payment session with provider |81| `authorizePayment` | Authorize payment (reserve funds) |82| `capturePayment` | Capture authorized payment |83| `refundPayment` | Refund captured payment |84| `cancelPayment` | Cancel/void payment |85| `deletePayment` | Clean up provider-side session |86| `getPaymentStatus` | Query current status from provider |87| `updatePayment` | Update an existing payment session |88| `retrievePayment` | Retrieve payment data from provider |89| `getWebhookActionAndData` | Parse incoming webhook events |9091> **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.9293## Stripe Integration9495| Configuration | Description |96|---------------|-------------|97| `apiKey` | Stripe secret key |98| `webhookSecret` | Stripe webhook signing secret |99| `capture` | Auto-capture or manual (`true`/`false`) |100101### Stripe Webhook Events102103| Event | Medusa Action |104|-------|---------------|105| `payment_intent.succeeded` | Mark session authorized/captured |106| `payment_intent.payment_failed` | Mark session errored |107| `charge.refunded` | Mark refund completed |108109> **Fetch live docs** for Stripe provider configuration options and webhook endpoint setup.110111## PayPal Integration112113| Configuration | Description |114|---------------|-------------|115| `clientId` | PayPal client ID |116| `clientSecret` | PayPal client secret |117| `sandbox` | Use sandbox environment (`true`/`false`) |118119> **Fetch live docs** for PayPal provider options, redirect handling, and webhook configuration.120121## Payment Workflows122123| Workflow | Purpose |124|----------|---------|125| `createPaymentCollectionForCartWorkflow` | Create collection linked to cart |126| `initializePaymentSessionWorkflow` | Start session with specific provider |127| `authorizePaymentSessionWorkflow` | Authorize a pending session |128| `capturePaymentWorkflow` | Capture an authorized payment |129| `refundPaymentWorkflow` | Refund a captured payment |130| `cancelPaymentWorkflow` | Cancel/void a payment |131132### Key Service Methods133134| Operation | Method |135|-----------|--------|136| Create collection | `paymentModuleService.createPaymentCollections()` |137| Create session | `paymentModuleService.createPaymentSession()` |138| Authorize session | `paymentModuleService.authorizePaymentSession()` |139| Capture payment | `paymentModuleService.capturePayment()` |140| Refund payment | `paymentModuleService.refundPayment()` |141142> **Fetch live docs** for workflow input shapes and provider-specific data requirements.143144## Admin API Routes145146| Route Pattern | Method | Purpose |147|---------------|--------|---------|148| `/admin/payments` | GET | List payments |149| `/admin/payments/:id` | GET | Retrieve payment |150| `/admin/payments/:id/capture` | POST | Capture payment |151| `/admin/payments/:id/refund` | POST | Refund payment |152153## Best Practices154155### Provider Implementation156- Always extend `AbstractPaymentProvider` — do not implement from scratch157- Store provider-specific data in the session `data` field (not in metadata)158- Handle `requires_more` status for providers with multi-step flows (3DS, redirect)159- Implement idempotent operations — captures and refunds may be retried160161### Webhook Handling162- Validate webhook signatures before processing events163- Use idempotency keys to prevent duplicate payment processing164- Log all webhook events for audit trails and debugging165- Handle out-of-order webhook delivery gracefully166167### Security168- Never store raw API keys in code — use environment variables169- Never expose payment session secrets to the client170- Use HTTPS-only webhook endpoints171- Implement amount validation — verify captured amount matches the order total172173### Testing174- Use provider sandbox/test modes during development175- Test the full lifecycle: initiate -> authorize -> capture -> refund176- Test error scenarios: declined cards, insufficient funds, network timeouts177178Fetch the Medusa v2 payment module documentation and provider interface references for exact method signatures, webhook configuration, and provider registration patterns before implementing.