Skip to main content

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) → emits payment.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)?