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.
| ||||||||||||||
legacyApiFacade
required |
boolean | Indicates the transaction was submitted through the version 1 API compatibility facade.
`null` for every other submission.
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.
| ||||||||||||||
invoicePayLinkPayment
required |
boolean | Indicates the transaction was paid through an invoice's payment link, so dual pricing
prices it as an invoice payment rather than a Hosted Payment Page payment.
`null` for every other submission.
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.
| ||||||||||||||
partialInvoicePayment
required |
boolean | Indicates an invoice payment link payment was for an amount the payer chose rather than
the amount the invoice fixes. Such a payment is never charged a dual pricing card price.
`null` for every other submission.
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.
| ||||||||||||||
recurringEnrollmentPayment
required |
boolean | Indicates the transaction is the first payment of a recurring plan the payer enrolled in on
the Hosted Payment Page, so dual pricing prices it as a recurring charge at the price the
page showed. `null` for every other submission.
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.
| ||||||||||||||
recurringChargeRepeat
required |
boolean | Indicates the transaction repeats or retries a recurring charge, so dual pricing prices it
as a recurring charge under the same consent as the charge it repeats. `null` for
every other submission.
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.
| ||||||||||||||
honorCheckSecCode
required |
boolean | Indicates the ACH processor originates the debit under the SEC code the transaction's check
data carries, rather than the merchant's processor profile default. `null` for every
other submission.
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.
| ||||||||||||||
consentedCardPriceRate
required |
number (double) | The card price rate, as a decimal fraction (`0.04` is 4 percent), that the
cardholder's stored-credential consent stated for a recurring charge. A recurring charge is
charged a dual pricing card price only when its consent stated one, and never at a rate
above it. `null` when the consent stated no card price, and on every other submission.
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.
| ||||||||||||||
consentedCardPriceAmount
required |
number (double) | The card price amount (the card price minus the cash price, in the transaction currency) that
the cardholder's stored-credential consent stated for a recurring charge, for a merchant whose
card price is the cash price plus a fixed amount. A recurring charge is charged a dual pricing
card price only when its consent stated one, and never uplifted by more than it. A consent
states one measure, so at most one of this and `consentedCardPriceRate` is set.
`null` when the consent stated no card price or stated it as a rate, and on every other
submission.
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.
| ||||||||||||||
consentedSurchargeMaxRate
required |
number (double) | The surcharge ceiling, as a decimal fraction (`0.03` is 3 percent), that the
cardholder's stored-credential consent stated at enrollment for the charges the merchant
initiates under it. The charge is never surcharged above it, even when the merchant's surcharge
rate has risen since. `null` when the consent stated no surcharge ceiling, and on every other
submission, in which case no consented ceiling applies.
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.
| ||||||||||||||
consentRecordedNoSurchargeCeiling
required |
boolean | `true` when this is a merchant-initiated recurring or installment card charge whose
stored-credential consent recorded no surcharge ceiling, so the cardholder was not told at
enrollment that the charge could carry a surcharge. A merchant that chose to withhold the
surcharge on such a charge charges it with none. `null` on every other submission.
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.
| ||||||||||||||
consentSurchargeEffectiveFrom
required |
string (date-time) | For a merchant-initiated recurring or installment charge whose cardholder was emailed the
surcharge ceiling after enrollment, the UTC instant that notice said the surcharge takes effect.
A charge processed before it carries no surcharge. `null` on every other submission.
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.