Overview
3D-Secure is a security protocol that provides an additional layer of security for online credit/debit card transactions. It allows an issuing bank to authenticate their cardholders during a CNP (Card Not Present) transaction. If the authentication is successful, liability for fraudulent transactions shifts away from the merchant to the card issuer, reducing chargebacks to the merchant.
This page describes the steps of the Server-to-Server 3D-secure payment flow.
- Render a Payment Form – Rendering a form using the Nuvei APIs to collect the cardholder details on your payment page.
- Authentication – Providing an authorization header with a bearer token required for the API requests.
- Sending a
/payment
API request – To determine if the card supports 3D-Secure, initialize the payment in the Nuvei system, return thefingerPrintingUrl
and other details required for the 3D-Secure fingerprinting. - Perform a 3DS fingerprinting – To authenticate the client-side device.
- Sending a second payment request – Submitting the fingerprint indicator in the
/payment/{paymentId}/fingerprint
API request.- If the issuer decides that transaction is frictionless, the transaction status can be approved or declined, the payment flow ends here.
- If the response returns the challenge status, you should redirect the customer to perform a 3D-Secure challenge.
- 3D-Secure Challenge – Performing 3D-Secure v2 Challenge to authenticate the identity of the customer.
- Final Payment Request – If a 3D-Secure challenge was performed, then perform a liability-shift payment by sending a
/payment/{paymentId}/challenge
request with a challenge indicator andcRes
.
1. Render a Payment Form
Render a form using the Nuvei APIs to collect the cardholder details on your payment page.
2. Authentication
Provide an authorization header with a bearer token required for the API requests.
3. 3D-Secure Payment
Perform 3DS payment by sending a /payment
request to determine whether the credit card supports 3D-Secure and what should be the next step in the process.
Provide the payment method (card) details by including either of these (not both):
- The
paymentOption.card
block with full card details. - Or, for a returning customer, you can provide their previously stored payment method, by including these parameters:
buyerDetails.buyerId
: “<unique customer identifier in merchant system>”paymentOption.paymentToken.paymentTokenId
: “<ID of a previously stored payment option>”
- The
paymentOption.card.threeD
containing mandatory fields:fingerprintNotificationUrl
: “<URL to which the issuer should send the fingerprinting notification response>”challengeNotificationUrl
: “<URL to which the issuer should send a notification after the 3D-Secure challenge step>” – This URL is needed for the next step 3D-Secure Challenge.challengeWindowSize
- Provide other optional fields in the
threeD
block to increase your chances of receiving fingerprint status:merchantUrl
– 3DS Requestor URL, the URL of the merchant’s fully qualified website.challenge.preference
– The merchant’s challenge/exemption preference for each transaction sent to the issuer during the 3DS v2 decision stage.
Possible values:- Challenge – You prefer that the issuer performs a challenge (even though this inconveniences your customer), and that the issuer ultimately accepts liability for the payment.
- ExemptionRequest – You are willing to accept the risk (liability) for the payment. You do not want the issuer to perform a challenge.
- NoPreference – This has the same effect as not sending the
challenge.preference
parameter.
buyerDetails
block containing:email
firstName
lastName
phone
(for 3DS card authentication if email is not provided)
buyerDetails.billingAddress
block containing:countryCode
address
zip
city
state
- deviceDetails: (new block added)
ipAddress
(for 3DS card authentication)browser.screenHeight
(for 3DS card authentication)browser.screenWidth
(for 3DS card authentication)
Example /payment
Request with 3DS Block
{ "processingEntityId": "<your processingEntityid>", "amount": "10.5", "currency": "USD", "paymentOption": { "store": "buyerToken", "card": { "cardNumber": "5101081046006034", "cardHolderName": "John Smith", "expirationMonth": "10", "expirationYear": "2026", "cvv": "345", "threeD": { "merchantUrl": "<merchantURL>", "fingerprintNotificationUrl": "<fingerprint notification URL", "challengeNotificationUrl": "<challenge notification URL>", "challengeWindowSize": "01", "platformType": "02" } } }, "deviceDetails": { "ipAddress": "<customer's IP address>" }, "buyerDetails": { "buyerId": "<unique customer identifier in your system>", "email": "[email protected]", "billingAddress": { "countryCode": "US" } } }
Example /payment
Response with 3DS Block and Fingerprint Status
{ "paymentId": "453681", "transactionId": "2110000000011428949", "externalTransactionId": "20230613202325336703000000", "amount": "10.5", "currency": "USD", "transactionType": "initAuth3D", "result": { "status": "fingerprint" }, "authCode": "075449", "partialApproval": { "requestedAmount": "10.5", "requestedCurrency": "USD" }, "paymentOption": { "card": { "cardHolderName": "John Smith", "maskedCardNumber": "5****6034", "bin": "400002", "last4Digits": "6034", "expirationMonth": "10", "expirationYear": "26", "acquirerId": "19", "cardType": "Credit", "cardBrand": "MASTERCARD", "paymentTokenId": "b4274bb4-7bb7-4658-ab92-ccec34618cc0", "merchantReference": "12391284AF87C7D2", "threeD": { "fingerprintUrl": "https://3dsn.sandbox.safecharge.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL", "fingerprintPayload ": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNjNDcxZTU4LWNjMDItNDU4YS1hNzUyLTZiMzNlZTQzMTMzMCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==", "dsTransId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "version": "2.1.0", "serverTransId": "3c471e58-cc02-458a-a752-6b33ee431330" } } } }
Handling the Response
- approved – The payment is approved in case of cascading the payment as non-3D payment. 3D block is not returned in the response.
- declined – The payment was declined by the card issuer and the transaction should not proceed to payment.
- fingerprint – Fingerprint step should be performed (see 3DS Fingerprinting).
- error – An error occurred.
4. Fingerprinting (Optional)
3D-Secure Fingerprinting for Web Browsers is an optional authentication step for 3D-Secure v2.
Prerequisites: In the previous step (3D-Secure Payment):
- The
fingerprintNotificationUrl
must have been included in the/payment
request. - The
fingerprintUrl
andfingerprintPayload
parameters should have been returned in the/payment
response.
Follow the steps described in 3DS Fingerprinting.
5. Second Payment Request
If in the previous payment response result.status
: “fingerprint” was returned, send a /payment/{paymentId}/fingerprint
request.
- Provide in the endpoint URL
paymentId
you received in the original in/payment
response. processingEntityId
- If 3DS Fingerprinting was performed, set the value of
fingerprintingIndicator
to “Y”.- Y – the merchant did fingerprint
- If 3DS Fingerprinting was not performed, set the value of
fingerprintingIndicator
to “N” or “U” to indicate “not done” or “unavailable”.- N – the merchant didn’t do fingerprinting
- U – the merchant didn’t do it because of technical reasons
Example /payment/{paymentId}/fingerprint
Request
{ "processingEntityId": "<your processingEntityId >" "fingerprintingIndicator": "<indicates whether the 3D-Secure v2 fingerprint challenge was successfully completed>" }
Example Response – Frictionless Flow
{ "paymentId": "34564567", "transactionId": "711000000028033669", "externalTransactionId": "20230613202325336703000000", "amount": "10.5", "currency": "USD", "transactionType": "Sale", "result": { "status": "approved" }, "authCode": "111844", "partialApproval": { "requestedAmount": "10.5", "requestedCurrency": "USD" }, "paymentOption": { "card": { "cardHolderName": "John Smith", "maskedCardNumber": "5101081046006034", "bin": "400002", "last4Digits": "6034", "expirationMonth": "10", "expirationYear": "26", "acquirerId": "19", "cardType": "Credit", "cardBrand": "MASTERCARD", "paymentTokenId": "b4274bb4-7bb7-4658-ab92-ccec34618cc0", "merchantReference": "12391284AF87C7D2", "threeD": { "version": "2.1.0", "eci": "5", "cavv": "AAQ2M0M5MEM5QzIzMkRFMUQ2NkQ=", "authenticationType": "02", "authenticationResult": "Y", "flow": "frictionless", "acsTransID": "b8301e4e-2e5b-4feb-a6f8-a768f1392ef4", "dsTransID": "7b1d3977-a2c0-45ec-9c23-ea47057a23ae", "challengePreferenceReason": "12", "acquirerDecision": "ExemptionRequest", "decisionReason": "NoPreference", "isLiabilityOnIssuer": "true" } } } }
Example Response – Challenge Status
{ "paymentId": "34564568", "transactionId": "711000000028033669", "externalTransactionId": "20230613202325336703000000", "amount": "500", "currency": "USD", "transactionType": "Auth3D", "result": { "status": "challenge" }, "authCode": "111095", "partialApproval": { "requestedAmount": "0", "requestedCurrency": "USD" }, "paymentOption": { "card": { "cardHolderName": "John Smith", "maskedCardNumber": "5****6034", "bin": "400002", "last4Digits": "6034", "expirationMonth": "12", "expirationYear": "25", "acquirerId": "19", "cardType": "Credit", "cardBrand": "VISA", "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "merchantReference": "12391284AF87C7D2", "threeD": { "version": "2.1.0", "eci": "7", "acsUrl": "https://3dsn.sandbox.safecharge.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL2RvY3MubnV2ZWkuY29tLzNEc2ltdWxhdG9yL25vdGlmaWNhdGlvblVybC5waHAiLCJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjJjYWE4NTU5LTcyNjktNDg3Ni05MTgxLTQwNjUyYjY2OTdlMCIsImFjc1RyYW5zSUQiOiIzYzVkZTY2Yi0zMzc3LTQ3OTgtOTQyMC01Yjc0YzNmMWE3MjQiLCJkc1RyYW5zSUQiOiI3NjU1NTgzMy05NTk5LTQ1MjAtYjBmYS1iNzg1ZjBkM2QzZmYiLCJkYXRhIjpudWxsLCJNZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=", "authenticationType": "01", "authenticationResult": "C", "acsChallengeMandated": "Y", "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjJjYWE4NTU5LTcyNjktNDg3Ni05MTgxLTQwNjUyYjY2OTdlMCIsImFjc1RyYW5zSUQiOiIzYzVkZTY2Yi0zMzc3LTQ3OTgtOTQyMC01Yjc0YzNmMWE3MjQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0", "flow": "challenge", "acsTransID": "ed7b1ab1-3d9c-4073-9a83-82805d84b474", "dsTransID": "852e23af-6446-4abb-9693-bde0ac2c5bb5", "isExemptionRequestInAuthentication": "0", "challengePreferenceReason": "12", "acquirerDecision": "ExemptionRequest", "decisionReason": "NoPreference" } } } }
Handling the Response
The response includes the result.status
parameter that can have one of these values:
- challenge – You must perform the 3D-Secure Challenge step.
- approved – Payment was approved, and the frictionless payment was made due to one of the following cases:
- A
cavv
value is returned, theeci
* value is either 5 (Visa) or 2 (Mastercard), and the issuer accepts liability (liability shift)
*The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3D-Secure program. - If you requested a 3D-Secure Exemption, the issuer has approved a non-3D transaction (the issuer does not accept liability (no liability shift).
- A
- declined – The payment was declined by the card issuer, and the transaction should not proceed to payment.
eci
is negative and nocavv
is returned.- A
code
andreason
are returned.
The response also includes:
- error – An error occurred. The 3D-Secure authentication failed.
6. 3D-Secure Challenge
For instructions on implementing the authentication challenge, see 3DS Authentication Challenge.
7. Final Payment Request
Perform the next relevant step based on the outcome of the 3D-Secure Challenge:
- If the customer did not complete the challenge successfully, then the process ends here.
For 3D-Secure v2 –cRes
would contain:transStatus
: “N“. - If the customer completed the challenge successfully, then:
For 3D-Secure v2 –cRes
would contain:transStatus
: “Y“.
Complete the payment process by sending a final Liability Shift Payment (3D-Secure v2) request (see below).
Liability Shift – 3D-Secure v2
If the 3D-Secure v2 challenge was successful, then complete the payment process by sending another /payment/{paymentId}/challenge
request and include these additional parameters:
processingEntityId
cRes
The paymenId
should be taken from the previous payment response.
Example Liability Shift /payment/{paymentId}/challenge
Request
{ "idempotencyId": "<the ID of the API request in the your system>", "processingEntityId": "<your processingEntityid>", "cRes": "Y" }
Example Liability Shift /payment/{paymentId}/challenge
Response
{ "paymentId": "34564569", "transactionId": "711000000028034738", "externalTransactionId": "20230613202325336703000000", "amount": "500", "currency": "USD", "transactionType": "Auth", "result": { "status": "approved" }, "authCode": "111818", "partialApproval": { "requestedAmount": "500", "requestedCurrency": "USD" }, "paymentOption": { "card": { "cardHolderName": "John Smith", "maskedCardNumber": "5****6034", "bin": "400002", "last4Digits": "6034", "expirationMonth": "12", "expirationYear": "25", "acquirerId": "19", "cardType": "Credit", "cardBrand": "MASTERCARD", "paymentTokenId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "merchantReference": "12391284AF87C7D2", "threeD": { "version": "2.1.0", "eci": "5", "cavv": "czFkVjllVGtFNHJsUzlNd3ZQVjQ=", "authenticationResult": "Y", "flow": "challenge", "acsTransID": "ed7b1ab1-3d9c-4073-9a83-82805d84b474", "dsTransID": "852e23af-6446-4abb-9693-bde0ac2c5bb5", "isExemptionRequestInAuthentication": "0", "challengePreferenceReason": "12", "acquirerDecision": "ExemptionRequest", "decisionReason": "NoPreference", "isLiabilityOnIssuer": "1" } } } }