# CardData

A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.

Represents the data associated with a payment card.

## Fields
- `cardNumber` (string): The card account number. Conditional: When IsStoredPayment is not true. (nullable)
- `last4CardNumber` (integer(int32)): The last 4 digits of the card number as an integer. (nullable, read only)
- `expirationMonth` (integer(int32)): The expiration month of the card as an integer in the range `1` to `12`.
- `expirationYear` (integer(int32)): The expiration year of the card. Either a two-digit year (e.g. `29`) or a four-digit year (e.g. `2029`); two-digit years resolve to the 2000s.
- `expirationDate` (string(date-time)): The expiration date of the card. Conditional: When IsStoredPayment is not true. (nullable)
- `binData` ([BinData](https://devportal.signapay-sbx.winkpg.io/docs/api/models/BinData.md)): The BIN (Bank Identification Number) data associated with the card.
  Fields:
  - `bin` (integer(int64))
  - `issuedEntity` ([IssuedEntity](https://devportal.signapay-sbx.winkpg.io/docs/api/models/IssuedEntity.md)): Represents the type of entity to which a transaction is issued.
    Values:
    - `Personal`: Indicates that the transaction is issued to a personal entity.
    - `Commercial`: Indicates that the transaction is issued to a commercial entity.
  - `brand` (string): (nullable)
  - `type` (string): (nullable)
  - `category` (string): (nullable)
  - `issuer` ([BinIssuer](https://devportal.signapay-sbx.winkpg.io/docs/api/models/BinIssuer.md))
  - `panLength` (integer(int32)): (nullable)
  - `flags` ([BinFlags](https://devportal.signapay-sbx.winkpg.io/docs/api/models/BinFlags.md))
  - `fundingSource` ([CardFundingSource](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CardFundingSource.md)): (nullable)
    Values:
    - `Unknown`: Funding source could not be determined from BIN data.
    - `Credit`: Credit card.
    - `Debit`: Debit card.
    - `Prepaid`: Prepaid card (overlay on the debit/credit rail: wins over the rail value).
    - `Charge`: Charge card.
- `cvv` (integer(int32)): Deprecated: send `cardVerificationValue` instead. The CVV (Card Verification Value) of the card as an integer. Conditional: When IsStoredPayment is not true. Range: 100 to 9999. (nullable, deprecated)
- `cardVerificationValue` (string): The card verification value (CVV, CVC or CID) exactly as printed on the card: three digits, or four for American Express. Send it as a string so a leading zero is kept. Conditional: When IsStoredPayment is not true. (nullable)
- `nameOnCard` (string): The name on the card. Conditional: When IsStoredPayment is not true. Max length: 25. (nullable, min length 0, max length 25)
- `pin` (string): The PIN (Personal Identification Number) of the card. (nullable)
- `keySerialNumber` (string): The Key Serial Number associated with the card. (nullable)
- `pinKeySerialNumber` (string): The DUKPT key serial number the reader encrypted the PIN block under, when it differs from `keySerialNumber`. (nullable, max length 24, pattern ^(?:[0-9A-Fa-f]{10,24})?$)
- `emvData` (string): The EMV (Europay, Mastercard, and Visa) data associated with the card. (nullable)
- `trackData` (string): The track data of the card. (nullable)
- `encryptedTrack1Data` (string): The encrypted track 1 data of the card. (nullable)
- `encryptedTrack2Data` (string): The encrypted track 2 data of the card. (nullable)
- `encryptedTrack3Data` (string): The encrypted track 3 data of the card. (nullable)
- `dynamicCardVerificationData` (string): A reader-generated dynamic card verification value captured at the moment the card was read. Card readers that support it derive this value from physical characteristics of the magnetic stripe, which differ between an original card and a copy, so the decryption service that fronts the processor can score whether the presented card is genuine. (nullable)
- `dynamicCardVerificationStatus` (string): Status metadata the reader reported alongside `dynamicCardVerificationData` (for example whether the reader considered the dynamic verification read successful). Non-secret: it describes the read, it is not the verification value itself, so it is persisted as submitted. (nullable)
- `iin` (string): The IIN (Issuer Identification Number) of the card. (nullable)
- `arqc` (string): The ARQC (Authorization Request Cryptogram) of the card. (nullable)
- `entryMode` ([EntryModes](https://devportal.signapay-sbx.winkpg.io/docs/api/models/EntryModes.md)): The entry mode of the card.
  Values:
  - `Unknown`: The entry mode is unknown.
  - `NotApplicable`: The entry mode is not applicable for this transaction.
  - `Manual`: The transaction details were entered manually.
  - `UnencryptedCardReaderSwipe`: The card was swiped through an unencrypted card reader.
  - `EncryptedCardReaderSwipe`: The card was swiped through an encrypted card reader.
  - `Icc`: The transaction was processed using an ICC (Integrated Circuit Card) or chip card.
  - `Proximity`: The transaction was processed using a proximity or contactless payment method.
  - `Fallback`: The transaction was processed using a fallback method when the primary method failed.
  - `TechnicalFallback`: The transaction was processed using a fallback method when the primary method failed.
  - `EmptyCandidateFallback`: The transaction was processed using a fallback method when the primary method failed.
  - `DigitalWallet`: The transaction was processed using a digital wallet.
- `cvPresence` ([CvPresence](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CvPresence.md)): The CV (Card Verification) presence status.
  Values:
  - `None`: The CV status is not specified or unknown.
  - `NotSubmitted`: The CV has not been submitted.
  - `Submitted`: The CV has been successfully submitted.
  - `Illegible`: The submitted CV is illegible or cannot be read.
  - `NotPresent`: The CV is not present or missing from the submission.
- `billingAddress` ([Address](https://devportal.signapay-sbx.winkpg.io/docs/api/models/Address.md)): The billing address associated with the card. Optional by default (no nested validation enforced). Conditional: When IsStoredPayment is not true.
  Fields:
  - `id` (string(uuid)): Gets the unique identifier for the address. (read only)
  - `address1` (string): Gets or sets the first line of the address (e.g., street address). (nullable, max length 100)
  - `address2` (string): Gets or sets the second line of the address (e.g., apartment, suite, unit, building, floor, etc.). (nullable, max length 100)
  - `city` (string): Gets or sets the city of the address. (nullable, max length 100)
  - `state` (string): Gets or sets the state or region of the address. (nullable, max length 100)
  - `province` (string): Gets or sets the province of the address (if applicable). (nullable)
  - `zip` (string): Gets or sets the US ZIP code of the address (for example 12345 or 12345-6789). Conditional: Conditional (see validator source). Pattern: ^\d{5}(-\d{4})?$. Conditional: When IsUsCountry(Country) is false. Max length: 20. (nullable)
  - `postalCode` (string): Gets or sets the international postal code of the address, for a country other than the US. (nullable, max length 20)
  - `country` (string): Gets or sets the country of the address. Defaults to "USA". (nullable, max length 100)
  - `isMailing` (boolean): Gets or sets a value indicating whether this address is a mailing address.
  - `isDefault` (boolean): Gets or sets a value indicating whether this address is the default address.
- `phone` (string): The phone number associated with the card. Conditional: When IsStoredPayment is not true. Max length: 15. Pattern: ^[0-9+()\-\s]*$. (nullable, min length 0, max length 15)
- `email` (string): The email address associated with the card. Conditional: When IsStoredPayment is not true. Must be a valid email. Max length: 50. (nullable, min length 0, max length 50)
- `hasEmvData` (boolean): Indicates whether EMV data was provided in the original request. The raw `emvData` value is not stored. (nullable)
- `hasTrackData` (boolean): Indicates whether track data was provided in the original request. The raw `trackData` value is not stored. (nullable)
- `hasEncryptedTrackData` (boolean): Indicates whether any encrypted track data (track 1, 2, or 3) was provided in the original request. The raw encrypted track values are not stored. (nullable)
- `hasCvv` (boolean): Indicates whether a CVV was provided in the original request, in either `cardVerificationValue` or `cvv`. The raw value is not stored. (nullable)
- `hasPin` (boolean): Indicates whether a PIN was provided in the original request. The raw `pin` value is not stored. (nullable)
- `hasDynamicCardVerificationData` (boolean): Indicates whether reader-generated dynamic card verification data was provided in the original request. The raw `dynamicCardVerificationData` value is not stored. (nullable)
- `emvAid` (string): (nullable)
- `isDebitRouting` (boolean): (nullable)
- `tenderType` ([CardTenderType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CardTenderType.md)): The card-rail tender the caller is attempting to use. Drives deterministic processor routing. `null` (or absent JSON) is treated as `CreditDebit` for backward compatibility: see `EffectiveTenderType`. (nullable)
  Values:
  - `CreditDebit`: Standard credit/debit card. The current card-rail behaviour. isDebitRouting modulates whether the request prefers debit-network routing within this rail.
  - `EbtSnap`: EBT SNAP (food benefits). Routes through the EBT SNAP processor lane and requires PIN + card-present per program rules.
  - `EbtCash`: EBT Cash (cash benefits). Distinct rail from SNAP; supports cashback where SNAP does not. PIN + card-present required.
  - `Ewic`: eWIC (Women, Infants, and Children). Distinct rail from EBT, with item-level eligibility / voucher-select flow handled in the eWIC follow-up epic.
- `isStoredPayment` (boolean): When `true`, this card data originates from a stored payment method and client-side field validation is not applicable. The server resolves actual card data from the payment token. (nullable)
- `terminalCapability` ([TerminalCapability](https://devportal.signapay-sbx.winkpg.io/docs/api/models/TerminalCapability.md)): The static hardware capability of the terminal. Selects the POS capability subfields on the processor wire message. Resolved once in `ProcessorSelectionApplier`: request value wins over the processor-profile default, which wins over `Unspecified`. (nullable)
  Values:
  - `Unspecified`: No capability declared. The handler emits its current default POS capability fields, preserving existing wire behavior exactly.
  - `MagneticStripe`: Magnetic stripe reader only (implies keyed entry).
  - `MagneticStripeWithPin`: Magnetic stripe reader with PIN pad (implies keyed entry).
  - `Chip`: Contact chip reader (EMV ICC).
  - `ChipWithPin`: Contact chip reader with PIN pad.
  - `ChipContactless`: Contactless chip reader (EMV contactless / NFC).
  - `ChipContactlessWithPin`: Contactless chip reader with PIN pad.
- `cryptogram` (string): The payment network cryptogram recovered from wallet-token decryption (the online payment cryptogram for Apple Pay / Google Pay DPAN transactions). Sensitive: masked from logs. (nullable)
- `eciIndicator` (string): The Electronic Commerce Indicator (ECI) describing the authentication context of a tokenized / wallet transaction (e.g. `"05"` for a 3DS-authenticated transaction). Drives the liability-shift indicators processors include in the network message. (nullable)
- `isTokenized` (boolean): Indicates the credential is a tokenized account number (DPAN / network token) rather than a raw PAN. `null` means unknown, which is treated the same as not tokenized. (nullable)
- `tokenTransactionId` (string): The provider-specific transaction identifier returned alongside a wallet token (Apple Pay `transactionIdentifier`, network-token transaction id). Used for dispute matching against the wallet provider. (nullable)

## See also

- [All documentation](https://devportal.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.