PaymentSITE

Overview

PaymentSITE is a hosted payment page that can be integrated into a merchant’s system to process payments. Upon accessing the PaymentSITE, either where it is embedded or via a standalone URL, the customer can enter their payment details and any other relevant information like their name, address, and phone number. PaymentSITE tokenizes all card data and keeps the merchant out of scope for PCI compliance.

The most popular form integration flow for developers is to build their own secure form with iFields for the user to enter their information, and then submit the transaction via our Transaction API. By doing so, the developer maintains full control over the UI and behavior of the integration. When using a PaymentSITE, the developer gives up much control and is limited to whatever is supported by PaymentSITE.

The advantage of PaymentSITE is that it is a quicker and easier implementation since the developer does not need to build the secure payment form and API calls directly. In addition, the user can utilize PaymentSITE’s built-in features and customizations without the developer needing to do additional work.

Getting started

Transaction types

The PaymentSite can be configured to process various different payment types: Sale , AuthOnly , and Save. For more details on what each of these commands is used for see Transaction API

Implementation

Initiation methods

Redirect

The PaymentSite is implemented so that when the user is ready to pay, they are redirected out of the merchants system, to the PaymentSite to enter their payment information.

iFrame

When the user is ready to pay, the PaymentSite is opened in an iFrame in the merchants system.

Pre-populate fields

Most fields that are on the PaymentSite (besides the sensitive payment details) can be pre-populated by the merchants system before the user is directed to the page. This can be done by specifying the “key” and “values” of those fields separated by the “&” symbol in the URL query string. The “key“ value needs to match exactly the html “name“ element of the field; you can find that by inspecting the page using the developer tools of a browser. You can also look at the Transaction API by transaction type to find most fields.

Example: https://secure.cardknox.com/cardknoxexternaldemodev?xamount=100&xinvoice=232144234

Note: The merchant can log into the Cardknox portal to control what fields are available on the page. If you try to pre populate a field that is not added to the page, the system will just ignore it.

Here is a list of specific settings fields that can be set in the query string in addition to the above.

Settings

Name	Description
xRedirectURL	This is the URL that the page will be redirected after the user submits the payment and the transaction is approved. If this is not specified, the user will stay on the PaymentSITE page and receive a message that the payment went through successfully.
xRedirectURL_NotApproved	This is the URL that the page will be redirected after the user submits the payment and the transaction is not approved. If this is not specified, the user will stay on the PaymentSITE page and receive a message that the payment did not go through, and they will be able to try again
xPostUrl	This is the URL the webhook will be sent to after the user submits the payment.

Accounts need a setting enabled by a Cardknox Support Team member to use the xPostUrl field.

Response methods

Redirect

Typically, after the transaction is completed by the user, the PaymentSite will automatically redirect the user back to the merchants system. There are two ways how to specify the redirect URL

1. Set the Redirect URL in the Cardknox PaymentSite backend settings

2. Set the xRedirectURL parameter in the query string when directing the user to the PaymentSITE.

The redirect will return the response parameter in the redirect quarry string. For a full list of response fields see Response parameters

Example: https://www.cardknox.com/?xCurrency=USD&xDate=6%2F29%2F2020%204%3A26%3A47%20PM&xResult=A&xStatus=Approved&xErrorCode=00000&xAuthCode=09379A&xAuthAmount=1.03&xRefNum=341260411&xToken=0p3q5479g1g3h2p34g5763008044gg0p&xBatch=5128197&xMID=xxxxxxxxxx9999&xTID=xxxxx6789&xAvsResult=Address%3A%20No%20Match%20&5_Digit_Zip%3A_No_Match&xAvsResultCode=NNN&xCvvResult=No%20CVV%20data%20available&xMaskedCardNumber=4xxxxxxxxxxx1111&xName=t%20test&xExp=0620&xCardType=Visa&xEntryMethod=Keyed&xCustom10=Payment%20Site

Webhook

The merchant's site can be notified of transaction responses via webhook notifications. This can be implemented in one of several ways:

1. Utilize account webhooks to receive webhooks for any transaction that is processed on an account
2. Set the webhook URL in the Cardknox PaymentSite backend settings

3. Set the xPostUrl the parameter in the query string when directing the user to the PaymentSITE.

To set an xPostUrl, please note that you need to contact Gateway Support to enable the setting for this method to function correctly.