Last updated: 16 June 2026 | Change log
Use External 3DS when your customer has already completed 3DS authentication outside of Payments API.
With External 3DS, you perform authentication using your own MPI, 3DS Server, PSP, or authentication provider. You then submit the authentication result in the payment request using threeDS.type: "external".
If you want Worldpay to orchestrate 3DS authentication, use Integrated 3DS instead.
Card payment with External 3DS, where authentication is completed by your own MPI or 3DS provider before the payment request is submitted.
At a high level, the External 3DS payment flow works as follows:
- You authenticate the customer using your external 3DS provider.
- Your provider returns the 3DS authentication result.
- You submit the payment request to Payments API.
- You include the authentication result in
instruction.threeDS. - Payments API uses the supplied 3DS data when requesting authorization.
- The payment proceeds to authorization.
To use External 3DS, include threeDS.type: "external" in the payment request.
Use this pattern when your external 3DS provider returns a successful authentication result.
{
"instruction": {
...
"threeDS": {
"type": "external",
"version": "2.2.0",
"eci": "05",
"authenticationValue": "kBNHXUAy4+HT1gAMBSDajheBcxQh",
"dsTransactionId": "b8fb4ecc-7e2e-4b1c-816d-0149849776b8"
}
}
}- Use the values returned by your external 3DS provider. The authentication data must relate to the same customer, card, transaction, amount, and merchant context as the payment authorization request.
- The data can only be used once.
When External 3DS is used, a summary of the 3DS authentication may be returned in the final payment response.
{
"threeDS": {
"type": "external",
"outcome": "authenticated",
"version": "2.2.0",
"eci": "05"
}
}The response may also include authorization details, payment outcome, issuer details, and other payment information depending on the request and final authorization result.