Skip to main content

Transaction Identifiers

A Transaction carries more than one identifier-shaped field. They serve different purposes and offer different stability guarantees — using the wrong one for deduplication or reconciliation is a common source of bugs.

transaction.id​

PayData's own identifier for this transaction record.

  • Use this to check whether your system already has this transaction — it's the right key for deduplicating against re-imports of the same transaction.
  • Stable: it does not change when PayData later updates the transaction's data (for example during a support case) — see Changing transactions for how to detect when that happened. Only the data and lastModifiedAt change; id stays the same.

Example: je7a2eddues7

transaction.transactionId​

The transaction identifier as received from the PSP — or, for PSPs that don't explicitly expose one, PayData falls back to another identifier.

  • Often not unique on its own: PSPs frequently reuse this id between a payment and a related transaction such as its refund. Pair it with paymentClassification (and/or bookingDate) if you need to disambiguate; don't use it alone as a database key.
  • Can change across a support-case correction of the same transaction, unlike transaction.id.
  • The same value may also be duplicated somewhere in transaction.fields, under a key name specific to that account type — see Transaction Fields rather than assuming a fixed key.

Example: TR edb8dd91-3244-487b-9080-1adfd97ea58f

transaction.fields.uniqueId​

An identifier that's unique within the account.

  • Sometimes taken directly from the PSP, sometimes synthesized by PayData (for example as a hash of other transaction data) when the PSP doesn't provide one of its own.
  • Because it's meant to be unique per account rather than per transaction record, it's the field to reach for when you need to recognize "the same underlying transaction" across two different PayData accounts on the same PSP — for example after a partner reconnects a shop under a new account, or reconciles two accounts that both see the same PSP-side transaction.
  • Where it's a computed hash, treat it as durable rather than permanently immutable: if the underlying data it's derived from is corrected in a support case, the hash can in principle change too.

Which one to use for what​

  • Have I already stored this transaction? — transaction.id.
  • Matching a transaction against the PSP's own records or a support ticket? — transaction.transactionId, keeping in mind it isn't always unique by itself.
  • Recognizing the same real-world transaction across two different PayData accounts on the same PSP? — transaction.fields.uniqueId, where the account type provides it.