Skip to main content
POST
/
V2.01
/
{ClientId}
/
cards
/
{CardId}
/
validation
{
    "AuthorId": "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT",
    "SecureModeReturnURL": "https://docs.mangopay.com/please-ignore",
    "IpAddress": "159.180.248.187",
    "Tag": "Custom meta",
    "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"
}  

{
    "Id": "110e5f73-9bdc-4333-860d-84dc3ab0fb3a",
    "AuthorId": "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT",
    "Status": "SUCCEEDED",
    "SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?cardValidationId=110e5f73-9bdc-4333-860d-84dc3ab0fb3a",
    "SecureModeRedirectURL": null,
    "SecureModeNeeded": false,
    "IpAddress": "159.180.248.187",
    "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",
    "PaymentCategory": "ECommerce",
    "ValidationUsage": "CIT",
    "Validity": "VALID",
    "CreationDate": 1717085089,
    "AuthorizationDate": 1717085089,
    "Type": "CARD_VALIDATION",
    "Applied3DSVersion": "V2_1",
    "ResultCode": "000000",
    "ResultMessage": "Success",
    "Tag": "Custom meta",
    "CardInfo": {
        "BIN": "497010",
        "IssuingBank": "LA BANQUE POSTALE",
        "IssuerCountryCode": "MA",
        "Type": "CREDIT",
        "Brand": "VISA",
        "SubType": null
    }
}

​
Path parameters

​
CardId
string
required
The unique identifier of the Card object, obtained during the card registration process.

​
Body parameters

​
AuthorId
string
required
The unique identifier of the user at the source of the transaction.
​
SecureModeReturnURL
string
required
Max. length: 255 charactersThe 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.
​
Tag
string
Max. length: 255 charactersCustom 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.
​
BrowserInfo
object
required
Information about the browser used by the end user (author) to perform the payment.
​
PreferredCardNetwork
string
Allowed values: VISA, MASTERCARD, CB, MAESTROThe card network to use, as chosen by the cardholder, in case of co-branded cards.
​
PaymentCategory
string
Default value: ECommerceAllowed values: ECommerce, TelephoneOrderThe 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
Allowed values: DEFAULT, FORCE, NO_CHOICEDefault value: DEFAULTThe 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
Default value: MIT
Allowed values: MIT, CITIndicates 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
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.

​
Responses

​
Id
string
Max length: 128 characters (see data formats for details)The unique identifier of the object.
​
AuthorId
string
The unique identifier of the user at the source of the transaction.
​
Status
string
Returned values: CREATED, SUCCEEDED, FAILEDThe status of the transaction.
​
SecureModeReturnURL
string
Max. length: 255 charactersThe 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
Max. length: 255 charactersThe URL to which to redirect the user to proceed to 3DS2 validation.
​
SecureModeNeeded
boolean
Whether or not the SecureMode was used.
​
IpAddress
string
The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
​
BrowserInfo
object
Information about the browser used by the end user (author) to perform the payment.
​
PreferredCardNetwork
string
Returned values: VISA, MASTERCARD, CB, MAESTROThe card network to use, as chosen by the cardholder, in case of co-branded cards.
​
PaymentCategory
string
Default value: ECommerceAllowed values: ECommerce, TelephoneOrderThe 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
Default value: DEFAULT
Allowed values: DEFAULT, FORCE, NO_CHOICEThe mode applied for the 3DS 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
Default value: MIT
Allowed values: MIT, CITIndicates 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
Returned values: UNKNOWN, VALID, INVALIDWhether 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
Unix timestamp
The date and time at which the object was created.
​
Type
string
Returned values: CARD_VALIDATIONThe type of the card validation.
​
Applied3DSVersion
string
Returned values: V1, V2_1The 3DS protocol version applied to the transaction.
​
ResultCode
string
The code indicating the result of the operation. This information is mostly used to handle errors or for filtering purposes.
​
ResultMessage
string
The explanation of the result code.
​
Tag
string
Max. length: 255 charactersCustom 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.
​
CardInfo
string
Information about the card used for the transaction.If the information or data is not available, null is returned.
{
    "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."
    }
}  

{
    "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."
    }
}  

{
    "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."
    }
}  

{
    "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."
    }
}  

{
    "Id": "110e5f73-9bdc-4333-860d-84dc3ab0fb3a",
    "AuthorId": "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT",
    "Status": "SUCCEEDED",
    "SecureModeReturnURL": "https://docs.mangopay.com/please-ignore?cardValidationId=110e5f73-9bdc-4333-860d-84dc3ab0fb3a",
    "SecureModeRedirectURL": null,
    "SecureModeNeeded": false,
    "IpAddress": "159.180.248.187",
    "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",
    "PaymentCategory": "ECommerce",
    "ValidationUsage": "CIT",
    "Validity": "VALID",
    "CreationDate": 1717085089,
    "AuthorizationDate": 1717085089,
    "Type": "CARD_VALIDATION",
    "Applied3DSVersion": "V2_1",
    "ResultCode": "000000",
    "ResultMessage": "Success",
    "Tag": "Custom meta",
    "CardInfo": {
        "BIN": "497010",
        "IssuingBank": "LA BANQUE POSTALE",
        "IssuerCountryCode": "MA",
        "Type": "CREDIT",
        "Brand": "VISA",
        "SubType": null
    }
}

{
    "AuthorId": "user_m_01HT2NFK7Z2BRQNGNHMY30VVTT",
    "SecureModeReturnURL": "https://docs.mangopay.com/please-ignore",
    "IpAddress": "159.180.248.187",
    "Tag": "Custom meta",
    "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"
}