Claves de correlación y metadata
La clave con la que amarras un pago de Tonder a tu pedido, en la API, los webhooks y los reportes.
Los nombres de los campos de referencia difieren entre modos de integración. Usa este mapa para mantener tu lógica de conciliación consistente, sin importar cómo integres.
Campo de referencia raíz (lo envías en la petición)
Este es el campo que aparece en el Dashboard y en los reportes de Excel para que puedas reconocer tus pedidos.
| Campo | Hosted Checkout | SDK | API Direct |
|---|---|---|---|
| Nombre del campo raíz | external_id | orderReference | client_reference |
| Aparece en | Dashboard · Excel | Dashboard · Excel | Dashboard · Excel · Webhook |
| ¿Llega en el webhook? | ❌ No | ❌ No | ✅ Sí — nivel superior |
Conciliación por webhook (usa los campos de metadata)
Los campos de metadata llegan en todos los formatos para todos los modos.
| Campo | Hosted Checkout | SDK | API Direct |
|---|---|---|---|
| Nombre recomendado | metadata.external_id | metadata.external_id | metadata.external_id |
| Otros campos | metadata.order_id · metadata.customer_id · metadata.business_user | (iguales) | (iguales) |
| ¿Llega en el webhook? | ✅ Sí — siempre | ✅ Sí — siempre | ✅ Sí — siempre |
API Direct es el único modo donde el campo de referencia raíz (client_reference) también llega en
el webhook. Para todos los modos, metadata.external_id es la clave de conciliación más segura.
Referencia rápida
| Modo | Campo en la petición (envías) | Campo en el webhook (lees) |
|---|---|---|
| Hosted Checkout | external_id | metadata.external_id |
| SDK (cualquier plataforma) | orderReference | metadata.external_id o metadata.order_id |
| API Direct | client_reference | client_reference (nivel raíz) + metadata.external_id |
| Híbrido | ambos, por leg | ambos formatos — deduplica por metadata.external_id |
Regla universal: incluye metadata.external_id en cada petición — es el único campo
garantizado en todos los webhooks de todos los formatos.