JetPay JetDirect Integration Guide

(1)

JetPay JetDirect

Integration Guide

(2)

1. JETDIRECT INTEGRATION. 4

2. THE PAYMENT FORM. 5

3 THE JETPAY RESPONSE. 10

4 CERTIFICATION TESTING. 13

4A STANDARD TRANSACTION PROCESSING TEST SUITE. 13

4B CVV2 TEST CASES. 13

4C ADDRESS VERIFICATION TEST CASES. 14

4D CHECKING ACCOUNT AND SAVINGS ACCOUNT TRANSACTIONS (ACH). 15

5 SPECIAL CONSIDERATIONS FOR THE DEVELOPER. 16

(3)

Introduction

JetPay JetDirect has been developed as a eCommerce specific method of communicating with JetPay’s processing front end by using the clients computer, instead of the merchant’s network. This method offsets the collection and transmission of card holder data from the merchant to the customer. By not sending the card data through the merchants’ network, merchants may be able to elevate a large portion of the PCI burden.

The JetDirect method is designed to send the card data directly to JetPay via an HTTPS POST directly from a card form on the merchant web site. This method uses the internet standard that a form when rendered in a browser is only exists as a form in the client browser. Further, any information entered in the form only exists on the computer where the input took place until such time as an action is preformed that moves that input to another page or service. In the case of JetDirect that information is moved from the client’s computer directly to JetPay.

What merchants qualify to use JetDirect?

JetDirect may be used by any eCommerce merchant where the merchant has control over the source code of their site or shopping cart system.

If you are using a Content Management System(CMS) such as WordPress, Drupal, Joomla etc you will need to make special considerations for virtual or sim links used by these packages. The $dataUrl, $retUrl, and $decUrl require absolute paths for the url’s failure to provide absolute paths could results in JetDirect receiving a 404 or a 405 error when sending back transaction data or redirecting the user to the approved or declined pages with in the merchant site.

Minimum Merchant Requirements

The following is the minimum requirements that each merchant using the HPP product must meet.

Item Description

SSL Certificate The merchant must possess a valid SSL Certificate issued by a registered certifying authority. The merchant may not use a self-signed certificate or a shared certificate. Receive Post

Data

If the merchant elects to receive transaction data to store in their own servers for reporting, or other use the merchant’s site must accept POST data and provide an HTTPS address where the transaction date will be sent.

SHA512 Hash Merchant web site language must support the generation of SHA512 hash for security and authentication routines.

Unique Order Number

Every transaction must contain a unique order number. This order number is used not only for record id in the GetReporting System* but is also used in the generation of the SHA512 Hash.

Key and Token Storage

A secured database or other secured method to store and read a specific set of Key and Token information used as part of the merchant credentials.

(4)

1. JetDirect Integration.

The integration information below assumes that the merchants’ development or engineering department has access to the full source code of the merchant web site or eCommerce shopping cart.

Integration is broken into three (3) parts: 1. SHA512 key generation

2. Payment collection – Credit Card or ACH 3. Payment process response.

1a. Generation of the SHA512 Hash

Using standard eCommerce check out process part one (1) of the integration will occur at the transition from where the customer reviews the order with the total amount to be paid and where the payment form is generated.

JetDirect uses a SHA512 Hash as part of the authentication routine. The merchant, depending on their web language and server set will need to implement the proper measures to generate this SHA512 Hash.

1b. Components of used in the SHA512 Hash

To generate the SAH5512 Hash the merchant will need to use the following variables: 1. Merchant TID – provided by Jetpay, LLC

2. Transaction Amount

3. JetDirect Token – Provided by JetPay when merchant goes live.

4. Unique Order Number for each transaction.

The above variables will need to be constructed in the following order and then the SHA512 method applied.

MerchantTID + Transaction Amount + Token + Order Number

Example: TESTTERMINAL15.001234567890ABCDEFGHIJKabcdefghijk20120103-A

The SHA512 Hash you generate should look something like this.

CB3E61A0BFCA4A75C571617A57356D5780309AB5C64DAE22FBB4CC8632A61E5CD1BACA EB8A584E6CEF811BD7293AD19E77AE2BA4765897CEB2B86AD141869915

(5)

2. The Payment Form.

