- v1.0.0-latest-prod
3DS is a protocol used to secure online credit & debit card transactions by having the customer interact with the card issuer to validate that they are the owner of the card. Once this validation is successfully complete, the merchant can execute transactions against the payment method with a drastically lowered fraud risk.
To achieve this verification, payment gateways use two primary patterns:
Verify the user’s ownership of the card prior to any transaction attempts
Allow the user & merchant to attempt a transaction, and then prompt for verification as needed. Successful completion of the verification is then required before the transaction is allowed to be processed.
In this document, we’ll focus on the second pattern.
This flow begins with attempting a payment transaction as part of checkout processing, as you would without 3DS being involved. Based on the information provided with this transaction, the card issuer will declare if the transaction is allowed to be processed (i.e. a "frictionless" flow) or if the transaction must be challenged. In the frictionless flow, the extra verification steps most commonly associated with 3DS do not need to be engaged. If the transaction is challenged, then typically the payment gateway will include a url in its response which the customer must be taken to, to verify their ownership of the card.
|
Note
|
Passing more information with these transactions allows the payment gateway & card issuers to make more informed fraud decisions. |
The same 3DS challenge url that’s returned from the payment gateway will be returned from CartOperationServices, along with a CheckoutResponse#failureType of PAYMENT_REQUIRES_3DS_VERIFICATION. In this case, the customer must be taken to the challenge url, either by redirect or within an iframe, to complete the extra verification step.
Once the customer verification step is successfully completed, card issuers and/or payment gateways often automatically execute the transaction. The implication of this is that an Authorize or AuthorizeAndCapture transaction was attempted outside of PaymentTransactionServices, and therefore, Broadleaf services don’t have awareness of the transaction attempt or results. Additionally, there may be a successful transaction that does not correlate to a checkout submission. To gain this awareness of the transaction & its result, we leverage the following approaches:
Once verification is complete & the transaction is executed, call the Record 3DS Transaction Results API in PaymentTransactionServices to record the result immediately.
NOTE: If the gateway does not support a transaction lookup for 3DS results, the endpoint for recording transaction results outside of PaymentTransactionServices can be used instead.
Listen to the gateway’s webhook notifications & record results for these transactions.
For subsequent checkout submissions, recognize the previous request for 3DS verification, & attempt to lookup transaction results, instead of attempting a new transaction for the payment. See DefaultPaymentTransactionExecutionService#lookup3DSTransactionResults(…) in CartOperationService.
|
Note
|
Once successful 3DS verification results are known (and hopefully transaction results as well), we suggest re-submitting checkout automatically. If the verification failed, then there’s no reason to resubmit checkout. In this case, the payment should be archived in PaymentTransactionServices, & a new form of payment should be requested from the customer. |
A subset of these approaches can be used, but we strongly suggest making use of all three, since they reinforce each other.
Approach 1 is the quickest & easiest way to become aware of transaction results.
If this approach is used, then the out-of-box Broadleaf checkout workflow will recognize that the payment is already processed, & it won’t attempt any additional transactions for this payment.
NOTE: With this approach, it’s very important to validate the authenticity of request to ensure that it can be trusted, & that we’re not recording fraudulent transaction results.
Approach 2 is the best means of guaranteeing that the Broadleaf system becomes aware of the transaction & its results.
Regardless of what happens with frontend interactions that could affect Approach 1 or Approach 3, we’ll always get webhook notifications.
If this approach is used, then the out-of-box Broadleaf checkout workflow will recognize that the payment is already processed, & it won’t attempt any additional transactions for this payment.
Approach 3 is the final back-stop to ensure that we understand transaction results for the 3DS interaction.
If successful transaction results are found, then the checkout process will continue beyond this payment.
If failed transaction results are found, then the checkout process will be blocked in the same way that would be done for any other failed payment transaction.
If transaction results are still not known, then the transaction & checkout responses will reflect the original request for 3DS verification.