{"_id":"5cc87f5b7fae12018477ff6f","project":"555fbba928249c1900618a82","user":{"_id":"5c4b4e5b39a20b00dc863b8a","username":"","name":"Dominique Saulet"},"__v":0,"metadata":{"title":"","description":"","image":[]},"hidden":false,"createdAt":"2019-04-30T17:01:15.411Z","fullscreen":false,"htmlmode":false,"html":"","body":"[block:api-header]\n{\n  \"title\": \"Overview and Purpose of this Guide\"\n}\n[/block]\nThe purpose of this guide is to provide you with the information you need to fully implement Strong Customer Authentication (SCA) using the 3-D Secure (3DS) protocol in order to satisfy the requirements of Payment Services Directive 2 (PSD2).   If you haven't already, we recommend that you read more about PSD2, 3DS, and SCA [here](https://docs.recurly.com/docs/revised-payment-services-directive-psd2) before proceeding with this guide. You can also refer to the [Key Terms and Glossary](#key-terms--glossary) section of this guide to refresh your memory on any important definitions.\n\nWhile SCA largely consists of an integration effort between you and your configured payment gateway(s), Recurly, as your billing solutions provider, is here to help make the integration as easy as possible. As such, we have made key updates to several of our existing platform components in order to help facilitate SCA requirements in relation to PSD2. This document is here to provide you with a high-level understanding SCA, the Recurly solution, and a step-by-step guide to help you complete the integration.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Merchant Initiated Transactions (MIT) and Dunning\",\n  \"body\": \"For recurring, Merchant Initiated Transactions (MIT), SCA should not be required. However, there will be scenarios where a SCA challenge may still be presented by a customer's issuing bank, which will require customer authentication.  In order to assist you in recovering revenue that may be lost from failed MITs, Recurly has built support for a flow to complete a SCA challenge for re-authentication. Please see setup instructions for our fully hosted dunning solution [here](https://docs.recurly.com/docs/dunning-configuration-for-3ds-2-declines)\\n\\nIf you'd like to implement your own dunning solution, you can listen for the [new dunning event webhook](https://dev.recurly.com/page/webhooks#dunning-event-notifications) which will be sent when a recurring payment fails due to an Issuers request for 3DS2 authentication.  The payload will indicate that the failure type is `three_d_secure_action_required` and provide the relevant invoice number. The [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice) endpoint can then used to finalize the transaction. The guide below, starting at [step 2](#section--step-2-submit-a-transaction-request) can be used for reference.\\n\\nThe 3DS2 dunning flow, hosted or custom, can be tested with the following test credit card: '4000008400001629'\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This guide is focused on helping you to support 3DS2 integrations for scenarios where your customers are 'in session' and directly interacting with the the transaction flow online. If you are supporting / building a solution that is used by call center agents who complete transactions on behalf of customers over the phone, you can bypass 3DS2 / SCA as these types of transactions are exempt from PSD2. This is done by passing an exemption flag via the Recurly API. See the [reference documentation](https://dev.recurly.com/docs/create-an-accounts-billing-info-token) for more details\\n\\n**Please be aware that certain payment gateways require additional configuration in order for MOTO exemptions to work properly. See our [gateway specific documentation](https://docs.recurly.com/docs/gateway-specific-updates) for details.** \",\n  \"title\": \"PSD2 Exemptions for Mail Order Telephone Order (MOTO) Transactions\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Key Terms / Glossary\"\n}\n[/block]\nHere are a few key terms that will be referenced throughout this guide.\n\n* **Access Control Server (ACS)**\nA service either hosted or related to the Issuing bank. Responsible for issuing challenge URLs, generating device fingerprints, and verifying that the cardholder is non-fraudulent.\n\n* **Merchant plug-in (MPI)**\nA module, designed to facilitate 3-D Secure verification and prevention of payment card fraud. Verifies the card number with the card issuing bank and checks if it is enrolled in the 3-D Secure program. Typically provided by your payment gateway and used to facilitate interactions between merchants and the issuing bank responsible for completing the SCA process. The Recurly SCA framework wraps MPI functionality provided by various payment gateways.\n\n* **Strong Customer Authentication (SCA)**\nRequirement mandated by the European Economic Area (EEA) that ensures electronic payments are performed with multi-factor authentication.  For more details check out our [docs](https://docs.recurly.com/docs/revised-payment-services-directive-psd2#section-strong-customer-authentication-sca)\n\n* **3-D Secure (3DS)**\nE-commerce authentication protocol that implements SCA.  There are currently two versions of the protocol in effect, with 3DS 2.0 being the newest, and 3DS 1.0 used as a fallback until it is completely retired at a later date.  \n\n* **Payment Services Directive 2 (PSD2)**\nEEA directive that is enforced as of September 14, 2019 requiring SCA to be in place.  For more details check out our [docs](https://docs.recurly.com/docs/revised-payment-services-directive-psd2#section-strong-customer-authentication-sca)\n[block:api-header]\n{\n  \"title\": \"Understanding the SCA Flows\"\n}\n[/block]\nSCA can be subdivided into a few different flows, each of which requires various degrees of engagement from your customers and/or a few extra steps from you in the implementation process. The Recurly SCA framework and this integration guide provide you with everything you need to account for each, but it is helpful to understand them and when they come into play.\n\n#### Frictionless\nJust as the name implies, this requires the least amount of effort from you and your customers. In fact, it is completely seamless and is the most ideal case if it can facilitated. In this flow, the card Issuer determines that it has enough information to authenticate the transaction without any further verification steps. As part of the initial authentication attempt, Recurly will pass on any available customer details to your payment gateway via the provided MPI, which will work with the Issuers’ ACS to determine if a frictionless flow can be used for the transaction.\n\n#### Fingerprint\nIn some cases, the Issuer may require a device fingerprint as additional verification data before it will authenticate the transaction. While this will not require any interaction from your customers, there are a few extra steps, detailed in the step-by-step guide below, that are required on your part to ensure this happens. \n\n#### Challenge\nThis flow requires direct interaction between your customer and the Issuers’ ACS before authentication can be confirmed. If a challenge is requested, your customer will be prompted for extra information to further prove their identity.\n[block:api-header]\n{\n  \"title\": \"The Recurly SCA Solution\"\n}\n[/block]\nThe Recurly solution to SCA is comprehensive and designed to simplify the process for you as much as possible. Because most payment gateways have taken a slightly different approach to implementing their MPIs, integrations can be substantially different and could require heavy development effort on your part. As such, we have designed our SCA solution with the following as key design goals:\n\n#### Simplify Complexity\nOur solution minimizes the complexity and effort required for you to integrate by building high-level abstractions around the low-level functionality provided by many of the payment gateway MPIs.\n\n#### Payment Gateway MPI Agnostic\nThe Recurly solution provides a one-to-many integration that normalizes payment gateway  specific implementations, giving you the flexibility to use the solution that you need today, without being locked into it should your business needs evolve. This allows you to build your SCA flow once without the need to start from scratch if you decide to migrate to a different payment gateway. \n[block:api-header]\n{\n  \"title\": \"Required Components and Prerequisites\"\n}\n[/block]\n### Recurly.js \n\nThe existing Recurly.js JavaScript library has been enhanced to provide you with the functionality needed to implement the client side requirements of 3DS2 / SCA, such as device fingerprinting and rendering the challenge flows. This functionality is provided as a wrapper interface around the many client side libraries maintained by the various payment gateways.  **Recurly.js version 4 is required for 3DS2 / SCA** .  \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"See the [Recurly.js 3D Secure documentation](https://dev.recurly.com/docs/recurly-js-3d-secure) for a complete reference\"\n}\n[/block]\nIf you are not already using Recurly.js for other purposes, you can read more about it [here](https://dev.recurly.com/docs/recurlyjs), and / or follow [this guide](https://dev.recurly.com/docs/recurly-js-getting-started) to get up and running. \n\n### Recurly API / Client Libraries\n**You will need to use version 2.21 (or higher)** of the Recurly API or one of its associated client libraries for 3DS2 / SCA.  \n\n If you are using our API or client libraries for the first time, you can get started [here](https://dev.recurly.com/docs/getting-started). \n\n If you are upgrading from an earlier version of the API or a client library you can use these [upgrade guides](https://dev.recurly.com/page/recurly-v2-api-support-policy-and-roadmap#client-library-upgrade-guides) to help identify any breaking changes that will need to be addressed.\n[block:api-header]\n{\n  \"title\": \"Key Objects & Parameters\"\n}\n[/block]\nThe following list provides a quick reference for several key objects and parameters that will be used in conjunction with Recurly.js and the Recurly API in order to implement SCA.\n\n* **Credit Card Token**\nSecure token generated by Recurly.js to encapsulate sensitive billing information such as customer credit card numbers.  Also includes additional customer / browser data collected by Recurly.js and used for SCA purposes.\n\n* **3-D Secure Action Token**\nToken generated by Recurly API to encapsulate data needed for Recurly.js to initiate the client-side authentication challenge and / or device fingerprinting. \n\n* **3-D Secure Action Result Token**\nToken generated by Recurly.js to encapsulate data captured as a result of the client-side authentication challenge and / or device fingerprinting.\n\n* **Recurly.js ThreeDSecure Class**\nRecurly.js class that is instantiated to provide SCA-specific client-side functionality such as handling challenge flows.\n[block:api-header]\n{\n  \"title\": \"Integration Guide\"\n}\n[/block]\n### **Step 1:** Collect payment data with Recurly.js\n\nIn most cases, credit card tokenization with Recurly.js is optional from a 3DS2 / SCA perspective *(see the callout below for cases where it is required)*. However, you may want to consider using it as we have enhanced Recurly.js to collect additional customer data ( ie. browser info) as part of the credit card tokenization process.  When possible, this data is passed on to the Issuers’ ACS via the payment gateway MPI in the initial authentication request, and could increase the chances that the transaction is approved in a frictionless manner.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"If you are using the **Wirecard, Sagepay, or Worldpay gateways**, **credit card tokenization with Recurly.js is required for all 3DS2 flows**.  These gateways require device data to be sent with the initial transaction.\"\n}\n[/block]\nIf you are already using Recurly.js to tokenize customer credit cards then there is no additional action required, as the enhancement described above will work automatically once you’ve upgraded to Recurly.js version 4\n\nIf you’re interested in taking advantage of this feature, see [this section of our documentation](https://dev.recurly.com/docs/recurly-js-getting-a-token) to get up and running with Recurly.js credit card tokenization.  Again, this step is optional, but could lead to an increased number of transactions that are approved via the frictionless flow, which is beneficial from a customer experience and conversion perspective.\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n\n### **Step 2:** Submit a transaction request\n\nIf you have decided to tokenize the credit card as described in Step 1, you are now able be able to send it along to the appropriate Recurly API endpoint to initiate the payment transaction. Otherwise, the raw customer billing info can be passed instead.  Transactions can be requested using the  [Create Purchase](https://dev.recurly.com/docs/create-purchase),  [Create Subscription](https://dev.recurly.com/docs/create-subscription), or [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice) endpoints\n\nSimilar to the previous step, this guide assumes that you are already using Recurly API or the client libraries to process payment transactions with Recurly. As such, there should be no additional work required for this step in the SCA flow aside from ensuring that you have **upgraded to (at least) version 2.21 of the Recurly API**. For more information on completing the standard payment integration, please see our [documentation](https://dev.recurly.com/docs).\n\n\nSee the 'Under the Hood' section below if you'd like to know more about the enhancements Recurly has made to facilitate this step in the SCA flow, otherwise continue on to Step 3.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Under the Hood\",\n  \"body\": \"Once your request is received by the Recurly platform, billing info details, including the browser-level details required for SCA, will be extracted from the [Credit Card Token](#key-objects--parameters) and passed through to your payment gateway. If you are not tokenizing your credit cards with Recurly, we will use the raw credit card / billing info passed in the  request to initiate the SCA process via the payment gateway.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n### **Step 3:** Process the response\n\nIf the transaction request is successful, Recurly API will return a success response code to your server and no additional action is needed from an authentication perspective.\n\nHowever, if the payment gateway requires additional action as part of the SCA flow, Recurly will indicate this with a new error code, called `three_d_secure_action_required`, in the API response.\n\n If this error code is returned, it will be accompanied with a `three_d_secure_action_token_id`, which references the [3-D Secure Action Token](#key-objects--parameters) that encapsulates data required for the next steps in the authentication flow. See below for the example response XML.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<errors>\\n  <transaction_error>\\n    <error_code>three_d_secure_action_required</error_code>\\n    <three_d_secure_action_token_id>ABCDEFGHIJKL012345</three_d_secure_action_token_id>\\n    ...\\n  </transaction_error>\\n  <transaction href=\\\"...\\\" type=\\\"credit_card\\\">\\n    ...\\n  </transaction>\\n</errors>\\n\",\n      \"language\": \"xml\"\n    }\n  ]\n}\n[/block]\nFor your part, you will need to pass the `three_d_secure_action_token_id` from your server to the client and instantiate a new instance of the Recurly.js ThreeDSecure class, passing in the `three_d_secure_action_token_id` as a parameter. See below for an example.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"const risk = recurly.Risk();\\nconst threeDSecure = risk.ThreeDSecure({ actionTokenId: 'ABCDEFGHIJKL012345' });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\nIf you'd like to know more details about what's going on under the hood, take a look below, otherwise proceed to Step 4.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Under The Hood\",\n  \"body\": \"When you instantiate the Recurly.js ThreeDSecure class with the `three_d_secure_action_token_id`, Recurly.js unpacks the associated [3-D Secure Action Token](#key-objects--parameters) in order to extract several details required to execute the next steps in the SCA flow on your behalf. For instance, one data point instructs Recurly.js as to which type of challenge to present to the customer (i.e. fingerprint, etc.), while another data point tells it which payment gateway MPI to leverage in order to complete the challenge.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n### **Step 4:** Setup event handlers and initiate Fingerprint / Challenge\n\nNext, you'll need to setup event handlers on the instance of the [Recurly.js ThreeDSecure class](#key-objects--parameters) that you created in the previous step. These event handlers will process the success and error responses related to the Fingerprint / Challenge results returned from the Issuers’ ACS. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"threeDSecure.on('error', err => {\\n  // display an error message to your user requesting they retry\\n  // or use a different payment method\\n});\\n\\nthreeDSecure.on('token', token => {\\n  // send `token.id` to your server to retry your API request\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf the Fingerprint or Challenge is successful and the 'token' handler is triggered, Recurly.js will pass in a `three_d_secure_action_result_token_id`, which references the [3-D Secure Action Result Token](#key-objects--parameters) which in turn encapsulates data returned from the Issuers’ ACS. With this handler you should pass the token id back to your server and then retry the original purchase request via the Recurly API. Step 6 of this guide will provide further details on this.\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n### **Step 5:** Initiate the Fingerprint / Challenge\n\nOnce your event handlers are setup, you'll need to initiate the Fingerprint / Challenge flow by attaching a reference to an HTML element to your instance of the [Recurly.js ThreeDSecure class](#key-objects--parameters).  This HTML element is a container for Recurly.js to render UI elements related to the challenge.   \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"threeDSecure.attach(document.querySelector('#my-container'));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The UI elements that Recurly.js injects will size to the dimensions of your container. Since the flow itself must be contained within an iframe controlled by your customer's bank, we are unable to dynamically size the flow. Thus, we recommend that your container have specific dimensions set at a minimum of 250px (W) x 400px (H), and contain an interstitial message to explain that 3-D Secure authentication will be required to complete the transaction.\\n\\n**Certain payment gateways (e.g. Stripe) will render the challenge frame as a modal interface, therefore it is advised that you do not place your container in a modal of your own.** \"\n}\n[/block]\nRecurly.js will then initiate the Fingerprint / Challenge using the appropriate payment gateway provided JavaScript library. Once completed, the event handlers that you setup in the previous step will be called depending on if there's a success or failure.\n\nOf course, there's a lot more going on behind the scenes. See below if you'd like to know more, or move on to step 6.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Under the Hood\",\n  \"body\": \"Because every payment gateway provides a different JavaScript library to complete the Fingerprint / Challenge step in the SCA flow, Recurly.js implements several different wrapper components and then leverages the correct one based on information encapsulated in the  [3-D Secure Action Token](#key-objects--parameters). However, it does this without requiring your code to know the difference or couple itself to any specific integration.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n### **Step 6:** Submit new purchase request \n\nAs part of the success event handler that you setup in step 4, initiate a new request to Recurly API  from your server using the provided `three_d_secure_action_result_token_id`. Recurly will use this token id to unpack data from the [3-D Secure Action Result Token](#key-objects--parameters) and pass it on to your payment gateway when it attempts to authenticate the transaction once again.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The `three_d_secure_action_result_token_id` is a valid parameter on the [Create Billing Info](https://dev.recurly.com/docs/create-an-accounts-billing-info-token) endpoint and on any Recurly API endpoint that accepts a Billing Info, including [Create Purchase](https://dev.recurly.com/docs/create-purchase), [Create Subscription](https://dev.recurly.com/docs/create-subscription), [Update Subscription](https://dev.recurly.com/docs/update-subscription), [Create Account](https://dev.recurly.com/docs/create-an-account), [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice), [Create Gift Card](https://dev.recurly.com/docs/create-gift-card)\\n\\n\\nWhen you submit the new request it is essential that the Account / billing info / credit card token match that of the previous request as the authentication data encapsulated in the [3-D Secure Action Result Token](#key-objects--parameters) is tightly coupled to the payment information and customer account.  Changing the Account / billing info / credit card token between requests will result in a token mismatch error.  \\n\\nIt is also invalid to mix and match 3DS Action Result Token Ids between different API endpoints.  For example, A 3DS Action Result Token Id obtained as part of the authentication process with the Create Account / Billing Info endpoint, can not be passed into the Create Subscription endpoint. A new token must be generated in this case if the endpoint requires 3DS2 authentication.\"\n}\n[/block]\nIf the request is successful, then no further action is required. If the request results in an error, you should handle this per your current standard integration (ie. collect alternate payment from the customer and retry the transaction) \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"**Note:** It is possible to get 3DS2 / SCA challenge requests on an Account / Billing Info that has been previously authenticated when you make subsequent API calls at a later date/time. For example, an API call to update a subscription could result in a new authentication challenge even if the initial action to create the subscription passed authentication.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Under the Hood\",\n  \"body\": \"When your server submits the new purchase request to Recurly API along with the `three_d_secure_action_result_token_id`, Recurly unpacks the authentication data returned from the Issuers’ ACS and then reattempts the authentication with your payment gateway based on their specific schema and API. The response data  is then normalized and returned to your server per the Recurly spec.\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br />\"\n}\n[/block]\n### **Step 7:** Testing \n\nTest that your integration can handle all SCA flows properly by using the Recurly Test Gateway and one of the following four test credit cards depending on the flow that you'd like to verify.  Your Recurly site must be in 'Sandbox' mode in order to use the Test Gateway.\n\n4000000000003220 - challenge flow\n4000000000003063 - (device) fingerprint flow\n4222222222222220 - approved fraud review ( frictionless flow)\n\nThe following test credit card can be used to test recurring transaction challenges (dunning flow) as well as the 'Update Subscription' endpoint. It will simulate a 3DS2 challenge any time a transaction is attempted:\n\n4000008400001629\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"When you are ready to test the integration with your payment gateway,  [contact](http://support.recurly.com) the Recurly support team for assistance in configuring your site in 'Development' mode. You'll need to contact your gateway in order to obtain their specific set of test credit cards for 3DS2. Please also see our guide on gateway specific configurations [here](https://docs.recurly.com/docs/gateway-specific-updates)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"**SagePay is not supported for testing in Development mode at this time due to requirements that cannot be implemented outside of Production mode.**\\n\\nFor the above gateways, testing will need to be performed in Sandbox mode, using the Recurly Test Gateway and test credit cards\",\n  \"title\": \"The following payment gateways do not support 3DS2 testing in Development mode\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\",\n  \"body\": \"Braintree supports 3DS2 testing in Development mode, but an amount of '2099.00' must be used to trigger the 3DS2 challenge frame. Also note that it is not possible to complete the authentication beyond the initial display of the challenge frame.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Additional Support\"\n}\n[/block]\nIf you need additional support with your SCA integration, do not hesitate to [contact](http://support.recurly.com) our support team","slug":"recurly-3d-secure-2-integration-guide","title":"Strong Customer Authentication (SCA) Integration Guide"}

Strong Customer Authentication (SCA) Integration Guide


[block:api-header] { "title": "Overview and Purpose of this Guide" } [/block] The purpose of this guide is to provide you with the information you need to fully implement Strong Customer Authentication (SCA) using the 3-D Secure (3DS) protocol in order to satisfy the requirements of Payment Services Directive 2 (PSD2). If you haven't already, we recommend that you read more about PSD2, 3DS, and SCA [here](https://docs.recurly.com/docs/revised-payment-services-directive-psd2) before proceeding with this guide. You can also refer to the [Key Terms and Glossary](#key-terms--glossary) section of this guide to refresh your memory on any important definitions. While SCA largely consists of an integration effort between you and your configured payment gateway(s), Recurly, as your billing solutions provider, is here to help make the integration as easy as possible. As such, we have made key updates to several of our existing platform components in order to help facilitate SCA requirements in relation to PSD2. This document is here to provide you with a high-level understanding SCA, the Recurly solution, and a step-by-step guide to help you complete the integration. [block:callout] { "type": "info", "title": "Merchant Initiated Transactions (MIT) and Dunning", "body": "For recurring, Merchant Initiated Transactions (MIT), SCA should not be required. However, there will be scenarios where a SCA challenge may still be presented by a customer's issuing bank, which will require customer authentication. In order to assist you in recovering revenue that may be lost from failed MITs, Recurly has built support for a flow to complete a SCA challenge for re-authentication. Please see setup instructions for our fully hosted dunning solution [here](https://docs.recurly.com/docs/dunning-configuration-for-3ds-2-declines)\n\nIf you'd like to implement your own dunning solution, you can listen for the [new dunning event webhook](https://dev.recurly.com/page/webhooks#dunning-event-notifications) which will be sent when a recurring payment fails due to an Issuers request for 3DS2 authentication. The payload will indicate that the failure type is `three_d_secure_action_required` and provide the relevant invoice number. The [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice) endpoint can then used to finalize the transaction. The guide below, starting at [step 2](#section--step-2-submit-a-transaction-request) can be used for reference.\n\nThe 3DS2 dunning flow, hosted or custom, can be tested with the following test credit card: '4000008400001629'" } [/block] [block:callout] { "type": "info", "body": "This guide is focused on helping you to support 3DS2 integrations for scenarios where your customers are 'in session' and directly interacting with the the transaction flow online. If you are supporting / building a solution that is used by call center agents who complete transactions on behalf of customers over the phone, you can bypass 3DS2 / SCA as these types of transactions are exempt from PSD2. This is done by passing an exemption flag via the Recurly API. See the [reference documentation](https://dev.recurly.com/docs/create-an-accounts-billing-info-token) for more details\n\n**Please be aware that certain payment gateways require additional configuration in order for MOTO exemptions to work properly. See our [gateway specific documentation](https://docs.recurly.com/docs/gateway-specific-updates) for details.** ", "title": "PSD2 Exemptions for Mail Order Telephone Order (MOTO) Transactions" } [/block] [block:api-header] { "title": "Key Terms / Glossary" } [/block] Here are a few key terms that will be referenced throughout this guide. * **Access Control Server (ACS)** A service either hosted or related to the Issuing bank. Responsible for issuing challenge URLs, generating device fingerprints, and verifying that the cardholder is non-fraudulent. * **Merchant plug-in (MPI)** A module, designed to facilitate 3-D Secure verification and prevention of payment card fraud. Verifies the card number with the card issuing bank and checks if it is enrolled in the 3-D Secure program. Typically provided by your payment gateway and used to facilitate interactions between merchants and the issuing bank responsible for completing the SCA process. The Recurly SCA framework wraps MPI functionality provided by various payment gateways. * **Strong Customer Authentication (SCA)** Requirement mandated by the European Economic Area (EEA) that ensures electronic payments are performed with multi-factor authentication. For more details check out our [docs](https://docs.recurly.com/docs/revised-payment-services-directive-psd2#section-strong-customer-authentication-sca) * **3-D Secure (3DS)** E-commerce authentication protocol that implements SCA. There are currently two versions of the protocol in effect, with 3DS 2.0 being the newest, and 3DS 1.0 used as a fallback until it is completely retired at a later date. * **Payment Services Directive 2 (PSD2)** EEA directive that is enforced as of September 14, 2019 requiring SCA to be in place. For more details check out our [docs](https://docs.recurly.com/docs/revised-payment-services-directive-psd2#section-strong-customer-authentication-sca) [block:api-header] { "title": "Understanding the SCA Flows" } [/block] SCA can be subdivided into a few different flows, each of which requires various degrees of engagement from your customers and/or a few extra steps from you in the implementation process. The Recurly SCA framework and this integration guide provide you with everything you need to account for each, but it is helpful to understand them and when they come into play. #### Frictionless Just as the name implies, this requires the least amount of effort from you and your customers. In fact, it is completely seamless and is the most ideal case if it can facilitated. In this flow, the card Issuer determines that it has enough information to authenticate the transaction without any further verification steps. As part of the initial authentication attempt, Recurly will pass on any available customer details to your payment gateway via the provided MPI, which will work with the Issuers’ ACS to determine if a frictionless flow can be used for the transaction. #### Fingerprint In some cases, the Issuer may require a device fingerprint as additional verification data before it will authenticate the transaction. While this will not require any interaction from your customers, there are a few extra steps, detailed in the step-by-step guide below, that are required on your part to ensure this happens. #### Challenge This flow requires direct interaction between your customer and the Issuers’ ACS before authentication can be confirmed. If a challenge is requested, your customer will be prompted for extra information to further prove their identity. [block:api-header] { "title": "The Recurly SCA Solution" } [/block] The Recurly solution to SCA is comprehensive and designed to simplify the process for you as much as possible. Because most payment gateways have taken a slightly different approach to implementing their MPIs, integrations can be substantially different and could require heavy development effort on your part. As such, we have designed our SCA solution with the following as key design goals: #### Simplify Complexity Our solution minimizes the complexity and effort required for you to integrate by building high-level abstractions around the low-level functionality provided by many of the payment gateway MPIs. #### Payment Gateway MPI Agnostic The Recurly solution provides a one-to-many integration that normalizes payment gateway specific implementations, giving you the flexibility to use the solution that you need today, without being locked into it should your business needs evolve. This allows you to build your SCA flow once without the need to start from scratch if you decide to migrate to a different payment gateway. [block:api-header] { "title": "Required Components and Prerequisites" } [/block] ### Recurly.js The existing Recurly.js JavaScript library has been enhanced to provide you with the functionality needed to implement the client side requirements of 3DS2 / SCA, such as device fingerprinting and rendering the challenge flows. This functionality is provided as a wrapper interface around the many client side libraries maintained by the various payment gateways. **Recurly.js version 4 is required for 3DS2 / SCA** . [block:callout] { "type": "info", "body": "See the [Recurly.js 3D Secure documentation](https://dev.recurly.com/docs/recurly-js-3d-secure) for a complete reference" } [/block] If you are not already using Recurly.js for other purposes, you can read more about it [here](https://dev.recurly.com/docs/recurlyjs), and / or follow [this guide](https://dev.recurly.com/docs/recurly-js-getting-started) to get up and running. ### Recurly API / Client Libraries **You will need to use version 2.21 (or higher)** of the Recurly API or one of its associated client libraries for 3DS2 / SCA. If you are using our API or client libraries for the first time, you can get started [here](https://dev.recurly.com/docs/getting-started). If you are upgrading from an earlier version of the API or a client library you can use these [upgrade guides](https://dev.recurly.com/page/recurly-v2-api-support-policy-and-roadmap#client-library-upgrade-guides) to help identify any breaking changes that will need to be addressed. [block:api-header] { "title": "Key Objects & Parameters" } [/block] The following list provides a quick reference for several key objects and parameters that will be used in conjunction with Recurly.js and the Recurly API in order to implement SCA. * **Credit Card Token** Secure token generated by Recurly.js to encapsulate sensitive billing information such as customer credit card numbers. Also includes additional customer / browser data collected by Recurly.js and used for SCA purposes. * **3-D Secure Action Token** Token generated by Recurly API to encapsulate data needed for Recurly.js to initiate the client-side authentication challenge and / or device fingerprinting. * **3-D Secure Action Result Token** Token generated by Recurly.js to encapsulate data captured as a result of the client-side authentication challenge and / or device fingerprinting. * **Recurly.js ThreeDSecure Class** Recurly.js class that is instantiated to provide SCA-specific client-side functionality such as handling challenge flows. [block:api-header] { "title": "Integration Guide" } [/block] ### **Step 1:** Collect payment data with Recurly.js In most cases, credit card tokenization with Recurly.js is optional from a 3DS2 / SCA perspective *(see the callout below for cases where it is required)*. However, you may want to consider using it as we have enhanced Recurly.js to collect additional customer data ( ie. browser info) as part of the credit card tokenization process. When possible, this data is passed on to the Issuers’ ACS via the payment gateway MPI in the initial authentication request, and could increase the chances that the transaction is approved in a frictionless manner. [block:callout] { "type": "danger", "body": "If you are using the **Wirecard, Sagepay, or Worldpay gateways**, **credit card tokenization with Recurly.js is required for all 3DS2 flows**. These gateways require device data to be sent with the initial transaction." } [/block] If you are already using Recurly.js to tokenize customer credit cards then there is no additional action required, as the enhancement described above will work automatically once you’ve upgraded to Recurly.js version 4 If you’re interested in taking advantage of this feature, see [this section of our documentation](https://dev.recurly.com/docs/recurly-js-getting-a-token) to get up and running with Recurly.js credit card tokenization. Again, this step is optional, but could lead to an increased number of transactions that are approved via the frictionless flow, which is beneficial from a customer experience and conversion perspective. [block:html] { "html": "<br />" } [/block] ### **Step 2:** Submit a transaction request If you have decided to tokenize the credit card as described in Step 1, you are now able be able to send it along to the appropriate Recurly API endpoint to initiate the payment transaction. Otherwise, the raw customer billing info can be passed instead. Transactions can be requested using the [Create Purchase](https://dev.recurly.com/docs/create-purchase), [Create Subscription](https://dev.recurly.com/docs/create-subscription), or [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice) endpoints Similar to the previous step, this guide assumes that you are already using Recurly API or the client libraries to process payment transactions with Recurly. As such, there should be no additional work required for this step in the SCA flow aside from ensuring that you have **upgraded to (at least) version 2.21 of the Recurly API**. For more information on completing the standard payment integration, please see our [documentation](https://dev.recurly.com/docs). See the 'Under the Hood' section below if you'd like to know more about the enhancements Recurly has made to facilitate this step in the SCA flow, otherwise continue on to Step 3. [block:callout] { "type": "info", "title": "Under the Hood", "body": "Once your request is received by the Recurly platform, billing info details, including the browser-level details required for SCA, will be extracted from the [Credit Card Token](#key-objects--parameters) and passed through to your payment gateway. If you are not tokenizing your credit cards with Recurly, we will use the raw credit card / billing info passed in the request to initiate the SCA process via the payment gateway." } [/block] [block:html] { "html": "<br />" } [/block] ### **Step 3:** Process the response If the transaction request is successful, Recurly API will return a success response code to your server and no additional action is needed from an authentication perspective. However, if the payment gateway requires additional action as part of the SCA flow, Recurly will indicate this with a new error code, called `three_d_secure_action_required`, in the API response. If this error code is returned, it will be accompanied with a `three_d_secure_action_token_id`, which references the [3-D Secure Action Token](#key-objects--parameters) that encapsulates data required for the next steps in the authentication flow. See below for the example response XML. [block:code] { "codes": [ { "code": "<errors>\n <transaction_error>\n <error_code>three_d_secure_action_required</error_code>\n <three_d_secure_action_token_id>ABCDEFGHIJKL012345</three_d_secure_action_token_id>\n ...\n </transaction_error>\n <transaction href=\"...\" type=\"credit_card\">\n ...\n </transaction>\n</errors>\n", "language": "xml" } ] } [/block] For your part, you will need to pass the `three_d_secure_action_token_id` from your server to the client and instantiate a new instance of the Recurly.js ThreeDSecure class, passing in the `three_d_secure_action_token_id` as a parameter. See below for an example. [block:code] { "codes": [ { "code": "const risk = recurly.Risk();\nconst threeDSecure = risk.ThreeDSecure({ actionTokenId: 'ABCDEFGHIJKL012345' });", "language": "javascript" } ] } [/block] [block:html] { "html": "<br />" } [/block] If you'd like to know more details about what's going on under the hood, take a look below, otherwise proceed to Step 4. [block:callout] { "type": "info", "title": "Under The Hood", "body": "When you instantiate the Recurly.js ThreeDSecure class with the `three_d_secure_action_token_id`, Recurly.js unpacks the associated [3-D Secure Action Token](#key-objects--parameters) in order to extract several details required to execute the next steps in the SCA flow on your behalf. For instance, one data point instructs Recurly.js as to which type of challenge to present to the customer (i.e. fingerprint, etc.), while another data point tells it which payment gateway MPI to leverage in order to complete the challenge." } [/block] [block:html] { "html": "<br />" } [/block] ### **Step 4:** Setup event handlers and initiate Fingerprint / Challenge Next, you'll need to setup event handlers on the instance of the [Recurly.js ThreeDSecure class](#key-objects--parameters) that you created in the previous step. These event handlers will process the success and error responses related to the Fingerprint / Challenge results returned from the Issuers’ ACS. [block:code] { "codes": [ { "code": "threeDSecure.on('error', err => {\n // display an error message to your user requesting they retry\n // or use a different payment method\n});\n\nthreeDSecure.on('token', token => {\n // send `token.id` to your server to retry your API request\n});", "language": "javascript" } ] } [/block] If the Fingerprint or Challenge is successful and the 'token' handler is triggered, Recurly.js will pass in a `three_d_secure_action_result_token_id`, which references the [3-D Secure Action Result Token](#key-objects--parameters) which in turn encapsulates data returned from the Issuers’ ACS. With this handler you should pass the token id back to your server and then retry the original purchase request via the Recurly API. Step 6 of this guide will provide further details on this. [block:html] { "html": "<br />" } [/block] ### **Step 5:** Initiate the Fingerprint / Challenge Once your event handlers are setup, you'll need to initiate the Fingerprint / Challenge flow by attaching a reference to an HTML element to your instance of the [Recurly.js ThreeDSecure class](#key-objects--parameters). This HTML element is a container for Recurly.js to render UI elements related to the challenge. [block:code] { "codes": [ { "code": "threeDSecure.attach(document.querySelector('#my-container'));", "language": "javascript" } ] } [/block] [block:callout] { "type": "warning", "body": "The UI elements that Recurly.js injects will size to the dimensions of your container. Since the flow itself must be contained within an iframe controlled by your customer's bank, we are unable to dynamically size the flow. Thus, we recommend that your container have specific dimensions set at a minimum of 250px (W) x 400px (H), and contain an interstitial message to explain that 3-D Secure authentication will be required to complete the transaction.\n\n**Certain payment gateways (e.g. Stripe) will render the challenge frame as a modal interface, therefore it is advised that you do not place your container in a modal of your own.** " } [/block] Recurly.js will then initiate the Fingerprint / Challenge using the appropriate payment gateway provided JavaScript library. Once completed, the event handlers that you setup in the previous step will be called depending on if there's a success or failure. Of course, there's a lot more going on behind the scenes. See below if you'd like to know more, or move on to step 6. [block:callout] { "type": "info", "title": "Under the Hood", "body": "Because every payment gateway provides a different JavaScript library to complete the Fingerprint / Challenge step in the SCA flow, Recurly.js implements several different wrapper components and then leverages the correct one based on information encapsulated in the [3-D Secure Action Token](#key-objects--parameters). However, it does this without requiring your code to know the difference or couple itself to any specific integration." } [/block] [block:html] { "html": "<br />" } [/block] ### **Step 6:** Submit new purchase request As part of the success event handler that you setup in step 4, initiate a new request to Recurly API from your server using the provided `three_d_secure_action_result_token_id`. Recurly will use this token id to unpack data from the [3-D Secure Action Result Token](#key-objects--parameters) and pass it on to your payment gateway when it attempts to authenticate the transaction once again. [block:callout] { "type": "warning", "body": "The `three_d_secure_action_result_token_id` is a valid parameter on the [Create Billing Info](https://dev.recurly.com/docs/create-an-accounts-billing-info-token) endpoint and on any Recurly API endpoint that accepts a Billing Info, including [Create Purchase](https://dev.recurly.com/docs/create-purchase), [Create Subscription](https://dev.recurly.com/docs/create-subscription), [Update Subscription](https://dev.recurly.com/docs/update-subscription), [Create Account](https://dev.recurly.com/docs/create-an-account), [Collect Invoice](https://dev.recurly.com/docs/collect-an-invoice), [Create Gift Card](https://dev.recurly.com/docs/create-gift-card)\n\n\nWhen you submit the new request it is essential that the Account / billing info / credit card token match that of the previous request as the authentication data encapsulated in the [3-D Secure Action Result Token](#key-objects--parameters) is tightly coupled to the payment information and customer account. Changing the Account / billing info / credit card token between requests will result in a token mismatch error. \n\nIt is also invalid to mix and match 3DS Action Result Token Ids between different API endpoints. For example, A 3DS Action Result Token Id obtained as part of the authentication process with the Create Account / Billing Info endpoint, can not be passed into the Create Subscription endpoint. A new token must be generated in this case if the endpoint requires 3DS2 authentication." } [/block] If the request is successful, then no further action is required. If the request results in an error, you should handle this per your current standard integration (ie. collect alternate payment from the customer and retry the transaction) [block:callout] { "type": "warning", "body": "**Note:** It is possible to get 3DS2 / SCA challenge requests on an Account / Billing Info that has been previously authenticated when you make subsequent API calls at a later date/time. For example, an API call to update a subscription could result in a new authentication challenge even if the initial action to create the subscription passed authentication." } [/block] [block:callout] { "type": "info", "title": "Under the Hood", "body": "When your server submits the new purchase request to Recurly API along with the `three_d_secure_action_result_token_id`, Recurly unpacks the authentication data returned from the Issuers’ ACS and then reattempts the authentication with your payment gateway based on their specific schema and API. The response data is then normalized and returned to your server per the Recurly spec." } [/block] [block:html] { "html": "<br />" } [/block] ### **Step 7:** Testing Test that your integration can handle all SCA flows properly by using the Recurly Test Gateway and one of the following four test credit cards depending on the flow that you'd like to verify. Your Recurly site must be in 'Sandbox' mode in order to use the Test Gateway. 4000000000003220 - challenge flow 4000000000003063 - (device) fingerprint flow 4222222222222220 - approved fraud review ( frictionless flow) The following test credit card can be used to test recurring transaction challenges (dunning flow) as well as the 'Update Subscription' endpoint. It will simulate a 3DS2 challenge any time a transaction is attempted: 4000008400001629 [block:callout] { "type": "success", "body": "When you are ready to test the integration with your payment gateway, [contact](http://support.recurly.com) the Recurly support team for assistance in configuring your site in 'Development' mode. You'll need to contact your gateway in order to obtain their specific set of test credit cards for 3DS2. Please also see our guide on gateway specific configurations [here](https://docs.recurly.com/docs/gateway-specific-updates)" } [/block] [block:callout] { "type": "danger", "body": "**SagePay is not supported for testing in Development mode at this time due to requirements that cannot be implemented outside of Production mode.**\n\nFor the above gateways, testing will need to be performed in Sandbox mode, using the Recurly Test Gateway and test credit cards", "title": "The following payment gateways do not support 3DS2 testing in Development mode" } [/block] [block:callout] { "type": "warning", "title": "", "body": "Braintree supports 3DS2 testing in Development mode, but an amount of '2099.00' must be used to trigger the 3DS2 challenge frame. Also note that it is not possible to complete the authentication beyond the initial display of the challenge frame." } [/block] [block:api-header] { "title": "Additional Support" } [/block] If you need additional support with your SCA integration, do not hesitate to [contact](http://support.recurly.com) our support team