Once the SHA512 Generation has been completed the merchant is ready to present the payment form page to the customer. The payment form page may be ether credit card or ACH for use with the JetDirect system.

The generation of the payment form is a standard HTML form with the form field names mapped to specific names used by the JetDirect system front end.

2a. Special Requirements for the Merchant Payment Form.

The merchant payment for may include:

 CSS

 Java Script, AJAX, jQuery etc.

Or any other scripts that can be included in the form as it loads.

Important information regarding server interaction with the payment page.

1) Once the payment form loads, the form can not interact with the merchants servers.

2) All validations must take place local to the page via javascript, ajax, json or other means available.

Any merchant site found to be using server side validation or having live interaction with the payment form page will have their merchant account suspended until corrective action has taken place OR the merchant completes the PCI SQA Level “B” or “C”.

2b. Best Practices for HTML Card From Construction.

While the construction of an HTML for is very common and basic in its coding, the developer should follow a best practices standard in its design and development. One item that should always be included in any form where sensitive data is entered is to prevent cashing the data in those fields. To prevent the client browser from saving this date the developer should turn off autocomplete for those fields

Example of turning off autocomplete for an entire form:

Example of turning off autocomplete for a single field:

(6)

2b. JetDirect Form Field Names and Descriptions.

Form Field

Field Name Required Visible/ Hidden

Description

Name name Y* V Card Holder or Account Holder Name

if used in a single form field. First

Name

fName Y* V First Name of Card or Account holder

if using split form fields for First and Last Name.

Last Name

lName Y* V Last Name of Card or Account holder

if using split form fields for First and Last Name.

Card Number

cardNum Y V Credit Card Number field.

Max length 16 Numeric Characters. Form autocomplete=”off”

Expiration Month

expMo Y V Credit Card expiration date Month.

May be a select or text field Min/Max Length 2 Numeric Characters.

Form autocomplete=”off”See Appendix for Month Formatting. Expiration

Year

expYr Y V Credit Card expiration date Month.

May be a select or text field Min/Max Length 2 Numeric Characters.

Form autocomplete=”off”

See Appendix for Year Formatting. Security

Code / CVV

cvv Y V The security code for the Credit Card

being used.

Min Length 3 Numeric Characters Max Length 4 Numeric Characters. Form autocomplete=”off”

Total Amount

amount Y V Total amount that is to be charged to

the Credit Card entered.

Must be in USD with two decimal points.

Example 100.00

Email customerEmail N V Email address of the customer

Billing Address 1

billingAddress1 N^ V/H First line of the billing address for the card being used.

Billing Address 2

billingAddress2 N^ V/H Second line of the billing address for

(7)

Billing City

billingCity N^ V/H City of the billing address for the card

being used. Billing

State

billingState N^ V/H State of the billing address for the

card being used.

Max Length 2 Alpha Characters. Example Texas = TX

Billing Zip Code

billingZip Y V Zip code of the billing address for the

card being used. Billing

Country

billingCountry N V/H Country of the billing address for the

card being used.

Min/Max Length 3 Alpha Characters, Example United States of America = USA

See Appendix for a list of Country and codes.

cid Y H A unique identifier for the customer.

jp_tid Y H Merchant Terminal ID as provided by

JetPay.

Max Length 12 Numeric or Alphanumeric Characters.

jp_key Y H Merchant Key provided by JetPay as

part of the Authentication Key Token set.

Min/Max Length 72 Alphanumeric Characters.

jp_request_hash Y H SHA512 Hash generated from the

Merchant TID, Total Amount, Token, Order Number.

order_number Y H Unique order number for the

transaction.

Max Length 12 Alpha or Alphanumeric.

trans_type Y H The type of transaction that is being

attempted. SALE

AUTHONLY** TOKEN**

ud1, ud2, ud3 N H Open user data fields

Max Length 21 Alpha or Alphanumeric characters.

Note: these values will be recorded in JetPay’s GetReporting System and can be used for payment tracking and reconciliation.

(8)

merData0 merData1 merData2 merData3 merData4 merData5 merData6 merData7 merData8 merData9

N H These are open free form fields for

use by the merchant and may contain up to 240 Characters. This

information is not stored or used by JetPay but provided as a pass through for added transaction details that can be picked up by the

