Authenticating with PAAY 3DS on Landers

• Enabling the PAAY Plugin

• Finding Your PAAY API Key

• Direct API

  • Rebills

  • Authenticating Upsells

  • 3DS 2.1

• Form-code

  • Form-code upsells

• Testing

• Suggested PAAY Practices

PAAY Integration requires a valid Merchant Number (provided by processor) inside Merchant Account in Konnektive. See here if you aren’t sure where the Merchant Number is added.

---

Enabling the PAAY Plugin

Follow the steps in the PAAY Plugin article to enable the PAAY plugin.

Finding Your PAAY API Key

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.

Direct API

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:

JavaScript

<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>

Python

message = "hello world"
print(message)

Ruby

message = "hello world"
puts message

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.

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 Import Order API calls to Konnektive.

More information can be found at: https://docs.3dsintegrator.com/docs/javascript-sdk

Rebills

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;

Authenticating Upsells

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.

3DS 2.1

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.1:

<script src="https://cdn.3dsintegrator.com/threeds.2.min.latest.js"></script> //JavaScript library for 3DS 2.1

PAAY will return additional parameters for 3DS 2.1 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.1 parameter returned by PAAY	Parameter to send to Import Order / Import Upsale API
authenticationValue	cavv
dsTransId	xid
eci	eci
acsTransId	acsTransId
status	threeDsStatus

---

Form-code

This section provides the instructions for funnels utilizing Konnektive’s form-code.

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.

Form-code upsells

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(); ?>

---

Testing

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.

---

Suggested PAAY Practices

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 results on your page.