# This file was auto-generated by Fern from our API Definition.

import typing_extensions
import typing_extensions
from ..types.card_brand import CardBrand
from ..core.serialization import FieldMetadata
import typing
from .address import AddressParams
from ..types.card_type import CardType
from ..types.card_prepaid_type import CardPrepaidType
from ..types.card_co_brand import CardCoBrand
from ..types.card_issuer_alert import CardIssuerAlert


class CardParams(typing_extensions.TypedDict):
    """
    Represents the payment details of a card to be used for payments. These
    details are determined by the payment token generated by Web Payments SDK.
    """

    id: typing_extensions.NotRequired[str]
    """
    Unique ID for this card. Generated by Square.
    """

    card_brand: typing_extensions.NotRequired[CardBrand]
    """
    The card's brand.
    See [CardBrand](#type-cardbrand) for possible values
    """

    last4: typing_extensions.NotRequired[typing_extensions.Annotated[str, FieldMetadata(alias="last_4")]]
    """
    The last 4 digits of the card number.
    """

    exp_month: typing_extensions.NotRequired[typing.Optional[int]]
    """
    The expiration month of the associated card as an integer between 1 and 12.
    """

    exp_year: typing_extensions.NotRequired[typing.Optional[int]]
    """
    The four-digit year of the card's expiration date.
    """

    cardholder_name: typing_extensions.NotRequired[typing.Optional[str]]
    """
    The name of the cardholder.
    """

    billing_address: typing_extensions.NotRequired[AddressParams]
    """
    The billing address for this card. `US` postal codes can be provided as a 5-digit zip code
    or 9-digit ZIP+4 (example: `12345-6789`). For a full list of field meanings by country, see
    [Working with Addresses](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-addresses).
    """

    fingerprint: typing_extensions.NotRequired[str]
    """
    Intended as a Square-assigned identifier, based
    on the card number, to identify the card across multiple locations within a
    single application.
    """

    customer_id: typing_extensions.NotRequired[typing.Optional[str]]
    """
    **Required** The ID of a [customer](entity:Customer) to be associated with the card.
    """

    merchant_id: typing_extensions.NotRequired[str]
    """
    The ID of the merchant associated with the card.
    """

    reference_id: typing_extensions.NotRequired[typing.Optional[str]]
    """
    An optional user-defined reference ID that associates this card with
    another entity in an external system. For example, a customer ID from an
    external customer management system.
    """

    enabled: typing_extensions.NotRequired[bool]
    """
    Indicates whether or not a card can be used for payments.
    """

    card_type: typing_extensions.NotRequired[CardType]
    """
    The type of the card.
    The Card object includes this field only in response to Payments API calls.
    See [CardType](#type-cardtype) for possible values
    """

    prepaid_type: typing_extensions.NotRequired[CardPrepaidType]
    """
    Indicates whether the card is prepaid or not.
    See [CardPrepaidType](#type-cardprepaidtype) for possible values
    """

    bin: typing_extensions.NotRequired[str]
    """
    The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API
    returns this field.
    """

    version: typing_extensions.NotRequired[int]
    """
    Current version number of the card. Increments with each card update. Requests to update an
    existing Card object will be rejected unless the version in the request matches the current
    version for the Card.
    """

    card_co_brand: typing_extensions.NotRequired[CardCoBrand]
    """
    The card's co-brand if available. For example, an Afterpay virtual card would have a
    co-brand of AFTERPAY.
    See [CardCoBrand](#type-cardcobrand) for possible values
    """

    issuer_alert: typing_extensions.NotRequired[CardIssuerAlert]
    """
    An alert from the issuing bank about the card status. Alerts can indicate whether
    future charges to the card are likely to fail. For more information, see
    [Manage Card on File Declines](https://developer.squareup.com/docs/cards-api/manage-card-on-file-declines).
    
    This field is present only if there's an active issuer alert.
    See [IssuerAlert](#type-issueralert) for possible values
    """

    issuer_alert_at: typing_extensions.NotRequired[str]
    """
    The timestamp of when the current issuer alert was received and processed, in
    RFC 3339 format.
    
    This field is present only if there's an active issuer alert.
    """

    hsa_fsa: typing_extensions.NotRequired[bool]
    """
    Indicates whether the card is linked to a Health Savings Account (HSA) or Flexible
    Spending Account (FSA), based on the card BIN.
    """
