Overview & When to Use It
Combine SDK or Hosted for cards with API Direct for APMs and payouts, without PCI scope.
The Hybrid model combines the simplicity of SDK/Hosted for card payments with the power and flexibility of API Direct for all other methods and withdrawals — without requiring PCI certification. It's the recommended approach for merchants that need custom UI for some flows and programmatic control for others (iGaming, fintech, high-volume operations).
How it works
The Hybrid model splits your processing strategically:
- For card payments: use Hosted Checkout, Full SDK, or Lite SDK. Tonder manages PCI compliance; no certification needed.
- For all other methods: use API Direct (SPEI, OXXO Pay, MercadoPago, cash, and any non-card method).
- For withdrawals: use API Direct, with full programmatic control and no PCI requirements.
Valid combinations
Choose one combination based on your card UI needs:
| Combination | Cards | Other methods | Withdrawals | Best for |
|---|---|---|---|---|
| Hybrid A | Hosted Checkout | API Direct | API Direct | Fastest launch with maximum control for non-card methods |
| Hybrid B | Full SDK | API Direct | API Direct | Embedded card experience with standard UI |
| Hybrid C | Lite SDK | API Direct | API Direct | Complete UI customization across all methods |
PCI scope
| Integration mode | PCI certification required |
|---|---|
| Hosted Checkout | None — Tonder hosts card capture |
| SDK (Full or Lite) | None — card data is tokenized on the client |
| Hybrid | None — cards flow through the SDK/Hosted leg |
| API Direct (S2S) — tokenized flow | SAQ A or SAQ A-EP — the card is tokenized before it reaches you |
| API Direct (S2S) — raw card data | PCI DSS Level 1 — the card passes through your servers |
Refunds in Hybrid mode
Card refunds can be processed in two ways:
- Dashboard (recommended): process all card refunds through the Tonder dashboard.
- API Direct: use API Direct for card refunds.
We recommend choosing one refund method and using it consistently. Mixing both complicates your integration.
Important limitations
- Refunds are only available for card payments; SPEI, OXXO Pay, and MercadoPago transactions cannot be refunded.
- Each transaction can be refunded only once, and in full.
- Refunds must be processed within 29 days after payment confirmation.
Trade-offs to consider
- Dual integration patterns. You'll implement two integration styles at once, with different request/response formats for cards vs. other methods.
- Dual webhook handling. You'll receive Hosted/SDK-style webhooks for cards and API Direct-style webhooks for everything else. See Dual webhooks.
- Higher initial development effort than a pure SDK/Hosted approach, since you build and maintain two integrations in parallel.
The Hybrid approach is a bridge solution toward the next generation of Hosted Checkout and SDKs, which will unify request/response/webhook patterns. Current hybrid implementations will remain supported, with migration paths available.