Payments — Hyperswitch + Gateways
Decision: self-hosted Hyperswitch as the payment orchestration layer in front of Indian gateways — Razorpay, CCAvenue, Cashfree (notes). Medusa talks to Hyperswitch via a custom payment provider.
Why orchestration
- One integration in Medusa; routing/failover across gateways behind it.
- Smart routing (cost, success-rate, method), automatic retries on a down gateway.
- Unified reconciliation + reporting across gateways.
- Self-hosted → routing rules + payment data under tenant control (PCI posture, see Security).
Medusa payment provider (custom)
// medusa custom payment provider → Hyperswitch
class HyperswitchProvider {
initiatePayment(cart) // create Hyperswitch PaymentIntent
authorizePayment(session) // confirm
capturePayment(payment) // capture (or auto)
refundPayment(payment, amt)
retrievePayment(id)
getWebhookActionAndData() // map HS webhook → Medusa state
}
Methods
UPI, cards, netbanking, wallets, EMI, COD (handled in Orders), and partial payments (advance + balance for installs — modeled as two payment collections on the order).
Webhooks
- Hyperswitch →
/v1/webhooks/hyperswitch(signature-verified) → emitspayment.captured/payment.failed/refund.processed→ consumed by Medusa (order state), Finance (reconciliation), Loyalty (confirm points).
Reconciliation
- Settlement files from gateways pulled into Finance (PG); matched against orders/payouts. Mismatches flagged.
Tenant config
HYPERSWITCH_URL, HYPERSWITCH_API_KEY (secret), per-gateway keys (RAZORPAY_*, CCAVENUE_*, CASHFREE_*), enabled methods, routing policy.
Open questions
- Default routing policy (success-rate vs cost) per tenant.
- Which gateway is primary for the first tenant (UTL)?