All you need to know about 3D secure (integration, workflow, etc.)


3D Secure is a protocol designed to be an additional security layer for online credit and debit card transactions (definition). This payment security step is mainly available within Europe.

The API provides a 2 ways to trigger 3DS:

  • The automatic one. It is available by default and triggers 3DS from 50€ (and its equivalent within other currencies) 
  • The switchable one. Your app is able to trigger 3DS by is own on any transaction by card.




How does it work?


Your app creates a Payins request with 3D Secure (or triggered automatically):

  1. Mangopay sends the request to the user bank. 
  2. If the user's card supports 3DS the bank replies with a 3DS URL
  3. If the user's card doesn't support 3DS, the bank replies the card is not enrolled. 

Mangopay then replies to the Payins request:

  1. If the user's card supports 3DS, mangopay replies with the SecureModeRedirectURL on witch your app has to redirect his user to let authenticate himself.

  2. ​If the user's card doesn't support 3DS, we make the payment failed and the SecureModeRedirectURL will be empty and the error will be Secure mode: The card is not compatible with 3DSecure




3DS related API fields


Included into the PAYIN's body sent by your app to Mangopay

Value may be DEFAULT
(your app doesn't trigger the 3DS)

or FORCE (your app triggers the 3DS)


Included into the response body replied by Mangopay

This is the reference your app has to check. 


If the value is FALSE, the 3DS is not needed : your app can directly check the transaction status


If the value is TRUE, the 3DS is needed : your app has to redirect the user on the SecureModeRedirectURL



Included into the response body replied by Mangopay


This is the 3D secure interface URL


If the value of SecureModeNeeded is true : a URL is given to redirect the user on.


​​If the value of SecureModeNeeded is false : no URL given



Included both into the sent and response bodies


The URL is provided by your app

the user is automatically redirected
on after the 3DS step


So if the SecureModeNeeded is TRUE (and SecureModeRedirectURL provided) this only means we need the user going onto the 3DS step. 



Liability shift

For cards issued within the EU zone and for payment in EURO, even if the card doesn't support 3DS, the user bank will take the risk anyway and so the 3D secure step can be skipped so the API response will include a SecureModeRedirectURL field equal to the SecureModeReturnURL field. 

Also, for cards issued within the EU zone and for payment in EURO, and if the user has got an issue/failed on 3D secure interface, the user bank will take the risk anyway and so the 3D secure step can be skipped so the payment will not get an error Secure mode: The card is not compatible with 3DSecure even if the 3DS step failed. 

In sandbox, this rule is simulated as well. This is why you've got these behaviors. The things is this "feature" was activated for all currencies (only on Sandbox). This is new fixed and only available for EURO as it is on production environment.


In certain situation, we have the possibility to shift the liability for 3DS transactions to the bank, even if the 3DS verification fails.
  • It is however only in certain situations (see below) but overall we take into account:
    • Type of 3DS error
    • Acquiring bank
    • Card network
    • Country of origin of the card
    • Type of card
  • Note that the liability shift logic is stipulated by acquiring bank (Arkea for EUR) and therefore:
    • It is the same whether card direct/preauthorization or card web
    • Only EUR payments are supported
    • We have no possibility to change it


Here is the overall logic where the liability can be shifted:

  • Cards originating from France (regardless of the card type or network)
  • Mastercard type cards (regardless of country of origin or subtype)
  • Personal Visa cards (regardless of the country, except for the error DS/ACS)
  • Business Visa cards originating from Europe (except for the error DS/ACS)
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found