Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

You may use TokenEx (<>) as a common payment gateway provider for your Optimizely <<product-name>> SDK offering for a variety of reasons including improved security, and simpler PCI compliance. To use this provider, implement an iframe to capture the credit card number and CVV. This implementation also has some credit card formatting as the card number is entered.


SDK/Self-Managed customers are responsible for their own PCI-DSS compliance and can choose to open their own TokenEx account.

In **\_MainLayout** we include the reference to the TokenEx JavaScript library (**Test:** `` , **Prod:** ``).

To support these updates, make the changes indicated below. The setting for TokenEx is under **Administration \> System \> Settings**, but this is controlled by the `appSettings.config` file.

## ReviewAndPay widget

If you do not have a customized **ReviewAndPay** widget, you can merge the changes from our updated Responsive theme **ReviewAndPay** widget. If you do have a customized version of this widget, you must update the **Credit Card Number** and **Security Code** inputs like the code below. The TokenEx JavaScript functions will replace the \<div> with id "tokenExCardNumber" with the card number iframe and the \<div> with id "pptokenExSecurityCode" with the security code iframe.

Code Sample: TokenEx IFrame



You must merge the changes from our updated Responsive theme **/scripts/cart/** in to your theme. If you made any changes to this controller by extending it in typescript with your own version of the controller (following the recommended way to extend our controllers), this should be all you need to do. If you actually changed it directly or replaced it without extending from our controller, you must manually merge the changes into your version. The functions to set up the TokenEx iframe are in this controller:

Code Sample: ``


First we call **this.settingsService.getTokenExConfig()**, which calls **/api/v1/tokenexconfig** to get the information to set up this TokenEx iframe instance. You must call this, as it sets up a unique authentication key using the timestamp and api key (that is not exposed), which must match and is used later with the transparent gateway calls. Next, the call then sets up the TokenEx iframes in the **getTokenExConfigCompleted** when it creates a new instance of the TokenEx.Iframe object.

The first parameter to the constructor is the id of the \<div> for the credit card iframe and the second is the configuration of that iframe. This is where you can control the styling of the iframe and note that the CVV iframe is set up in the configuration of the card number iframe and tied directly to that card number iframe.

Then **this.tokenExIframe.load()** is called, which loads the iframes into the page and event handlers are set up to listen to events issued from the iframes. The **validate** event is fired when the iframes are exited (on blur) and the **tokenize** event is fired when the submit button is clicked. We set the card number equal to the token we get back and the security code to just CVV, as the CVV token is already tied to the token for that card number and not needed or returned.

For more information on setting up the TokenEx iframe, see [Creating the iFrame](๐Ÿ”—๏ปฟ).

## TokenEx transparent gateway

When the iframe is used client side, the submit order sends the TokenEx token for the credit card number and CVV for the security code. What then happens server side is that we enclose these values with three curly braces like **{{{token}}}** and **{{{CVV}}}** and for whichever payment gateway is used, we replace the URL for that request to the TokenEx transparent gateway URL and then we set three headers on the request:

  • **TX_URL** โ€“ gets set to the actual payment gateway url that we replaced

  • **TX_TokenExID** โ€“ gets set to our TokenEx Id

  • **TX_APIKey** โ€“ gets set to our TokenEx API Key

The request goes through the TokenEx transparent gateway and the values in the request **{{{token}}}** and **{{{CVV}}}** get replaced with the actual card number and security code. Then the request is forwarded on to the actual payment gateway and we get the same response back from the payment gateway.

For information on the TokenEx transparent gateway see [Welcome to TokenEx](๐Ÿ”—๏ปฟ).

## Saved credit cards

When customers [save a credit card](๐Ÿ”—๏ปฟ), the system uses the same tokenization method of storing the token in the UserPaymentProfile table. When referencing a saved card, the system references information from the UserPaymentProfile table. When using a saved card, customers will need to enter a CVV number. A TokenEx iFrame is used for this, and calls the CVV-only mode configuration.