Integration Options
Miracle offers two ways to accept payments: Hosted Payment Page (HPP) and Direct API (H2H). Both use the same underlying Payment object, the same webhooks, and the same payment methods — they differ in where the checkout UI lives and how much you build yourself.
Comparison
| Hosted Payment Page (HPP) | Direct API (H2H) | |
|---|---|---|
| Integration effort | Low — redirect to hosted page | Higher — build your own checkout |
| Where customer pays | Miracle-hosted page | Your website |
| Customization | Logo, colors, branding | Full control over UI |
| PCI scope | SAQ-A (simplest) | SAQ A-EP with tokenization (recommended), or SAQ-D for PCI-certified merchants |
| 3D Secure | Handled automatically | You implement redirect handling |
| Payment methods | All supported | All supported |
| Server-side code | Create session, handle webhook | Create payment, handle 3DS, handle webhook |
| Best for | Quick launch, compliance simplicity | Full UX control, custom checkout |
Which should I choose?
If you're just getting started, choose HPP. You can always switch to Direct API later.
HPP is the right choice for most use cases. You create a checkout session on your server, redirect your customer to the hosted page, and receive a webhook when the payment completes. There is no PCI paperwork beyond SAQ-A, and 3D Secure is handled for you automatically. This is the fastest path to go live.
Direct API is for teams that need full control over the checkout experience. The recommended approach is client-side tokenization (SAQ A-EP): your frontend tokenizes card data via our API, and your backend creates payments using the token — your server never handles raw card data. Sending raw card data server-side (SAQ-D) is only available to PCI-certified merchants. You handle the 3D Secure redirect yourself and process the result via webhook. Choose this when your product requires a deeply customized checkout flow.
Idempotency
All write operations (POST, PUT, PATCH, DELETE) require an Idempotency-Key header. This prevents duplicate operations caused by network retries. Requests without the header will receive a 400 error. See the Idempotency guide for details.
Next steps
- HPP — follow the quickstart guide: Your first payment
- Direct API — learn about the payment lifecycle: Payments