Core Concepts
Correlation Keys & Metadata
The key that ties a Tonder payment to your order across the API, webhooks and reports.
Reference field names differ across integration modes. Use this map to keep your reconciliation logic consistent, no matter how you integrate.
Root reference field (you send it in the request)
This is the field that appears in the Dashboard and in Excel reports so you can recognize your orders.
| Field | Hosted Checkout | SDK | API Direct |
|---|---|---|---|
| Root field name | external_id | orderReference | client_reference |
| Appears in | Dashboard · Excel | Dashboard · Excel | Dashboard · Excel · Webhook |
| Arrives in webhook? | ❌ No | ❌ No | ✅ Yes — top-level |
Webhook reconciliation (use the metadata fields)
The metadata fields arrive in all formats for all modes.
| Field | Hosted Checkout | SDK | API Direct |
|---|---|---|---|
| Recommended name | metadata.external_id | metadata.external_id | metadata.external_id |
| Other fields | metadata.order_id · metadata.customer_id · metadata.business_user | (same) | (same) |
| Arrives in webhook? | ✅ Yes — always | ✅ Yes — always | ✅ Yes — always |
API Direct is the only mode where the root reference field (client_reference) also arrives in the
webhook. For all modes, metadata.external_id is the safest reconciliation key.
Quick reference
| 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.
Next steps
Was this page helpful?