merchant along with the transaction data for internal tracking of payment.

retUrl Y H The full url of where JetDirect will

redirect the customer in the event of an APPROVED Transaction

Example: https://www.merchant-domain.com/approved.html

decUrl The full url of where JetDirect will

redirect the customer in the event of a DECLINE transaction.

Example: https://merchant-domain.com/decline.html

dataUrl Y H The full url of where JetDirect will

POST the returned transaction details. This url must handle HTTPS POST request. JetDirect will send both APPROVED and DECLINE transaction information to this url. Example: https://www.merchant-domain.com/transactions.html

* The name fields may be ether a single form field to collect both first and last name OR it may be split into two (2) fields for First Name and Last Name. Do not use both options on your form.

** The Transaction Types of AUTHONLY and TOKEN may be used IF the merchant develops their own method of sending subsequent CAPT requests for AUTHONLY transaction OR if the merchant needs to only tokenize (TOKEN) the card number and expiration date for use in recurring billing OR to run a SALE transaction at a later date.

^ The Billing Address may be visible form fields for the customer to complete or they may be hidden fields if the billing address is already stored in the merchants’ database. Further, The Billing Address information is ONLY required IF the merchant has elected to use AVS Checking during the merchant enrolment. However, the Billing Zip Code is required at all times.

Set the the form method to “post” and the action of the form to the JetDirect testing URL -

https://testapp1.jetpay.com/jetdirect/post/cc/process_cc.php

(9)

If a TOKEN only request is sent please note that JetPay will TOKENIZE the card number and expiration date. A TOKEN only request does NOT validate that a card is live or “good” only that it passes the LUHN Check and that the date is valid.

IF you are using TOKEN only for the bulk of your transactions we strongly suggest that the merchant account also use the JetPay Account Updater option to help and ensure that that card numbers and expiration dates are correct at the time when a TOKEN is used for transactions.

Merchant Testing Variables

Variable Value

merchant_mid TESTTERMINAL

jp_key _{1234567890abcdefghijk}

jp_token 1234567890ABCDEFGHIJKabcdefghijk

cid The first 24 characters of the merchant name. Do not include spaces or special characters.

Once testing is complete this variable maybe be any 24 alphanumeric value used to tie the transaction to the customer making the payment. If the merchant will be using JetPay’s GetReporting system as the sole resource for transaction data it is strongly advised that the merchant also set this value in on of the User Data fields (UD1, UD2, UD3). The use of the User Data fields will ensure that the customer ID, customer number etc is presented in the transaction details in JetPay’s GetReporting system. Thus simplifying bookkeeping by connecting the transaction to the customer.

(10)

3 The JetPay Response

After the transaction has been completed JetPay will return to the merchant the transaction data in the form of an HTTPS POST, to a return URL provided by the merchant. This transaction data can include a number of different values based on the merchant’s configuration as well as the information provided by the merchant. The table below outlines each returned variable and a description of the information.

For approved Credit Card and ACH

Returned Variable Description CC/ACH Standard/

Optional

jp_return_hash A retuned sha512 has using the same construction set as the jp_request_hash. However for an approval the hash will be appended with “APPROVED”

Example of the build would be:

TID.AMOUNT.JP_TOKEN.ORDER_NUMBER.APPROVED

CC/ACH S

cid Customer ID as provided by Merchant CC/ACH S

cardNum Card number provided by the customer in the following format: ************####

CC S

card The type of card used be the customer for the transaction VS=Visa

MC=Master Card DS=Discover

AX=American Express

CC S

chargeTotal The total amount that was charged for this payment. This amount includes any fee incurred for online bill pay.

CC/ACH S

responseText

Text providing a verbose statement of the transaction. In this instance it would be:

APPROVED CC/ACH S

transId Transaction ID CC/ACH S

actCode The Action Code for the transaction

Note to obtain a full listing of Action Codes please contact JetPay Customer Service at [email protected] and request the Action Code List.

CC/ACH S

apprCode The six(6) character authorization code for the transaction CC S

cvvMatch CVV or Security Code Matching information^ CC S

addressMatch Address Verification Match Code^ CC S

zipMatch Zjp Code Verification Match Code^ CC S

avsMatch Address Verification Match Code^^ CC S

