Integration Guide

Overview

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.

Private Key Usage - Card Token Request 001

The BridgeComm solution provides a rich set of web service endpoints for a wide variety of payment services. The Card Token (Request 001) interface allows for the use of the Private Key and card payment token for returning a credit card token and expiration date. The Private Key and card payment token may only be used with the Authorization/Sale (Request 004) and card tokenization (Request 001) endpoints.

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>  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 - Authorization/Sale Request 004

The BridgeComm solution provides a rich set of web service endpoints for a wide variety of payment services. The Authorization/Sale (Request 004) interface allows for the use of the Private Key and card payment token for capturing a card transaction. The Card Token and Expiration Date are required to perform subsequent Sale transactions. The Private Key and card payment token may only be used with the Authorization/Sale (Request 004), Multi-Use Card Token (Request 001), 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.

Sample custom field format:
 

<CustomField1 passBack="True">1366</CustomField1>

Request Message format:
The following XML message is to be posted to the RequestHandler.postRequest method:
 <requestHeader>
  <ClientIdentifier>SOAP</ClientIdentifier>
  <TransactionId>635693706433821501</TransactionId>
  <RequestDateTime>20200417120822</RequestDateTime>
  <PrivateKey>yourPrivateKey</PrivateKey>
  <AuthenticationTokenId>TokenPay payment token</AuthenticationTokenId>
  <RequestType>004</RequestType>
    <requestMessage>
      <TransIndustryType>EC</TransIndustryType>
      <TransactionType>Sale</TransactionType>
      <Amount>4500</Amount>
      <HolderType>P</HolderType>
      <AcctType>R</AcctType>
        <SoftwareVendor>{company name software name software version}</SoftwareVendor>
      <CurrencyCode>USD</CurrencyCode>
    </requestMessage>
  </requestHeader> Response message format returned outside of the XML response message (sample):
 <Sale>
  <TransactionId>635693706433821501</TransactionId>
  <RequestType>004</RequestType>
  <ResponseCode>00000</ResponseCode>
  <ResponseDescription>Successful Request</ResponseDescription>
    <responseMessage>
      <Token>1000000074700016</Token>
      <ExpirationDate>1022</ExpirationDate>
      <OrganizationId>3538</OrganizationId>
      <AuthorizationCode>735333</AuthorizationCode>
      <AuthorizedAmount>4500</AuthorizedAmount>
      <GatewayTransID>236079704</GatewayTransID>
    </responseMessage>
</Sale> 

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. More details on Service fees. 

Request Message format: