Reference

Which leg covers each capability in a hybrid integration, plus the refund and payout rules.

A consolidated reference for the Hybrid model: which leg handles each flow, which webhook format, and which correlation key to use.

Format and key per leg

Leg	Handles	Webhook format	Correlation key
SDK / Hosted	Card payments	Long	`metadata.external_id`
API Direct	Other methods, withdrawals, and refunds	Short	`client_reference` + `metadata.external_id`

On both legs, metadata.external_id is the universal reconciliation key.

Combination	Cards	Other methods	Withdrawals
Hybrid A	Hosted Checkout	API Direct	API Direct
Hybrid B	Full SDK	API Direct	API Direct
Hybrid C	Lite SDK	API Direct	API Direct

Refunds apply to cards only and are processed via Dashboard (recommended) or API Direct. Choose one method and use it consistently.

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.

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

Mode	Request field (you send)	Webhook field (you read)
Hosted Checkout	`external_id`	`metadata.external_id`
SDK (any platform)	`orderReference`	`metadata.external_id` or `metadata.order_id`
API Direct	`client_reference`	`client_reference` (top-level) + `metadata.external_id`
Hybrid	both, per leg	both formats — dedupe on `metadata.external_id`

Universal rule: populate metadata.external_id on every request — it's the only field guaranteed to arrive in every webhook of every format.