> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identifiers & reconciliation

Integrating with a payment orchestrator involves managing multiple layers of identifiers. This guide explains the types of IDs returned by the platform API and provides recommendations on which IDs to store for reliable reconciliation and troubleshooting. For field definitions, see the [Get transaction](/reference/transactions/get-transaction) reference.

## 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`, refund `id`, and payment method `id`) and the `reconciliation_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 the `reconciliation_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.

<Info>
  When you view a statement in a PSP dashboard, the **Reference** or
  **Description** field usually contains the `reconciliation_id`.
</Info>

## 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_id` as a unique key in your database; consider it an internal platform reference.