> For the complete documentation index, see [llms.txt](https://academy.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.hyperswitch.io/preface.md). # PREFACE ## The Problem Payments are deceptively simple. A customer clicks **Pay,** money moves, everyone's happy, right? Behind that click lies a labyrinthine world of state machines, authentication protocols, routing strategies, compliance requirements, and a dozen interconnected systems that must coordinate perfectly in milliseconds. When something breaks and it always breaks you need more than surface-level knowledge. You need to understand the terrain. Most payment education falls into two camps: **Camp A:** Dense academic tomes that explain **what** things are, but never **why** they matter or **how** to use them. You memorize definitions but can't build anything. **Camp B:** Fragile tutorials that get you through a "Hello World" payment but leave you stranded when real-world complexity hits. Partial authorizations? Network tokens? Multi-processor routing? Good luck. Neither camp prepares you for production. Neither camp helps you think like a payment engineer. ## The Vision Hyperswitch Academy exists to bridge that gap to take you from zero to production-ready payment expertise. We believe learning should flow like a journey, not a checklist. Each chapter builds on the last, creating momentum and curiosity. You're not memorizing components, you're building a mental model of how modern payments actually work. Our philosophy is simple: * **Learn by doing**. Every concept connects to hands-on practice. You'll deploy local instances, trace payments through the stack, build integrations, and break things intentionally. * **Understand the "why".** We don't just explain what a vault does, we explain why it matters for your business: one-click payments, recurring billing, PCI compliance, customer retention. * **Think in systems.** Payments aren't isolated transactions, they're part of larger systems involving routing, optimization, observability, and operational excellence. * **Ship with confidence.** By the end, you won't just know Hyperswitch, you'll know how to run it in production, debug it when it fails, and extend it when you need more. ## Who This Is For * **Developers** building payment infrastructure for the first time * **Engineers** migrating from closed-source processors to open-source orchestration * **Architects** designing systems that need to handle payments at scale * **Operators** responsible for keeping payment systems running smoothly * **Contributors** wanting to understand Hyperswitch deeply enough to improve it ## What You'll Walk Away With After completing Hyperswitch Academy, you'll have: * Complete payment fluency: You'll understand every state transition, every failure mode, and every optimization opportunity. * Production instincts: You'll know what to monitor, what to alert on, and how to debug issues without panic. * Integration confidence: You'll integrate processors, vaults, fraud systems, and alternative payment methods with a repeatable pattern that scales. * Optimization mindset: You'll see payments not just as transactions to process, but as opportunities to improve approval rates, reduce costs, and recover revenue. * Contributor-level knowledge: You'll understand Hyperswitch's internals deeply enough to customize it, extend it, or contribute back to the project. ## The Journey Ahead This academy is organized as a narrative from foundations to mastery, from extend to optimize, from deploy to operate. Each part builds on the last, each chapter marks a milestone. Start at the beginning. Follow the flow. Do the practical sessions. Ask questions. By the end, you won't just know how to process a payment. You'll know how to build, operate, and optimize payment systems that scale. Let's begin. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://academy.hyperswitch.io/preface.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.