# 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. ## Fields - `source` ([TransactionSource](https://devportal.signapay-sbx.winkpg.io/docs/api/models/TransactionSource.md)): The primary source of the transaction (virtual terminal, API, etc.). (nullable) Values: - `Unknown`: The source of the transaction is unknown or not specified. - `VirtualTerminal`: The transaction originated from a virtual terminal interface. - `Api`: The transaction was initiated through an API call. - `HostedPaymentPage`: The transaction was processed via a hosted payment page. - `RecurringBilling`: The transaction is part of a recurring billing cycle. - `OfflineBatch`: The transaction was processed as part of an offline batch. - `Invoicing`: The transaction is an automatic charge against an invoice (e.g. a recurring-invoice auto-charge or a smart-retry attempt) submitted by the Invoicing module. - `hostedPaymentPageId` (string(uuid)): When `source` is `HostedPaymentPage`, this is the ID of the hosted payment page where the transaction was run. (nullable) - `contractId` (string(uuid)): When `source` is `RecurringBilling`, this is the ID of the recurring billing contract. (nullable) - `offlineBatchId` (string(uuid)): When `source` is `OfflineBatch`, this is the ID of the batch which submitted the transaction. (nullable) - `invoiceId` (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) - `apiKeyId` (string(uuid)): When `source` is `Api`, this is the ID of the api key used to submit the transaction. (nullable) - `apiKeyName` (string): The name associated with the API key used as the source of the transaction. (nullable) - `usedHppSession` (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) - `usedManualStoredPaymentMethodAdd` (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) - `legacyApiFacade` (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) - `invoicePayLinkPayment` (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) - `partialInvoicePayment` (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) - `recurringEnrollmentPayment` (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) - `recurringChargeRepeat` (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) - `honorCheckSecCode` (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) - `consentedCardPriceRate` (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) - `consentedCardPriceAmount` (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) - `consentedSurchargeMaxRate` (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) - `consentRecordedNoSurchargeCeiling` (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) - `consentSurchargeEffectiveFrom` (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) - `hppSessionId` (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) - `campaignId` (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) - `campaignSource` (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) - `promotionCode` (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) - `discountAmount` (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) - `clientIpAddress` (string): The IP address of the client that initiated the transaction. Null for system-initiated transactions (recurring billing, offline batch). (nullable) - `clientIpGeo` ([ClientIpGeoSnapshot](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ClientIpGeoSnapshot.md)): 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). Fields: - `countryA2` (string): ISO 3166-1 alpha-2 country code (e.g. `"US"`). (nullable) - `countryName` (string): Country name in English (e.g. `"United States"`). (nullable) - `region` (string): First-level administrative subdivision name (e.g. US state, Canadian province, German Land). May be the ISO subdivision code in some records and the localized name in others. (nullable) - `city` (string): City name (e.g. `"Minneapolis"`). (nullable) - `latitude` (number(double)): Approximate latitude of the IP block centroid in decimal degrees. Resolution depends on the database tier: country, city, or block. (nullable) - `longitude` (number(double)): Approximate longitude of the IP block centroid in decimal degrees. (nullable) - `timeZone` (string): IANA time zone (e.g. `"America/Chicago"`). (nullable) - `isp` (string): Internet Service Provider name. Available in editions that include ISP data (Location+ISP / Full). (nullable) - `organization` (string): Organization name registered for the IP block. May coincide with `isp` for residential blocks but typically diverges for hosting / corporate blocks. (nullable) - `asNumber` (integer(int64)): Autonomous System Number (e.g. `15169` for Google). (nullable) - `connectionType` (string): Connection / usage type as classified by DB-IP. Typical values: `"Residential"`, `"Business"`, `"Hosting"`, `"Mobile"`, `"Education"`, `"Government"`. The exact vocabulary is supplied by the database; consumers should treat unknown values as opaque. (nullable) - `clientDevice` ([ClientDeviceSnapshot](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ClientDeviceSnapshot.md)): 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. Fields: - `userAgent` (string): The `User-Agent` header sent by the submitting browser, or `null` when none was observed. Null is the normal state for system-initiated transactions (recurring billing, offline batch) and for API callers that do not send one. (nullable, max length 512) - `acceptLanguage` (string): The `Accept-Language` header sent by the submitting browser, or `null` when none was observed. Carried verbatim, weighting and all, because a screening provider scores the header as sent rather than a language the platform picked out of it. (nullable, max length 64) - `deviceFingerprint` (string): A platform device fingerprint: a keyed hash of the user agent, the accept-language and the network prefix of the client IP address, as 64 lowercase hexadecimal characters. Null when no user agent was observed, which is the normal state for system-initiated transactions. (nullable, read only) - `screeningDeviceSignals` (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) - `createdByUserId` (string(uuid)): The user ID of the user who created the transaction. Null for anonymous or system-initiated transactions. (nullable) - `metadata` (object): Optional extra metadata for future sources or provider-specific data. (nullable) ## See also - [All documentation](https://devportal.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.