Integration Guide

Overview

For integrating via BridgeComm see below, otherwise, please view the Transaction API.

Integrate via our BridgeComm web services API to our Payment Gateway to securely collect card information and execute transactions in a PCI compliant manner.

The base integration solutions for TokenPay.js include:

BridgeComm – a web services API for payment processing. The use of BridgeComm (without TokenPay.js) for payment capture places 100% of PCI Compliance responsibility on the Customer’s integration.
TokenPay.js – is an extension of BridgeComm that combines client-side and server-side technologies for PCI-compliant online payment capture.

TokenPay.js maximizes the user experience by allowing for the capture of sensitive card data within the payment form on the merchant’s website. The consumer remains on the merchant’s payment page at all times. The payment ‘token’ is only valid for use within 15 minutes of being generated or until used for the BridgeComm transaction.

TokenPay.js is an integration interface for the Payment Gateway that primarily facilitates online card payments in a manner that ensures that no sensitive card data ever needs to reach your servers so your integration can operate in a PCI compliant way.

To ensure that merchants are eligible for the simplest PCI validation method, Self-Assessment Questionnaire (SAQ A)*, TokenPay.js utilizes:

Isolation – Payment Gateway hosts the card sensitive data input fields. The fields are injected into your form as an HTML iframe thus isolating your page and your server from card sensitive data.
Tokenization – in order to execute transactions against the user’s card, TokenPay.js tokenizes the card sensitive data. The card token is generated via the use of the TokenPay.js JavaScript library and your payment form.
Segregation - Requests for charges against the user's card are made server-to-server not in the browser where it is publicly visible. The tokenized card data is submitted to your server where a secure server-to-server request is made to execute the transaction.
Public/Private Keys – The injection of the TokenPay.js hosted input fields and card tokenization is authenticated via a public key assigned to the merchant. API requests to execute charges against the tokenized card information are made by the backend server and are authenticated with a private key assigned to the merchant.

If you are processing more than six million transactions per year, you are not eligible to use a SAQ to prove PCI compliance. Payment brands require you to complete a Report on Compliance (RoC) to validate your PCI compliance annually.

Public and Private Keys

When a Payment Gateway Merchant on BridgeComm wants to utilize TokenPay.js for online transactions, a public/private key pair is assigned to the merchant for use with TokenPay.js. The public/private key is tied to a merchant account and merchant account code combination.

The public key is utilized by the TokenPay.js JavaScript library on your payment web page and is publicly visible, but this key only allows for the injection of the Payment Gateway hosted input fields. This key cannot be used to execute transactions against the user’s card.

The private key MUST be secured and never shared. The combination of the TokenPay.js generated card payment token and private key allows for charges to be made against the associated user’s card.

BridgeComm Request Examples

The BridgeComm solution provides a rich set of web service endpoints for a wide variety of payment services. The BridgeComm interface allows for the use of the Private Key and card payment token for capturing a card transaction, tokenization, or validation. The Card Token and Expiration Date are required to perform subsequent Sale transactions after consuming the AuthenticationTokenID. The Private Key and card payment token may only be used with the Authorization/Sale (Request 004), Multi-Use Card Token (Request 001), Multi-Use Bank Account Token (Request 013), and Account Verification and Balance Inquiry (Request 015).

Pass-Through Fields

In addition, the service request system supports the submission of extraneous, non-payment data elements that are submitted specifically as “pass through” information to be used for reporting and accounting purposes. These elements may include items like invoice number, operator ID, service code, or any other reporting data that an interfacing system might need.

Request/Response Structure

Requests are formatted and sent to the appropriate handler/processor, and the payment gateway sends a corresponding response in real-time. The payment gateway returns responses to the requesting system as a web service response message. The response includes the unique transaction identifier (reference number), request type (sale, auth, etc.), response code, and includes a tokenized representation of the credit card number and associated expiration date.

Overall Process

The general process cycle for a submitted service request is as follows:

Web Service request received by the payment gateway.
Superficial evaluation of request performed to determine general “proper format” and to retrieve and verify client access credentials.
Private key and tokenpay payment token is used to assign proper access rolls, contain credit card information and credential information.
Request message is evaluated based on request format details.
Request is processed.
Results of request are formatted based on the response message format details.
Response message is returned to the requesting system.

Private Key Usage - Card Token Request 001

The Card Token (Request 001) interface allows for the use of the Private Key and AuthenticationTokenID for returning a credit card token and expiration date.

Request Message format:
The following XML message is to be posted to the RequestHandler.postRequest method:

<?xml version= "1.0" encoding= "utf-8"?>
<requestHeader>
	<ClientIdentifier>SOAP</ClientIdentifier>
	<TransactionId>77777</TransactionId>
	<PrivateKey>yourPrivateKey</PrivateKey>
	<AuthenticationTokenId>TokenPay payment token</AuthenticationTokenId>
	<RequestType>001</RequestType>
	<requestMessage>
  </requestMessage>