ccToken Token for Credit Card Number and Expiration Date CC S

(11)

merOrderNumber As provided by the merchant. CC/ACH O merUd1

merUd2 merUd3

As provided by the merchant CC/ACH O

merData0 - 9 As provided by the merchant CC/ACH O

For Declined CC and ACH

Optional

jp_return_hash A retuned sha512 has using the same construction set as the jp_request_hash. However for an approval the hash will be appended with “DECLINE”

TID.AMOUNT.JP_TOKEN.ORDER_NUMBER.DECLINE

CC/ACH S

responseText

DECLINE CC/ACH S

actCode

The Action Code for the transaction*

Note to obtain a full listing of Action Codes please contact JetPay Customer Service at [email protected] and request the Action Code List.

CC/ACH S

amount Amount attempted to be charged CC/ACH S

name Card Holder or Account Holders Name CC S

merOrderNumber As provided by the merchant. CC/ACH O

(12)

Special for Authentication Failures.

In the instance where the incoming SHA512 hash can not be validated the transaction will immediately be rejected. And a Response returned to the dataUrl value with the following values.

Optional

jp_return_hash A retuned sha512 has using the same construction set as the jp_request_hash. However for an approval the hash will be appended with “AUTHENTICATIONFAIL”

TID.AMOUNT.JP_TOKEN.ORDER_NUMBER.AUTHENTICA TEFALE

CC/ACH S

responseText

AUTHENTICATEFAIL CC/ACH S

name Card Holder or Account Holders Name CC S

amount Amount attempted to be charged CC/ACH S

merOrderNumber As provided by the merchant. CC/ACH O

Once the data is sent to the dataUrl of the merchant, the users browser will be redirected to the merchant designated decline url (decUrl).

(13)

4 Certification Testing

JetPay certification testing is intended to prepare a merchant for processing transactions through JetPay. This document contains test suites and test cases that enable a merchant to prepare and submit test JetPay transactions and verify compliance with JetPay submission rules.

Testing validation must be completed prior to the issuing of the merchant Key and Token sets. Please record the Transaction ID’s from your test cases and submit them to

[email protected]

4a Standard Transaction Processing Test Suite

The following test cases consist of common JetPay transactions that many merchants will need to be able to perform. To certify, the merchant needs to submit those test cases that apply to the merchant's anticipated requirements.

The following test cases will certify standard sales transactions. The credit card used for these test cases will follow the format, 4111 1111 1111 xxxx.

Test Case Type PAN Exp Date

Amount Expected Result

STND001 SALE 1111 12/13 $10.00 Approved

STND002 SALE 1129 01/11 $10.00 Expired Card

STND003 SALE 1128 12/13 $10.00 Invalid Card Number

STND004 Through STND051

SALE 1137 12/13 Amounts between

$1.00 and $2.00 ($1.01, $1.02, etc)

Assorted responses both approved and declined. These test cases are always required.

4b CVV2 Test Cases

The credit card companies support multiple methods for validating credit cards and verifying a cardholder's identity. JetPay supports CVV2, CVC2, and CID card validation, available from Visa, MasterCard, and American Express, as well as all the other major credit card brands. JetPay supports address verification ("AVS") as implemented by Visa, MasterCard, and American Express (as well as Amex's name verification feature). With these two common features, a credit card's integrity can be validated and a cardholder's billing address can be verified. Even more importantly, these two features reduce transaction charges and help to protect a merchant against charge backs.

The following test cases will certify CVV2 transactions. The credit card used for these test cases use the following format: 4666 6666 6666 xxxx.

Test Case Type PAN Exp Date

Amount CVV2 Expected Result CVV201 SALE Or AUTHONLY 6669 12/13 $10.00 321 Approved, CVV Matches CVV202 SALE Or

(14)

AUTHONLY CVV203 SALE

Or

AUTHONLY

6685 12/13 $10.00 543 Approved, CVV not processed

CVV204 AUTHONLY 6693 12/13 $0.00 021 Approved, CVV Matches

CVV205 SALE or AUTHONLY

6610 12/13 $10.05 123 Declined, CVV Not Processed CVV206 SALE or

AUTHONLY

6628 12/13 $12.51 089 Declined, CVV Matches

4c Address Verification Test Cases

