TransactionSourceData
A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.
Encapsulates the origin of a transaction and any source-specific identifiers.
Values
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields
| Field | Type | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
source
required |
TransactionSource TransactionSource | The primary source of the transaction (virtual terminal, API, etc.).
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
hostedPaymentPageId
required |
string (uuid) | When `source` is `HostedPaymentPage`,
this is the ID of the hosted payment page where the transaction was run.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
contractId
required |
string (uuid) | When `source` is `RecurringBilling`,
this is the ID of the recurring billing contract.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
offlineBatchId
required |
string (uuid) | When `source` is `OfflineBatch`,
this is the ID of the batch which submitted the transaction.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
invoiceId
required |
string (uuid) | When `source` is `Invoicing`,
this is the ID of the invoice the automatic charge (or smart-retry attempt)
is settling. Stamped server-side by the Invoicing module's auto-charge executor;
the join key used to reconcile the resulting transaction back onto the invoice.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
apiKeyId
required |
string (uuid) | When `source` is `Api`,
this is the ID of the api key used to submit the transaction.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
apiKeyName
required |
string | The name associated with the API key used as the source of the transaction.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
usedHppSession
required |
boolean | Indicates the transaction was initiated via an HPP pre-filled session.
Set to `true` when a session was resolved and consumed during form submission.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
usedManualStoredPaymentMethodAdd
required |
boolean | Indicates the transaction is the internal account verification run when a payment method
is manually added as a stored payment method from the Customers back office.
Set by the server only. Any value a client supplies on a create request is discarded,
so this field is read-only for API callers.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
hppSessionId
required |
string (uuid) | The ID of the Hosted Payment Page session that produced this transaction.
Populated only when the transaction was created through the HPP session flow;
`null` for every other source (Virtual Terminal, API, recurring billing,
offline batch, and HPP submits that did not resolve a session).
This is a stable, server-supplied join key: integrators that drive transactions
through the HPP session API can read it back from the transaction to correlate
the originating session without subscribing to completion events. Distinct from
`hostedPaymentPageId`, which identifies the reusable page template
rather than the single-use session.
Read-only from a client's perspective: the value is stamped server-side only on
the verified HPP-session create path. Any value supplied on an inbound create
request is ignored and overwritten with `null`, so it cannot be used to
fabricate a session-to-transaction correlation.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
campaignId
required |
string (uuid) | The campaign the payment link that produced this transaction belonged to, when it belonged
to one. `null` for every transaction created outside a campaign, which is every
transaction created before campaigns existed and every one whose link named no campaign.
Stamped server-side on the verified HPP-session create path from the session document,
exactly like `hppSessionId`, and scrubbed to `null` on every other create
entrypoint. A campaign report is a claim about which links earned which money, so a value a
caller could supply would let one merchant's traffic be attributed to a campaign it never
ran.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
campaignSource
required |
string | The per-channel source tag carried by the payment link that produced this transaction
(`email`, `sms`, `qr`, `social`), when the link carried one. Bounded and
normalized by `CampaignSourceRules`; `null` when the link named no source.
Meaningful only alongside `campaignId`: it is the breakdown inside one
campaign, not a standalone classification. Server-stamped and client-scrubbed on the same
terms as `campaignId`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
promotionCode
required |
string | The promotion code that discounted this transaction, in the platform's normalized casing,
or `null` when no promotion was applied, which is every transaction created before
promotions existed and every one the payer entered no code on.
Stamped server-side on the verified HPP-session create path from a re-evaluation the
gateway performed itself, exactly like `campaignId`, and scrubbed to
`null` on every other create entrypoint. A discount is money the merchant gave away,
so a value a caller could supply would let anyone holding a payment link record a
promotion the merchant never issued.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
discountAmount
required |
number (double) | The amount the promotion took off the base of this transaction, or `null` when none
was applied.
A record of what was discounted, not a component of what was charged: the base on
`TrxAmounts` is already the discounted figure, so this never participates in
any total. It is what makes the reduction legible afterwards, on a receipt, a report and
the promotion's own redemption ledger. Server-stamped and client-scrubbed on the same
terms as `promotionCode`, and meaningful only alongside it.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
clientIpAddress
required |
string | The IP address of the client that initiated the transaction.
Null for system-initiated transactions (recurring billing, offline batch).
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
clientIpGeo
required |
ClientIpGeoSnapshot ClientIpGeoSnapshot | Point-in-time geolocation / ISP / ASN snapshot resolved at the
enrichment stage from `clientIpAddress`.
Snapshot: does NOT update if the underlying IP intelligence
database changes. Once written by the enrichment pipeline this
value is immutable; subsequent transaction operations (capture,
refund, reversal, repeat, recurring-billing materializations) must
not overwrite it.
Null when no client IP was available (system-initiated
transactions, or when the IP geo provider could not resolve the
address: loopback / private / unrouted ranges).
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
Fields of ClientIpGeoSnapshot: This body has no documented fields. | ||||||||||||||||
clientDevice
required |
ClientDeviceSnapshot ClientDeviceSnapshot | Browser context of the client that submitted the transaction: the user agent and the
accept-language header, as observed at create time.
Server-stamped from the request on every surface the platform hosts (hosted payment page,
virtual terminal), and accepted from the request body on the API, where the caller is the
only party that has seen the shopper's browser. Preserved rather than overwritten when a
caller supplies it, exactly like `clientIpAddress`.
Null for system-initiated transactions (recurring billing, offline batch), for every
transaction created before this field existed, and for any caller that sends neither
header. Absent rather than empty when there is nothing to record.
Conditional: When ClientDevice is not null.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
Fields of ClientDeviceSnapshot:
This body has no documented fields. | ||||||||||||||||
screeningDeviceSignals
required |
object | Device signals collected by an external screening provider's own client-side agent,
keyed by the registered screening provider id (a Riskified beacon session id under
`riskified`, a FraudLabs Pro agent checksum under `fraudlabspro`).
A provider's agent runs in the shopper's browser and hands back an opaque token that only
that provider can interpret; the token is the join key between what the agent observed
and the screening call the gateway later makes. Keyed by provider id so a merchant
running two providers keeps the two tokens apart, and so the screening request builder
can hand each provider only its own: see
`TryGetScreeningDeviceSignal`, which is the only sanctioned read.
These are provider session tokens, so they are never logged and never leave the
transaction document except on the screening call to the provider that issued them.
Null when no agent ran, which is every transaction created before this field existed and
every transaction on a surface that renders no agent. Absent rather than empty, for the
reason given on `clientDevice`.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
createdByUserId
required |
string (uuid) | The user ID of the user who created the transaction.
Null for anonymous or system-initiated transactions.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
metadata
required |
object | Optional extra metadata for future sources or provider-specific data.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||||||
This model has no documented fields.