</requestHeader>

Response message format returned outside of the XML response message (sample):

<GetToken>
	<TransactionId>77777</TransactionId>
	<RequestType>001</RequestType>
	<ResponseCode>00000</ResponseCode>
	<ResponseDescription>Successful Request</ResponseDescription>
	<responseMessage>
		<Token>1000000010261111</Token>
		<ExpirationDate>1222</ExpirationDate>
		<CardBIN>414720</CardBIN>
		<OrganizationId>2572</OrganizationId>
	</responseMessage>
</GetToken>

Private Key Usage - ACH Token Request 013

The Card Token (Request 013) interface allows for the use of the Private Key and AuthenticationTokenID for returning a bank account token and routing number.

Request Message format:
The following XML message is to be posted to the RequestHandler.postRequest method:

<?xml version= "1.0" encoding= "utf-8"?>
<requestHeader>
	<ClientIdentifier>SOAP</ClientIdentifier>
	<TransactionId>77777</TransactionId>
	<PrivateKey>yourPrivateKey</PrivateKey>
	<AuthenticationTokenId>TokenPay payment token</AuthenticationTokenId>
	<RequestType>013</RequestType>
	<requestMessage>
  </requestMessage>
</requestHeader>

Response message format returned outside of the XML response message (sample):

Private Key Usage - Authorization/Sale Request 004

Use the Authorization/Sale Request 004 to process a transaction using the AuthenticationTokenID.

Sample custom field format:

Request Message format:
The following XML message is to be posted to the RequestHandler.postRequest method:

Response message format returned outside of the XML response message (sample):

Private Key Usage - Authorization/Sale Request 004 with Service Fees

A service fee transaction can be added to a TokenPay transaction by inserting the service fee fields highlighted below. See the SOAP BridgeComm API for more details.

Request Message format:

The following XML message is to be posted to the RequestHandler.postRequest method:

Response message format returned outside of the XML response message (sample):

Account Verification and Balance Inquiry 015

Use the Account Inquiry request to obtain information from BridgeComm for a given credit card to return valid card, correct CVV and/or correct zip code. This function returns information just as the sale process except it does not charge the card.

NOTE: Balance Inquiry is only included for gift cards and EBT. For samples see SOAP BridgeComm API.

Request Message:

Response Message:

BridgeComm Find Transaction 023

There may be occasions when a transaction lookup is needed for research purposes or to confirm that a transaction completed. The Find Transaction (Request 023) method will allow you to retrieve the transaction details.

	Data Element	Data Type	Length	Description
O	MerchantCode	integer		Provided by the gateway at the time of boarding. The element is necessary unless the client is using a different merchant lookup solution. Used to narrow the search query down to a given merchant account code.
O	MerchantAccountCode	integer		Provided by the gateway at the time of boarding. The element is necessary unless the client is using a different merchant lookup solution. Used to narrow the search query down to a given merchant account code.
O	TransactionCode	string		Used to search on the user-provided transaction code of the transaction.
O	GatewayTransID	long integer		Identifies the Gateway ID number of the request.
O	InvoiceNum	string	24	Used to search on the user-provided Invoice Number of the original transaction.

The following XML message is to be posted to the RequestHandler.postRequest method:

Client Side

TokenPay.js is the JavaScript library for building payment flows within the Payment Gateway. With it you can collect card sensitive data from the user and create payment tokens for securely sending the data to your server in a PCI compliant manner.

TokenPay.js provides a ready-made UI component for collecting the card sensitive data from the user. TokenPay.js then tokenizes the information without ever having to touch your server.

The TokenPay.js UI component includes:

Automatically format card information as it is entered
Validation of card information as it is entered
Responsive design that works on user’s screen or mobile device
Customizable styling to match your look and feel

Payment Form Submission Best Practices

When implementing payment forms, it is recommended that the integrator utilize reCAPTCHA. reCAPTCHA protects payment forms from SPAM and bot abuse. Using reCAPTCHA on your payment forms reduces the risk of fraudulent transactions on the merchant's eCommerce sites by performing a Completely Automated Public Turing Test to Tell Computers and Humans Apart (CAPTCHA) test to tell humans and bots apart.

For more information on reducing form SPAM and bot abuse visit:
https://developers.google.com/recaptcha/intro

HTTP Requirements

All submission of payment information using TokenPay.js is made via a secure HTTPS connection. To protect yourself from man-in-the-middle attacks and to prevent your users from experiencing mixed content warnings in their browser, you MUST serve the page with your payment form over HTTPS.

The URL of the page containing TokenPay.js MUST begin with https://.

TEST URL:
https://www.bridgepaynetsecuretest.com/WebSecurity/TokenPay/js/tokenPay.js

PRODUCTION URL:
https://www.bridgepaynetsecuretx.com/WebSecurity/TokenPay/js/tokenPay.js

Step 1: Setting Up TokenPay.js

