{"_id":"5cc87f5b7fae12018477ff6f","project":"555fbba928249c1900618a82","initVersion":{"_id":"5c880f30807b06006266135b","version":"2.19"},"user":{"_id":"5c4b4e5b39a20b00dc863b8a","username":"","name":"Dominique Saulet"},"__v":0,"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: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 (optional):** Collect payment data with Recurly.js\n\nCredit card tokenization with Recurly.js is completely optional from a 3DS2 / SCA perspective. 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\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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\"\n}\n[/block]\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 purchase 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.\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 purchase 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 purchase 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 purchase response\n\nIf the purchase 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[/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 purchase request to the 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\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\": \"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 three test credit cards depending on the flow that you are trying to confirm:\n\n4000000000003220 - challenge flow\n4000000000003063 - (device) fingerprint flow\n4222222222222220 - approved fraud review ( frictionless flow)\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: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 (optional):** Collect payment data with Recurly.js Credit card tokenization with Recurly.js is completely optional from a 3DS2 / SCA perspective. 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": "warning", "body": "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" } [/block] 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 purchase 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. 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 purchase 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 purchase request to initiate the SCA process via the payment gateway." } [/block] [block:html] { "html": "<br />" } [/block] ### **Step 3:** Process the purchase response If the purchase 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" } [/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 purchase request to the 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. 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": "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 three test credit cards depending on the flow that you are trying to confirm: 4000000000003220 - challenge flow 4000000000003063 - (device) fingerprint flow 4222222222222220 - approved fraud review ( frictionless flow) [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