> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Card Validation object

### Description

The Card Validation object allows you to validate an user’s card using 3DS authentication without processing a payment.

A Card object's `Validity` is automatically set to `INVALID` after 24 hours unless it is validated through successful authentication with a Card Validation or a payment (Direct Card PayIn, Preauthorization, Recurring Registration).

<Note>
  **Note – Card validation only available for CB\_VISA\_MASTERCARD**

  The card validation feature is only available for cards with the `CardType` `CB_VISA_MASTERCARD`.
</Note>

<Note>
  **Note – Card validation expires after 5 minutes**

  Because you cannot create two requests at once for the same card, the card validation will expire after 5 minutes, setting the `Status` of the Card Validation object to `FAILED`. 

  The Card `Validity`, however, will remain `UNKNOWN`, which allows you to request a new Card Validation.
</Note>

### Attributes

<ParamField body="AuthorId" type="string">
  The unique identifier of the user at the source of the transaction.
</ParamField>

<ParamField body="SecureModeReturnURL" type="string">
  Max. length: 255 characters

  The URL to which users are automatically returned after 3DS2 if it is triggered (i.e., if the `SecureModeNeeded` parameter is set to `true`).
</ParamField>

<ParamField body="SecureModeRedirectURL" type="string">
  Max. length: 255 characters

  The URL to which to redirect the user to proceed to 3DS2 validation.

  **Caution:** This variable URL is specific to each payment. You must rely on the returned URL in full (host, path, and queries) and not hardcode any part of it.
</ParamField>

<ParamField body="SecureModeNeeded" type="boolean">
  Whether or not the `SecureMode` was used.
</ParamField>

<ParamField body="IpAddress" type="string">
  The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
</ParamField>

<ParamField body="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.\
  For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
</ParamField>