To get started, include this script on your page (sample code is using the Test URL):

Step 2: Create Your Payment Form

To securely collect card sensitive details from your users, TokenPay.js creates UI components for you that are hosted by BridgePay. They are then inserted into your payment form.

To determine where to insert the UI components, create empty DOM elements with unique IDs within your payment form.
If you want to modify and customize the style of the card entry area, create a hidden <div>
element to contain your styling. The id of this element MUST be 'customStyles'.

When the form is loaded, initialize the Pay element:

Replace the phrase your-public-key, shown below, with your publishable public key tied to your merchant account and merchant account codes. To display ACH instead of credit card fields set useACH to true - useACH: true. To disable zip code field (prevent zip code field from displaying) set disableZip to true - disableZip: true. To disable CVV field (prevent CVV field from displaying) set disableCVV to true - disableCVV: true.

The TokenPay element simplifies the form and minimizes the fields required by inserting a single input field that securely collects all needed card data.

If you have created the customStyles element to style the card entry area, change the value of 'useStyles' to true.

Step 3: Submit the Token

The card data collected by the TokenPay element returns a payment token to be used with the private key for the 004 sale transaction request to BridgeComm. If there are any errors in the collection of the card data or creation of the payment token, information is automatically displayed in the 'errorElement' of your payment form.

Server Side

Please refer to the BridgeComm Interface API Guide for instructions on interfacing to BridgeComm.

TEST URL:

https://www.bridgepaynetsecuretest.com/PaymentService/RequestHandler.svc

PRODUCTION URL:

https://www.bridgepaynetsecuretx.com/PaymentService/RequestHandler.svc

Once you have securely collected and tokenized your user’s card payment data using TokenPay.js, you will have a 15 minute window in which to complete the transaction request. The payment token expires after the fifteen minute window or when used.

To complete the transaction, you must perform a ‘RequestType 004 Sale or Auth’ or a 'RequestType 001 card token request' in a call to the BridgeComm API. Please see the example below.

The following XML message is to be posted to the RequestHandler.postRequest method:

To ensure uniqueness of the transaction and proper compliance with the TokenPay.js solution, please populate the following fields as described including the required fields listed in the BridgeComm API Interface Guide:

	Data Element	Data Type	Length	Description
R	TransactionId			The transaction ID generated by your backend for tracking purposes.
R	RequestDateTime	integer	19	Date and time of the transaction in yyyyMMddHHmmss format
R	PrivateKey			Your 'private key portion' of the tokenpay.js is generated card token.
R	AuthenticationTokenId			The 'token' delivered in the submission of your form.
R	Amount	integer	8	Transaction amount in pennies. Processed as implied decimal $1.25 would be represented as 125

Additional optional fields can also be passed with the transaction in the “Request Type 004” as described below. The fields listed below are the minimum recommended for Ecommerce transactions. A full listing is available in the BridgeComm API Interface Guide (001 or 004 Request).

	Data Element	Data Type	Length	Description
O	AccountStreet	string	128	Street address on the account. Can contain alphanumeric, spaces, hyphens, periods, and slashes.
O	AccountPhone	string	10-11	Billing phone number. Numeric only. No special characters allowed.
O	CardHolderName	string	200	Displays the cardholder name as provided in the request message.
O	InvoiceNum	string	24	Invoice number. Spaces are not allowed. Alphanumeric and dashes accepted. User supplied data.

The following XML message includes the optional fields listed above and is to be posted to the RequestHandler.postRequest method:

Base64 - Encoded SOAP Message Sample

The following message samples show the proper way to base64 encode a request message and the resulting base64-encoded response message for BridgeComm requests.

Sample Request Message:

Sample Response Message:

Testing and Integration Support

In the live environment, transactions must be initiated over an SSL-protected connection using a minimum of 128-bit encryption to protect sensitive data. Initial testing can be performed over an unencrypted connection; however, testing must be performed over an SSL-encrypted channel before a client can be certified to production. Only test card data may be transmitted -no live payment information should ever be transmitted to the test system.

A test or live merchant account including a public and private key with the gateway is necessary to successfully process transactions. To acquire a test account, complete the test account request form.

You may use the following cards in testing:

MasterCard	5439 7500 0150 0347
Visa	4005 5500 0000 0019
Discover	6011 0009 9301 0978
Diners	3699 9999 9999 99
AMEX	3742 5531 2721 002

1 Integration Guide
- 1.1 Overview
- 1.2 Public and Private Keys
- 1.3 BridgeComm Request Examples
- 1.4 Client Side
- 1.5 Payment Form Submission Best Practices
- 1.6 HTTP Requirements
  - 1.6.1 Step 1: Setting Up TokenPay.js
  - 1.6.2 Step 2: Create Your Payment Form
  - 1.6.3 Step 3: Submit the Token
- 1.7 Server Side
- 1.8 Base64 - Encoded SOAP Message Sample
- 1.9 Testing and Integration Support