> ## 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.

# Create a Card Validation

### Path parameters

<ParamField path="CardId" type="string" required>
  The unique identifier of the Card object, obtained during the card registration process.
</ParamField>

### Body parameters

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

<ParamField body="SecureModeReturnURL" type="string" required>
  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="IpAddress" type="string" required>
  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" required>
  Information about the browser used by the end user (author) to perform the payment.

  <Expandable title="properties">
    <ParamField body="AcceptHeader" type="string" required>
      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" required>
      Whether or not the end user’s browser has the ability to execute Java.
    </ParamField>

    <ParamField body="Language" type="string" required>
      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" required>
      The value representing the depth of the screen’s color palette for displaying images, in bits per pixel.
    </ParamField>

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

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

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

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

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

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

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

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

<ParamField body="PreferredCardNetwork" type="string">
  **Allowed 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="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="SecureMode" type="string">
  **Allowed values:** `DEFAULT`, `FORCE`, `NO_CHOICE`

  **Default value:** `DEFAULT`

  The mode applied for the <a href="/guides/payment-methods/card/3ds">3DS2 protocol</a> 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="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="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>

### Responses

<AccordionGroup>
  <Accordion title="200 - Created">
    <ResponseField name="Id" type="string">
      Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)

      The unique identifier of the object.
    </ResponseField>

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

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

      The status of the transaction.
    </ResponseField>

    <ResponseField name="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`).
    </ResponseField>

    <ResponseField name="SecureModeRedirectURL" type="string">
      Max. length: 255 characters

      The URL to which to redirect the user to proceed to 3DS2 validation.
    </ResponseField>

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

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

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

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

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

        <ResponseField name="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.
        </ResponseField>

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

        <ResponseField name="ScreenHeight" type="integer">
          Max. length: 6 characters

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

        <ResponseField name="ScreenWidth" type="integer">
          Max. length: 6 characters

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

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

        <ResponseField name="UserAgent" type="string">
          Max. length: 255 characters

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

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

    <ResponseField name="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>.
    </ResponseField>

    <ResponseField name="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).
    </ResponseField>

    <ResponseField name="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.*
    </ResponseField>

    <ResponseField name="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.*
    </ResponseField>

    <ResponseField name="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.
    </ResponseField>

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

    <ResponseField name="Type" type="string">
      **Returned values:** `CARD_VALIDATION`

      The type of the card validation.
    </ResponseField>

    <ResponseField name="Applied3DSVersion" type="string | null">
      **Returned values:** `V1`, `V2_1`

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

    <ResponseField name="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.
    </ResponseField>

    <ResponseField name="ResultMessage" type="string">
      The explanation of the result code.
    </ResponseField>

    <ResponseField name="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.
    </ResponseField>

    <ResponseField name="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">
        <ResponseField name="BIN" type="string">
          The 6-digit bank identification number (BIN) of the card issuer.
        </ResponseField>

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

        <ResponseField name="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.
        </ResponseField>

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

          The type of card product.
        </ResponseField>

        <ResponseField name="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.
        </ResponseField>

        <ResponseField name="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.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="AuthenticationResult" type="object | null" defaultOpen>
      Information about the authentication result, based on the request made by Mangopay and the decision of the issuer regarding the type of authentication to be enforced (if applicable).

      <Expandable title="properties">
        <ResponseField name="AuthenticationType" type="string | null">
          Response values: `CHALLENGE`, `FRICTIONLESS`, `DIRECT_AUTHORIZATION`

          The type of authentication:

          * `CHALLENGE` – The issuer requested SCA to be enforced (for example, using 3DS).
          * `FRICTIONLESS` – The transaction was exempted from SCA because an exemption was granted by the issuer.
          * `DIRECT_AUTHORIZATION` – The transaction was sent to the issuer for authorization without any frictionless or challenge (for example, if SCA doesn't apply).

          A `null` value typically indicates that authentication was not requested (for example, because the request failed before being sent) or a decision was not received.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Accordion>
</AccordionGroup>

<AccordionGroup>
  <Accordion title="400 - Only available for CB_VISA_MASTERCARD">
    ```json theme={null}
    {
        "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type": "param_error",
        "Id": "c67ea4b3-c144-4142-8fbd-aca45be840da",
        "Date": 1706044641.0,
        "errors": {
            "CardId": "The underlying card type is invalid. Only card type CB_VISA_MASTERCARD is accepted on this feature."
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - Card validation already pending">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"7a2d1d57-6c0e-4689-bb80-62222ae073ed#1687358437",
        "Date":1687358438.0,
        "errors":{
            "CardId":"This card is already being validated."
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - The card is already valid">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"7af030d9-c652-4cfa-a76b-ae445018ed6e#1687358113",
        "Date":1687358114.0,
        "errors":{
            "CardId":"This card is already VALID."
        }
    }  
    ```
  </Accordion>

  <Accordion title="400 - The card is invalid">
    ```json theme={null}
    {
        "Message":"One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
        "Type":"param_error",
        "Id":"7af030d9-c652-4cfa-a76b-ae445018ed6e#1687358113",
        "Date":1687358114.0,
        "errors":{
            "CardId":"This card is INVALID."
        }
    }  
    ```
  </Accordion>
</AccordionGroup>

<ResponseExample>
  ```json 200 - Created   theme={null}
  {
      "Id": "wt_b7f55dd5-d699-46da-8c43-51c166e116f9",
      "AuthorId": "user_m_01KHRMAQT1ZPVBWK2KYM6S0N7M",
      "Status": "CREATED",
      "SecureModeReturnURL": "http://example.com?cardValidationId=wt_b7f55dd5-d699-46da-8c43-51c166e116f9",
      "SecureModeRedirectURL": "https://api.sandbox.whenthen.co/payment-gateway/whenthen/threeDS/54b0c206-0a67-43d4-ace6-14a25697cf85/challenge?id=b7f55dd5-d699-46da-8c43-51c166e116f9&url=aHR0cHM6Ly9hcGkuc2FuZGJveC53aGVudGhlbi5jby9wYXltZW50cy8zRFNlY3VyZS81NGIwYzIwNi0wYTY3LTQzZDQtYWNlNi0xNGEyNTY5N2NmODUvZDNjNWI0ODMtNTdjMC00NzA2LTkxZTAtMjk4ZDA5ZWFhY2Mw&amount=MA&currency=RVVS",
      "SecureModeNeeded": true,
      "IpAddress": "466b:ed49:0966:f7fe:1e09:d7de:4e24:b612",
      "BrowserInfo": {
          "AcceptHeader": "application/json,text/javascript,*/*;q=0.01<",
          "JavaEnabled": true,
          "Language": "fr",
          "ColorDepth": 32,
          "ScreenHeight": 667,
          "ScreenWidth": 375,
          "TimeZoneOffset": -120,
          "UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
          "JavascriptEnabled": true
      },
      "PreferredCardNetwork": null,
      "SecureMode": "DEFAULT",
      "PaymentCategory": "ECommerce",
      "Type": "CARD_VALIDATION",
      "SecurityInfo": {
          "AVSResult": "NO_CHECK"
      },
      "ValidationUsage": "MIT",
      "Validity": "UNKNOWN",
      "CreationDate": 1771580513,
      "Applied3DSVersion": null,
      "ResultCode": null,
      "ResultMessage": null,
      "Tag": "Created using the Mangopay API Postman collection",
      "CardInfo": {
          "BIN": "497010",
          "IssuingBank": "LA BANQUE POSTALE",
          "IssuerCountryCode": "MA",
          "Type": "CREDIT",
          "SubType": null,
          "Brand": "VISA"
      },
      "AuthenticationResult": {
          "AuthenticationType": "CHALLENGE"
      }
  }
  ```
</ResponseExample>

<RequestExample>
  ```json REST   theme={null}
  {
      "AuthorId": "user_m_01KHRMAQT1ZPVBWK2KYM6S0N7M",
      "SecureModeReturnURL": "http://example.com",
      "IpAddress": "466b:ed49:0966:f7fe:1e09:d7de:4e24:b612",
      "Tag": "Created using the Mangopay API Postman collection",
      "BrowserInfo": {
          "AcceptHeader": "application/json,text/javascript,*/*;q=0.01<",
          "JavaEnabled": true,
          "Language": "fr",
          "ColorDepth": 32,
          "ScreenHeight": 667,
          "ScreenWidth": 375,
          "TimeZoneOffset": "-120",
          "UserAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
          "JavascriptEnabled": true
      },
      "PreferredCardNetwork":"CB",
      "SecureMode":"NO_CHOICE",
      "ValidationUsage":"CIT"
  }  
  ```

  ```ruby Ruby   theme={null}
  require 'mangopay'

  MangoPay.configure do |client|
      client.preproduction = true
      client.client_id = 'your-client-id'
      client.client_apiKey = 'your-api-key'
      client.log_file = File.join(Dir.pwd, 'mangopay.log')
  end
  ```

  ```java Java  theme={null}
  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;
  import com.mangopay.MangoPayApi;
  import com.mangopay.entities.CardValidation;
  import com.mangopay.entities.subentities.BrowserInfo;

  public class CreateCardValidation {
      public static void main(String[] args) throws Exception {
          MangoPayApi mangopay = new MangoPayApi();
          mangopay.getConfig().setClientId("your-client-id");
          mangopay.getConfig().setClientPassword("your-api-key");
          
          String userId = "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT";
          String cardId = "card_m_01HY0MA4E2WQ0NRYQJP8X8SXMB";
          
          BrowserInfo browserInfo = new BrowserInfo();
          browserInfo.setAcceptHeader("application/json,text/javascript,*/*;q=0.01<");
          browserInfo.setJavaEnabled(true);
          browserInfo.setLanguage("fr");
          browserInfo.setColorDepth(32);
          browserInfo.setScreenHeight(667);
          browserInfo.setScreenWidth(375);
          browserInfo.setTimeZoneOffset("-120");
          browserInfo.setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148");
          browserInfo.setJavascriptEnabled(true);

          CardValidation cardVal = new CardValidation();
          cardVal.setAuthorId(userId);
          cardVal.setSecureModeReturnUrl("http://example.com");
          cardVal.setIpAddress("159.180.248.187");
          cardVal.setBrowserInfo(browserInfo);
          cardVal.setTag("Created using the Mangopay Java SDK");

          CardValidation createCardValidation = mangopay.getCardApi().validate(cardId, cardVal);

          Gson prettyPrint = new GsonBuilder().setPrettyPrinting().create();
          String prettyJson = prettyPrint.toJson(createCardValidation);

          System.out.println(prettyJson);
      }
  }
  ```

  ```python Python   theme={null}
  import mangopay

  mangopay.client_id='your-client-id'
  mangopay.apikey='your-api-key'

  from mangopay.api import APIRequest
  handler = APIRequest(sandbox=True)

  from mangopay.resources import NaturalUser, CardValidation
  from mangopay.utils import BrowserInfo

  natural_user = NaturalUser.get('213600749')

  user_card_validation = CardValidation(
      author = natural_user,
      secure_mode_return_url = 'http://example.com',
      ip_address = '159.180.248.187',
      tag = 'Created with Mangopay Python SDK',
      browser_info = BrowserInfo(
          user_agent = 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148',
          screen_width = 375,
          screen_height = 667,
          color_depth = 32,
          language = 'EN',
          accept_header = 'application/json,text/javascript,*/*;q=0.01<',
          timezone_offset = '-120',
          java_enabled = True,
          javascript_enabled = True
      ),
      card_id = '213601128'
  )

  create_card_validation = user_card_validation.validate(card_id = user_card_validation.card_id)

  pprint(create_card_validation)  
  ```

  ```csharp .NET  theme={null}
  using MangoPay.SDK;
  using MangoPay.SDK.Entities;
  using MangoPay.SDK.Entities.POST;
  using Newtonsoft.Json;

  class Program
  {
      static async Task Main(string[] args)
      {
          MangoPayApi api = new MangoPayApi();

          api.Config.ClientId = "your-client-id";
          api.Config.ClientPassword = "your-api-key";

          var userId = "user_m_01J2TZ261WZNDM0ZDRWGDYA4GN";
          var cardId = "card_m_01J3049JBA2XPA7GC7GEFJRQG4";

          var cardValidation = new CardValidationPostDTO(
              userId,
              "http://www.mangopay.com/docs/please-ignore",
              "2001:0620:0000:0000:0211:24FF:FE80:C12C",
              new BrowserInfo {
                  AcceptHeader = "text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8",
                  JavaEnabled = true,
                  Language = "FR-FR",
                  ColorDepth = 4,
                  ScreenHeight = 1800,
                  ScreenWidth = 400,
                  JavascriptEnabled = true,
                  TimeZoneOffset = "+60",
                  UserAgent = "Mozilla/5.0 (iPhone; CPU iPhone OS 13_6_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148"
              },
              "Created using the Mangopay .NET SDK"
          );

          var createCardValidation = await api.Cards.ValidateAsync(cardId, cardValidation);

          string prettyPrint = JsonConvert.SerializeObject(createCardValidation, Formatting.Indented);
          Console.WriteLine(prettyPrint);
      }
  }
  ```
</RequestExample>