<ParamField body="BrowserInfo" type="object">
  Information about the browser used by the end user (author) to perform the payment.

  <Expandable title="properties">
    <ParamField body="AcceptHeader" type="string">
      The exact content of the HTTP accept headers as sent to the platform from the end user’s browser.
    </ParamField>

    <ParamField body="JavaEnabled" type="boolean">
      Whether or not the end user’s browser has the ability to execute Java.
    </ParamField>

    <ParamField body="Language" type="string">
      Format: Two-letter language code (ISO 639-1 alpha-2) followed by two-letter country code (ISO 3166-1 alpha-2), separated by a hyphen (example: `en-US`; pattern:`^[a-zA-Z]{2}(-[a-zA-Z]{2})?$`)

      The language of the browser.
    </ParamField>

    <ParamField body="ColorDepth" type="integer">
      The value representing the depth of the screen’s color palette for displaying images, in bits per pixel.
    </ParamField>

    <ParamField body="ScreenHeight" type="integer">
      Max. length: 6 characters

      The height of the screen in pixels.
    </ParamField>

    <ParamField body="ScreenWidth" type="integer">
      Max. length: 6 characters

      The width of the screen in pixels.
    </ParamField>

    <ParamField body="TimeZoneOffset" type="integer">
      The difference in minutes between the browser’s timezone and UTC.
    </ParamField>

    <ParamField body="UserAgent" type="string">
      Max. length: 255 characters

      The exact content of the HTTP User-Agent header.
    </ParamField>

    <ParamField body="JavascriptEnabled" type="boolean">
      Whether or not the end user’s browser has the ability to execute JavaScript.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="Status" type="string">
  **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`

  The status of the transaction.
</ParamField>

<ParamField body="Type" type="string">
  **Returned values:** `CARD_VALIDATION`

  The type of the card validation.
</ParamField>

<ParamField body="PreferredCardNetwork" type="string">
  **Returned values:** `VISA`, `MASTERCARD`, `CB`, `MAESTRO`

  The card network to use, as chosen by the cardholder, in case of <a href="/guides/payment-methods/card/co-branded">co-branded cards</a>.
</ParamField>

<ParamField body="SecureMode" type="string">
  **Default value:** DEFAULT\
  **Allowed values:** DEFAULT, FORCE, NO\_CHOICE

  The mode applied for the [3DS protocol](/guides/payment-methods/card/3ds) for CB, Visa, and Mastercard. The options are:

  * `DEFAULT` – Requests an exemption to strong customer authentication (SCA), and thus a frictionless payment experience, if allowed by your Mangopay contract and accepted by the issuer.
  * `FORCE` – Requests SCA.
  * `NO_CHOICE` – Leaves the choice to the issuer whether to allow for a frictionless payment experience or to enforce SCA.

  *Note: Sending the FORCE value automatically sets the ValidationUsage value to MIT.*
</ParamField>

<ParamField body="PaymentCategory" type="string">
  **Default value:** `ECommerce`

  **Allowed values:** `ECommerce`, `TelephoneOrder`

  The channel through which the user provided their card details, used to indicate mail-order and telephone-order (MOTO) payments:

  * `ECommerce` – Payment received online.
  * `TelephoneOrder` – Payment received via mail order or telephone order (MOTO).
</ParamField>

<ParamField body="ValidationUsage" type="string">
  **Default value:** MIT\
  **Allowed values:** MIT, CIT

  Indicates the intended usage of the card:

  * CIT – For customer-initiated transactions (CITs), meaning 3DS is less likely to be required on the card validation.
  * MIT – For merchant-initiated transactions (MITs), meaning 3DS is more likely to be required on the card validation.

  *Note: The MIT value is returned automatically if the SecureMode value is FORCE, even if CIT is sent.*
</ParamField>

<ParamField body="Validity" type="string">
  **Returned values:** `UNKNOWN`, `VALID`, `INVALID`

  Whether the card is valid or not.

  * `UNKNOWN` – No payment or card validation has been processed, so the validity of the card remains unknown.
  * `VALID` – The first payment or card validation using the card was processed successfully within 24 hours of the initial card registration.
  * `INVALID` – The first payment or card validation using the card was attempted and failed, or the status of the corresponding card registration was `CREATED` for more than 24 hours.\
    Once a card is set to `INVALID`, it cannot be set back to `VALID`. A new card registration will be necessary to make a payment.
</ParamField>

<ParamField body="CreationDate" type="Unix timestamp">
  The date and time at which the object was created.
</ParamField>

<ParamField body="AuthorizationDate" type="Unix timestamp">
  The date and time at which successful authorization occurred. If authorization failed, the value is `null`.
</ParamField>

<ParamField body="Applied3DSVersion" type="string">
  **Returned values:** `V1`, `V2_1`

  The 3DS protocol version applied to the transaction.
</ParamField>

<ParamField body="ResultCode" type="string">
  The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
</ParamField>

<ParamField body="ResultMessage" type="string">
  The explanation of the result code.
</ParamField>

<ParamField body="Tag" type="string">
  Max. length: 255 characters

  Custom data that you can add to this object.\
  For transactions (pay-in, transfer, payout), you can use this parameter to identify corresponding information regarding the user, transaction, or payment methods on your platform.
</ParamField>

<ParamField body="CardInfo" type="string">
  Information about the card used for the transaction. \
  If the information or data is not available, `null` is returned.

  <Expandable title="properties">
    <ParamField body="BIN" type="string">
      The 6-digit bank identification number (BIN) of the card issuer.
    </ParamField>

    <ParamField body="IssuingBank" type="string">
      The name of the card issuer.
    </ParamField>

    <ParamField body="IssuerCountryCode" type="string">
      Format: Two-letter country code ([ISO 3166-1 alpha-2 format](/api-reference/overview/data-formats))

      The country where the card was issued.
    </ParamField>

    <ParamField body="Type" type="string">
      **Returned values:** `DEBIT`, `CREDIT`, `CHARGE CARD`.

      The type of card product.
    </ParamField>

    <ParamField body="Brand" type="string">
      The card brand. Examples include: `AMERICAN EXPRESS`, `DISCOVER`, `JCB`, `MASTERCARD`, `VISA`, etc.

      **Note:** The possible returned values are numerous and liable to evolve over time.
    </ParamField>

    <ParamField body="SubType" type="string">
      The subtype of the card product. Examples include: `CLASSIC`, `GOLD`, `PLATINUM`, `PREPAID`, etc.

      **Note:** The possible returned values are numerous and liable to evolve over time.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ProfilingAttemptReference" type="string">
  The unique reference generated for the profiling session, used by the <a href="/guides/fraud-prevention">fraud prevention</a> solution to produce recommendations for the transaction using the profiling data.

  **Note:** Parameter not returned by the API. Profiling feature available on request – contact Mangopay <a href="https://hub.mangopay.com/" target="_blank">via the Dashboard</a> for more information.
</ParamField>