Authenticating with PAAY 3DS on Landers
Last updated
Last updated
Follow the steps in the article to enable the PAAY plugin.
Once you have added the PAAY plugin, you can find your paayApiKey to use with the PAAY JavaScript you put on your lander by clicking on the PAAY tile (Admin → Plugins → Authentication).
You can also hit the Edit icon and copy the paayApiKey from the edit form.
1) Go to your checkout page code and make sure that the card inputs are inside of a form with an id attribute.
<form id="kform">
2) Add the following data-threeds attributes to your card inputs:
card input name
data-threeds attribute
cardNumber
pan
cardMonth
month
cardYear
year
Code example:
<input name='cardNumber' type='TEXT' maxlength=16 isRequired data-threeds="pan"> <select name='cardMonth' style='width:30%' isRequired data-threeds="month"> <select name='cardYear' style='width:30%' isRequired data-threeds="year">
3) Add the hidden inputs x_transaction_id and paayAmount inside of the same form as the card inputs. Initialize the x_transaction_id input value to “1234” since a Javascript function will be added in a later step to randomly generate that value. Set the paayAmount input value to the total amount of the transaction if it is static or to an empty string if it is calculated upon selection or submission.
<input type="hidden" name="x_transaction_id" value="1234" data-threeds="id"/> <input type='hidden' name='paayAmount' id='paayAmount' value='' data-threeds="amount">
4) Add these scripts to your page before the closing body tag:
<script src="https://cdn.3dsintegrator.com/threeds.min.latest.js"></script> <script type="application/javascript"> var id = document.querySelector('[data-threeds=id]'); var uniqueId = function() { return 'id-' + Math.random().toString(36).substr(2, 16); }; id.value = uniqueId(); </script> <script> var tds = new ThreeDS("kform", "paayApiKeyGoesHere", null, {autoSubmit:false, endpoint:"https://sandbox-api.3dsintegrator.com", verbose:true}); </script> </body>
The first parameter of ThreeDS is the form id (The example from step 1 was <form id=”kform”>).
The second parameter of ThreeDS is your paayApiKey which can be found following the steps in the Finding Your PAAY API Key section above.
The fourth parameter of ThreeDS is the options object.
autoSubmit
true: Authentication will be automatically attempted as soon as the customer has filled in the required card inputs.
Default if autoSubmit not included in options object.
pros: May speed up the order processing time for the customer since authentication is started before submission and less code to integrate.
cons: Less control over when authentication happens, authentication may not be completed before submission / Import Order is called.
false: You will need to add code that calls the ThreeDS verify function.
pros: More control over how authentication is called (for example: you won’t want try to authenticate every card since it only works with Mastercard and Visa and can code to not authenticate in those circumstances), you can code to make sure authentication is completed and 3DS values sent in Import Order
cons: May add time to order processing as perceived by customer
We suggest setting autoSubmit to false and will provide instructions on calling the verify function in the next steps.
endpoint
testing: "https://sandbox-api.3dsintegrator.com"
production: remove endpoint property from options object
verbose
true: You can inspect element in the browser and see verbose output in the console
rebill
decimal total amount of rebill cycle 2 transaction to also authenticate the cycle 2 rebill transaction
If authentication is successful, these rebill 3DS parameters will be automatically added to the form as the inputs rebill_cavv, rebill_xid, and rebill_eci, and the CRM will send them to the gateway with the cycle 2 rebill transaction at the time of rebilling.
5) Add the following code if implementing the autoSubmit = false option. Otherwise skip to step 6.
5a) Code to check the card number and only attempt authentication if Mastercard or Visa based on first character of cardNumber input value (3=Amex, 6=Discover):
const cardNumber = document.getElementsByName("cardNumber")[0] ? document.getElementsByName("cardNumber")[0].value : null; if(cardNumber) { const firstCCDigit = cardNumber.charAt(0); if(firstCCDigit !== "3" && firstCCDigit !== "6") { triggerPAAY(); //Run PAAY authentication } }
5b) Code to trigger the PAAY authentication:
function triggerPAAY() { const paayCallback = function(data) { <import Order> } const successCallbackFunction = paayCallback; //if you don't want to accept orders without successful 3DS authentication, //make this a separate function that returns decline message to customer const failureCallbackFunction = paayCallback; tds.verify(successCallbackFunction, failureCallbackFunction, {amount: initialAmount}); if(tds.errors.length > 0) { const paayError = tds.errors[0]; } }
6) If authentication is successful, the PAAY JavaScript will automatically add the 3DS values as the hidden inputs cavv, xid, and eci inside your form.
To also authenticate the cycle 2 rebill transaction and send the 3DS parameters to the gateway upon the first (cycle 2) rebilling, either set the rebill property of the options object while initializing ThreeDS or set tds.options.rebill before calling tds.verify.
This value is the decimal formatted total amount of the cycle 2 rebill transaction.
If authentication is successful, rebill 3DS parameters will be automatically added to the form as the inputs rebill_cavv, rebill_xid, and rebill_eci, and the CRM will send them to the gateway with the cycle 2 rebill transaction at the time of rebilling.
Initializing ThreeDS with rebill option example:
<script> var tds = new ThreeDS("kform", "paayApiKeyGoesHere", null, {autoSubmit:false, endpoint:"https://sandbox-api.3dsintegrator.com", verbose:true, rebill:89.95}); </script> </body>
Setting rebill property after initializing the ThreeDS object tds variable example:
tds.options.rebill = 89.95;
In order to authenticate the upsell transaction, you will need to save the cardNumber, cardMonth, and cardYear to session storage and then add hidden inputs with the data-threeds attributes pan, month, and year to your upsell page form. Then follow the same steps as for the checkout page and send the cavv, eci, xid, rebill_cavv, rebill_eci, rebill_xid on your Import Upsale call.
Replace this script:
<script src="https://cdn.3dsintegrator.com/threeds.min.latest.js"></script> //JavaScript library for 3DS 1.2
with the script for 3DS 2.0:
<script src="https://cdn.3dsintegrator.com/threeds.2.min.latest.js"></script> //JavaScript library for 3DS 2.0
PAAY will return additional parameters for 3DS 2.0 that you will need to send in the Import Order API and the Import Upsale API as the cavv, xid, and eci parameters.
3DS 2.0 parameter returned by PAAY
Parameter to send to Import Order / Import Upsale API
authenticationValue
cavv
dsTransId
xid
eci
eci
acsTransId
acsTransId
status
threeDsStatus
1) Add your PAAY API Key to the checkout page of your form-code lander inside the CRM and Update.
2) Download Code
3) The downloaded checkout page will include these lines of code. Copy or edit to your checkout page (adding data-threeds attributes to the cardNumber, cardMonth, and cardYear inputs, the new hidden inputs x_transaction_id and paayAmount, calling the echoPaayJS function before the closing of the body tag)
Inside the form:
<input name='cardNumber' type='TEXT' maxlength=16 isRequired data-threeds="pan"> <select name='cardMonth' style='width:30%' isRequired data-threeds="month"> <select name='cardYear' style='width:30%' isRequired data-threeds="year"> <input type="hidden" name="x_transaction_id" value="1234" data-threeds="id"/> <input type='hidden' name='paayAmount' id='paayAmount' value='' data-threeds="amount">
Amex with PAAY 3DS also requires the threeds attributes on the additional inputs:
<input name='shipAddress1' type='TEXT' isRequired data-threeds="shippingStreetAddress"> <input name='shipPostalCode' type='TEXT' isRequired data-threeds="shippingZipCode"> <input name="emailAddress" type="TEXT" isRequired data-threeds="emailAddress"> <input name="firstName" type="TEXT" isRequired data-threeds="billingFirstName"> <input name="lastName" type="TEXT" isRequired data-threeds="billingLastName">
Before the closing body tag:
<?php $ksdk->echoPaayJS(); ?> </body>
The echoPaayJS function optionally takes the boolean parameter $testing and the decimal parameter $rebill. Testing mode is false by default. Fetching rebill parameters (rebill_xid, rebill_cavv, rebill_eci) is null by default. In the examples below, 2.99 is the amount you plan to rebill. The amount you actually authorize/bill cannot be more than 110% of the amount authenticated, so if you are unsure of the rebill amount we recommend estimating a higher amount.
echoPaayJS() - Will use the production PAAY endpoint and NOT fetch rebill parameters.
echoPaayJS($testing=true) - Will use the testing endpoint with verbose messaging that can be seen through the console and NOT fetch rebill parameters.
echoPaayJS($testing=true,$rebill=2.99) - Will use the testing endpoint AND fetch rebill parameters.
echoPaayJS($testing=false,$rebill=2.99) - Will use the production endpoint AND fetch rebill parameters.
On klander.js, change lines 587 and 719 to: var noSaveFields = ['cardSecurityCode','achAccountNumber']; That way the cardNumber will be saved to the session and automatically filled in on upsell page.
Then add the hidden inputs to the upsell page: <input name='cardNumber' type='hidden' data-threeds="pan"> <input name='cardMonth' type="hidden" data-threeds="month"> <input name='cardYear' type="hidden" data-threeds="year"> <input type="hidden" name="x_transaction_id" value="1234" data-threeds="id"/> <input type='hidden' name='paayAmount' id='paayAmount' value='25' data-threeds="amount"> With the value of paayAmount being the upsell total.
And add the line before the closing body tag: <?php $ksdk->echoPaayJS(); ?>
You can run a test using cardNumber 4111111111111111, cardMonth 01, cardYear 21.
During testing you can see the verbose messaging in the console.
You can see the parameters after they have been created by the JavaScript by inspecting the form.
If you are testing with NMI, you may see the decline message "XID data must be 20 bytes" when you submit the order. That message means that your test 3DS parameters were successfully sent to NMI.
If the 3DS parameters are passed in properly on the Import call and the transaction goes to a mid that accepts 3rd Party 3DS you will see a tag that says *3DSecure underneath the result of the transaction.
Compatible Card Types
PAAY can currently be used to authenticate Visa and Mastercard transactions, so we recommend only attempting authentication with those card types.
Rebills
We recommend authenticating the cycle 2 transaction rebill amount in addition to authenticating your cycle 1 transaction.
Trial Authentications
For trials, we recommend following these practices:
Hold Trial Charge - Authenticate the cycle 2 transaction amount and send as the initial authentication amount. Do not attempt a PAAY rebill authentication.
Full Authorize & Void and Validate Card Trials or any trial with either no cycle 1 price or only shipping for cycle 1 - Run the PAAY authentication using the cycle 2 transaction amount and then send to Konnektive as rebill 3DS parameters.
FAQ
Q) How come I cannot see the returned 3ds values from PAAY’s API?
A) Please check the PAAY SDK and confirm that the 'addResultToForm' sdk option is set to True. This sdk option is embedded as a default config and set to true with the integration. Any changes made to this can lead to unexpected resulsts on your page.
7) After getting the 3DS parameters from PAAY through the JavaScript on your lander, you will send them as the cavv, xid, eci, rebill_cavv, rebill_xid, rebill_eci parameters in API calls to Konnektive.
More information can be found at:
This section provides the instructions for funnels utilizing Konnektive’s .