The following test cases will certify address verification transactions using AVS. The credit card used for these test cases is 4777 7777 7777 xxxx.

Test AVS if AVS is activated on the Merchant Account. Test Case Type PAN Exp

Date Amount Address Postal Code Expected Result AVS01 SALE Or AUTHONLY 7711 01/11 $11.00 1234 Fifth Street 77708

Approved, both address & zip match AVS02 SALE Or AUTHONLY 7729 01/11 $11.00 _{1234 Fifth Street} 11100

Approved, address match, zip not match AVS03 SALE Or AUTHONLY 7737 01/11 $11.00 1234 Fifth Street 88809

Approved, zip match, address does not match

AVS04 SALE or AUTHONLY

7745 01/11 $11.00 _{1234 Fifth Street}

44403

Approved, address and zip do not match

7778 01/11 $11.00 1234 Fifth Street

33312

Approved, international non-AVS participant

7810 01/11 $12.51 1234 Fifth Street

00006

(15)

4d Checking Account and Savings Account

Transactions (ACH)

Merchants may submit bank drafts to JetPay. JetPay can enable properly configured merchants to send checks and savings account drafts directly into their bank account. By submitting the ABA routing code listed on every check along with the bank account number and the accountholder's name, JetPay will route these bank drafts directly into the merchant's bank account. Refunds of bank drafts are also available.

Bank accounts submitted through ACH require an ABA number, and account number, an accountholder's name, and an identifying check number. The following processes prescribe the test cases for ACH processing. For Approval Testing use routing code of 122000496, for Decline Testing use routing number of 654654654. For the cardholder name, use "John Q. Public" or the name of your favorite Star Wars character.

Test Case Type Account Number

Check Number

Amount Expected Result

ACH01 CHECK 123411 234 $10.00 Approved

ACH04 CHECK 3213211 12222 $10.00 Decline

ACH05 CHECK 1598887 55622 $10.00 Decline

Once your testing has been validated and certified you will receive you Key and Token set that is unique to your Terminal ID (TID). Please note that there is only one Key/Token set per TID. If you are running multiple sites you will need one(1) TID and one(1) Key/Token set for each site.

(16)

5 Special Considerations for the Developer.

While JetDirect has been created with ease of implementation in mind there are some factors that the developer must take into consideration.

1. Content Management Systems (CMS) such as WordPress, Joomla, Drupal etc may not allow the developer to run custom scripts within the framework. Considerations may need to be made to run JetDirect out side of the base CMS package.

2. The developer should take into account the need to disable the “Submit” button action on the first click OR through use of a modal set a progress .gif to alert the user that some action is taking place. Failure to do so or allowing the customer to click the “Submit” more than once can result in duplicate or multiple transactions being submitted. Further, a 30 second time out for your card page is recommended if the client does not receive a redirect in that time; the developer should auto redirect to an error page alerting the user that there is an issue and to contact the merchants customer service. JetPay does not provide error pages or notifications to the user in the instance of a time out or communication issues back to the merchant site.

3. As stated previously in this document, the card page must not have any downwards

interaction with the merchant’s server or network in order to be PCI SQA Level A compliant. Any form validation for required fields or completeness must take place on the client’s machine via JavaScript, AJAX, jQuery, etc. Checks may need to be implemented to check for JavaScripting being turned off in browsers and ether a notice prior to the card form.

4. Cross browser compliance must also be taken into consideration. Developers should test on Internet Explore, Fire Fox, Safari, and Opera at a minimum.

5. In regard to the retUrl, decUrl and dataUrl please provide the full path where browser redirects are to take place as well as where the transaction data is to be sent. The use of dynamic urls, sim-links etc may result in loss of data in the return information from JetPay.

(17)

6 Error Codes and Other Resources.

Developers will find a full list of transaction error codes, test credit card and ACH account numbers, AVS codes located here -

http://www.jetpay.com/developer/dev-codes.php

Sample Code in PHP may be downloaded here -

http://www.jetpay.com/developer/dev-jetpay-api-web-dev.php

For integration assistance please contact via email [email protected]

All information contained in this document is accurate and correct at the time of publication. Please check the JetPay.com web site to validate that you have the most current and up to date version. Changes to this document may be made with notice.