> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/api-reference/card-validations/create-card-validation/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Create a Card Validation

POST https://api.sandbox.mangopay.com/v2.01/{ClientId}/cards/{CardId}/validation
Content-Type: application/json

Create a Card Validation

Reference: https://docs.mangopay.com/api-reference/card-validations/create-card-validation

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token. If your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL.

## Servers

- `https://api.sandbox.mangopay.com` (Sandbox, default)
- `https://api.mangopay.com` (Production)
- `https://api-mtls.sandbox.mangopay.com` (mTLS Sandbox)
- `https://api-mtls.mangopay.com` (mTLS Production)

## Request

### Path parameters

- `ClientId` (string, required) — Platform's API account identifier, associated with the API key.
- `CardId` (string, required) — The unique identifier of the Card object, obtained during the card registration process.

### Body (application/json)

This endpoint expects a CreateACardValidationRequest.

- `AuthorId` (string, required) — The unique identifier of the user at the source of the transaction.
- `SecureModeReturnURL` (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`).
- `IpAddress` (string, required) — The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
- `BrowserInfo` (BrowserInfo, required) — Information about the browser used by the end user (author) to perform the payment.
- `Tag` (string, optional) — Max. length: 255 characters Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.
- `PreferredCardNetwork` (string, optional) — **Allowed values:** `VISA`, `MASTERCARD`, `CB`, `MAESTRO` The card network to use, as chosen by the cardholder, in case of co-branded cards.
- `PaymentCategory` (string, optional) — **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).
- `SecureMode` (string, optional) — **Allowed values:** `DEFAULT`, `FORCE`, `NO_CHOICE` **Default value:** `DEFAULT` The mode applied for the 3DS2 protocol 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.
- `ValidationUsage` (string, optional) — **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._
- `ProfilingAttemptReference` (string, optional) — The unique reference generated for the profiling session, used by the fraud prevention 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 via the Dashboard for more information.

## Response

### 200

Success

- `Id` (string, optional) — Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details) The unique identifier of the object.
- `AuthorId` (string, optional) — The unique identifier of the user at the source of the transaction.
- `Status` (string, optional) — **Returned values:** `CREATED`, `SUCCEEDED`, `FAILED` The status of the transaction.
- `SecureModeReturnURL` (string, optional) — 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`).
- `SecureModeRedirectURL` (string, optional) — Max. length: 255 characters The URL to which to redirect the user to proceed to 3DS2 validation.
- `SecureModeNeeded` (boolean, optional) — Whether or not the `SecureMode` was used.
- `IpAddress` (string, optional) — The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
- `BrowserInfo` (BrowserInfo, optional) — Information about the browser used by the end user (author) to perform the payment.
- `PreferredCardNetwork` (string, optional) — **Allowed values:** `VISA`, `MASTERCARD`, `CB`, `MAESTRO` The card network to use, as chosen by the cardholder, in case of co-branded cards.
- `PaymentCategory` (string, optional) — **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).
- `SecureMode` (string, optional) — **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._
- `ValidationUsage` (string, optional) — **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._
- `Validity` (string, optional) — **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.
- `CreationDate` (integer, optional) — Unix timestamp (UTC) of the date and time the object was created.
- `Type` (string, optional) — **Returned values:** `CARD_VALIDATION` The type of the card validation.
- `Applied3DSVersion` (string, optional) — **Returned values:** `V1`, `V2_1` The 3DS protocol version applied to the transaction.
- `ResultCode` (string, optional) — The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.
- `ResultMessage` (string, optional) — The explanation of the result code.
- `Tag` (string, optional) — Max. length: 255 characters Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.
- `CardInfo` (CardInfo, optional) — Information about the card used for the transaction. If the information or data is not available, `null` is returned.
- `AuthenticationResult` (AuthenticationResult, optional) — 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).

## Errors

### 400 Bad Request Error

Bad Request

- `Message` (string, optional) — Description of the error.
- `Type` (string, optional) — The category of the error.
- `Id` (string, optional) — Unique identifier of the error instance, useful when contacting Mangopay for support.
- `Date` (double, optional) — Unix timestamp (UTC) of the date and time the error was triggered.
- `errors` (map from string to string, optional, nullable) — Object containing one or more field-level errors.

## Types

### BrowserInfo

Information about the browser used by the end user (author) to perform the payment.

- `AcceptHeader` (string, required) — The exact content of the HTTP accept headers as sent to the platform from the end user's browser.
- `JavaEnabled` (boolean, required) — Whether or not the end user's browser has the ability to execute Java.
- `Language` (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.
- `ColorDepth` (integer, required) — The value representing the depth of the screen's color palette for displaying images, in bits per pixel.
- `ScreenHeight` (integer, required) — The height of the screen in pixels.
- `ScreenWidth` (integer, required) — The width of the screen in pixels.
- `TimeZoneOffset` (integer, required) — The difference in minutes between the browser's timezone and UTC.
- `UserAgent` (string, required) — The exact content of the HTTP User-Agent header.
- `JavascriptEnabled` (boolean, required) — Whether or not the end user's browser has the ability to execute JavaScript.

### CardInfo

Information about the card used for the transaction. If the information or data is not available, `null` is returned.

- `BIN` (string, optional) — The bank identification number (BIN) of the card.
- `IssuingBank` (string, optional) — The name of the bank that issued the card.
- `IssuerCountryCode` (string, optional) — The country code of the card issuer.
- `Type` (string, optional) — The type of card (for example, `CREDIT` or `DEBIT`).
- `SubType` (string, optional, nullable) — The sub-type of the card, if available.
- `Brand` (string, optional) — The card brand (for example, `VISA` or `MASTERCARD`).

### AuthenticationResult

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

- `AuthenticationType` (string, optional, nullable) — **Returned 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. 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.

## Examples

**Request**

```json
{
  "body": {
    "AuthorId": "user_m_01KHRMAQT1ZPVBWK2KYM6S0N7M",
    "BrowserInfo": {
      "AcceptHeader": "application/json,text/javascript,*/*;q=0.01<",
      "ColorDepth": 32,
      "JavaEnabled": true,
      "JavascriptEnabled": true,
      "Language": "fr",
      "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"
    },
    "IpAddress": "466b:ed49:0966:f7fe:1e09:d7de:4e24:b612",
    "PreferredCardNetwork": "CB",
    "SecureMode": "NO_CHOICE",
    "SecureModeReturnURL": "http://example.com",
    "Tag": "Created using the Mangopay API Postman collection",
    "ValidationUsage": "CIT"
  }
}
```

**Response**

```json
{
  "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,
  "PaymentCategory": "ECommerce",
  "SecureMode": "DEFAULT",
  "ValidationUsage": "MIT",
  "Validity": "UNKNOWN",
  "CreationDate": 1771580513,
  "Type": "CARD_VALIDATION",
  "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"
  },
  "SecurityInfo": {
    "AVSResult": "NO_CHECK"
  }
}
```

**SDK Code**

```python
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 = 'https://docs.mangopay.com/please-ignore',
    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)

```

```java
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("https://docs.mangopay.com/please-ignore");
        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);
    }
}

```

```csharp
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);
    }
}

```

```ruby
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

```