Identifier categories
Platform API responses include three categories of identifiers. Understanding the source and purpose of each is critical for a stable integration.- Merchant identifiers: You provide these IDs to the platform during an API request, such as the
external_identifier. Use these to map platform resources back to your internal systems, like an order or customer record. - Platform identifiers: The platform generates these to uniquely identify resources within its ecosystem. These include resource IDs (such as the transaction
id, refundid, and payment methodid) and thereconciliation_id. These are typically formatted as UUIDs, but they can also appear as shorter, unique strings when a PSP reference field has strict limits. - PSP identifiers (connector IDs): Payment Service Providers (PSPs) such as Stripe, Adyen, or PayPal return these IDs. Examples include authorization IDs, capture IDs, or session IDs. Use these to identify specific actions within a PSP’s own dashboard or API.
Reconciliation
Reconciliation is a two-step process: the platform maps the PSP record to a platform record, and then the platform maps that record back to your system. To ensure the mapping between the PSP and the platform is reliable, the platform often passes its own ID to the PSP. This is necessary because unique IDs generated by a PSP might not be available in real-time due to intermittent network timeouts or variations in upstream response formats. Because most PSPs have character limits for reference fields, standard UUIDs are often too long to send. To solve this, the platform uses thereconciliation_id. This is a shorter representation of the internal UUID and is compatible with most PSPs.
Some connectors cannot send the reconciliation_id because the PSP field enforces additional length or character rules. In those cases, the platform sends an alternate reference derived from the transaction id that fits the PSP constraints.
When you view a statement in a PSP dashboard, the Reference or
Description field usually contains the
reconciliation_id.Recommended storage strategy
To ensure you can map webhooks, settlement reports, and API responses back to your database, follow these storage recommendations:| Priority | ID type | Recommendation |
|---|---|---|
| Primary | Platform ID | Store the ID of the resource (for example, the transaction id). This is the most stable reference for API look-up. |
| Secondary | Reconciliation ID | Store the reconciliation_id. Use this key to link platform data to PSP settlement reports. |
| Optional | Merchant ID | Store your external_identifier for internal mapping. Resolve it to the platform id for reconciliation and look-ups. |
| Optional | PSP IDs | Store for reference or logging only. Don’t use these as primary keys for your reconciliation logic. |
Nuances and implementation details
Use additional_identifiers for PSP references
Transaction responses include a field called payment_service_transaction_id. This field is intended for the platform’s internal use to track the primary PSP entity. Because a single transaction might involve multiple PSP entities—such as a session, order, authorization, and capture—this ID might change as the transaction progresses or as PSP APIs evolve.
Instead, use the additional_identifiers object. This object provides a structured, merchant-friendly breakdown of all IDs returned by the PSP, such as payment_service_authorization_id and payment_service_capture_id.
Avoid relying on PSP-specific fields
Do not use PSP-specific fields as primary identifiers. PSPs frequently update API versions, which can change the format or the field used for transaction IDs. Additionally, the platform might update how PSP fields are mapped to improve data quality. By relying on the platform’s internal IDs, your integration remains insulated from these external changes.Summary
- For your UI and support: Use the transaction
id. - For financial reconciliation: Use the
reconciliation_id. - For PSP dashboard look-up: Use the values found in
additional_identifiers. - Avoid: Don’t use
payment_service_transaction_idas a unique key in your database; consider it an internal platform reference.