JetPay JetDirect Integration Guide

Transcription

1 JetPay JetDirect Integration Guide

2 1. JETDIRECT INTEGRATION THE PAYMENT FORM. 5 3 THE JETPAY REPONE CERTIFICATION TETING. 13 4A TANDARD TRANACTION PROCEING TET UITE. 13 4B CVV2 TET CAE. 13 4C ADDRE VERIFICATION TET CAE. 14 4D CHECKING ACCOUNT AND AVING ACCOUNT TRANACTION (ACH) PECIAL CONIDERATION FOR THE DEVELOPER ERROR CODE AND OTHER REOURCE. 17

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 HTTP POT 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 ystem(cm) 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 L Certificate Receive Post Data HA512 Hash Unique Order Number Key and Token torage Description The merchant must possess a valid L Certificate issued by a registered certifying authority. The merchant may not use a self-signed certificate or a shared certificate. 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 POT data and provide an HTTP address where the transaction date will be sent. Merchant web site language must support the generation of HA512 hash for security and authentication routines. Every transaction must contain a unique order number. This order number is used not only for record id in the GetReporting ystem* but is also used in the generation of the HA512 Hash. 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. HA512 key generation 2. Payment collection Credit Card or ACH 3. Payment process response. 1a. Generation of the HA512 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 HA512 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 HA512 Hash. 1b. Components of used in the HA512 Hash To generate the AH5512 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 HA512 method applied. MerchantTID + Transaction Amount + Token + Order Number Example: TETTERMINAL ABCDEFGHIJKabcdefghijk A The HA512 Hash you generate should look something like this. CB3E61A0BFCA4A75C571617A57356D AB5C64DAE22FBB4CC8632A61E5CD1BACA EB8A584E6CEF811BD7293AD19E77AE2BA CEB2B86AD Once this value is generated it will be used in a hidden form field on the payment form page.

5 2. The Payment Form. Once the HA512 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. pecial Requirements for the Merchant Payment Form. The merchant payment for may include: C Java cript, 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 QA 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: <form method="pot" action="..." autocomplete="off"> Example of turning off autocomplete for a single field: <intput type= text name= cardnum id= cardnum value= autocomplete="off">

6 2b. JetDirect Form Field Names and Descriptions. Form Field Name Required Visible/ Description Field Hidden Name name Y* V Card Holder or Account Holder Name if used in a single form field. First Name Last Name Card Number Expiration Month Expiration Year ecurity Code / CVV Total Amount fname Y* V First Name of Card or Account holder if using split form fields for First and Last Name. lname Y* V Last Name of Card or Account holder if using split form fields for First and Last Name. cardnum Y V Credit Card Number field. Max length 16 Numeric Characters. Form autocomplete= off expmo Y V Credit Card expiration date Month. May be a select or text field Min/Max Length 2 Numeric Characters. Form autocomplete= off ee Appendix for Month Formatting. expyr Y V Credit Card expiration date Month. May be a select or text field Min/Max Length 2 Numeric Characters. Form autocomplete= off ee Appendix for Year Formatting. 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 amount Y V Total amount that is to be charged to the Credit Card entered. Must be in UD with two decimal points. Example customer N V address of the customer Billing Address 1 Billing Address 2 billingaddress1 N^ V/H First line of the billing address for the card being used. billingaddress2 N^ V/H econd line of the billing address for the card being used.

7 Billing City Billing tate Billing Zip Code Billing Country billingcity N^ V/H City of the billing address for the card being used. billingtate N^ V/H tate of the billing address for the card being used. Max Length 2 Alpha Characters. Example Texas = TX billingzip Y V Zip code of the billing address for the card being used. billingcountry N V/H Country of the billing address for the card being used. Min/Max Length 3 Alpha Characters, Example United tates of America = UA ee 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 HA512 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. ALE ** 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 ystem 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: decurl The full url of where JetDirect will redirect the customer in the event of a DECLINE transaction. Example: dataurl Y H The full url of where JetDirect will POT the returned transaction details. This url must handle HTTP POT request. JetDirect will send both APPROVED and DECLINE transaction information to this url. Example: * 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 and TOKEN may be used IF the merchant develops their own method of sending subsequent CAPT requests for 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 ALE 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 AV Checking during the merchant enrolment. However, the Billing Zip Code is required at all times. et the the form method to post and the action of the form to the JetDirect testing URL - Production URL will be provided once the merchant has completed the integration and testing.

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 merchant_mid jp_key Value TETTERMINAL abcdefghijk jp_token ABCDEFGHIJKabcdefghijk 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 HTTP POT, 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 tandard/ 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 cid Customer ID as provided by Merchant cardnum Card number provided by the customer in the following format: ************#### CC card The type of card used be the customer for the transaction V=Visa MC=Master Card D=Discover AX=American Express CC chargetotal The total amount that was charged for this payment. This amount includes any fee incurred for online bill pay. responsetext Text providing a verbose statement of the transaction. In this instance it would be: APPROVED transid Transaction ID actcode The Action Code for the transaction Note to obtain a full listing of Action Codes please contact JetPay Customer ervice at [email protected] and request the Action Code List. apprcode The six(6) character authorization code for the transaction CC cvvmatch CVV or ecurity Code Matching information^ CC addressmatch Address Verification Match Code^ CC zipmatch Zjp Code Verification Match Code^ CC avsmatch Address Verification Match Code^^ CC cctoken Token for Credit Card Number and Expiration Date CC name Card Holder or Account Holders Name CC

11 merordernumber As provided by the merchant. O merud1 merud2 merud3 As provided by the merchant O merdata0-9 As provided by the merchant O For Declined CC and ACH Returned Variable Description tandard/ 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 Example of the build would be: TID.AMOUNT.JP_TOKEN.ORDER_NUMBER.DECLINE cid Customer ID as provided by Merchant transid Transaction ID responsetext Text providing a verbose statement of the transaction. In this instance it would be: DECLINE The Action Code for the transaction* actcode Note to obtain a full listing of Action Codes please contact JetPay Customer ervice at [email protected] and request the Action Code List. amount Amount attempted to be charged name Card Holder or Account Holders Name CC merordernumber As provided by the merchant. O

12 pecial for Authentication Failures. In the instance where the incoming HA512 hash can not be validated the transaction will immediately be rejected. And a Response returned to the dataurl value with the following values. Returned Variable Description tandard/ 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 Example of the build would be: TID.AMOUNT.JP_TOKEN.ORDER_NUMBER.AUTHENTICA TEFALE cid Customer ID as provided by Merchant transid Transaction ID responsetext Text providing a verbose statement of the transaction. In this instance it would be: AUTHENTICATEFAIL name Card Holder or Account Holders Name CC amount Amount attempted to be charged merordernumber As provided by the merchant. 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 tandard Transaction Processing Test uite 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, xxxx. Test Case Type PAN Exp Amount Expected Result Date TND001 ALE /13 $10.00 Approved TND002 ALE /11 $10.00 Expired Card TND003 ALE /13 $10.00 Invalid Card Number TND004 Through TND051 ALE /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 ("AV") 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: xxxx. Test Case Type PAN Exp Date CVV201 CVV202 Amount CVV2 Expected Result ALE Or /13 $ Approved, CVV Matches ALE Or /13 $ Approved, CVV Doesn t Match

14 CVV203 ALE /13 $ Approved, CVV not processed Or CVV /13 $ Approved, CVV Matches CVV205 CVV206 ALE or /13 $ Declined, CVV Not Processed ALE or /13 $ Declined, CVV Matches 4c Address Verification Test Cases The following test cases will certify address verification transactions using AV. The credit card used for these test cases is xxxx. Test AV if AV is activated on the Merchant Account. Test Case Type PAN Exp Date AV01 AV02 AV03 AV04 AV05 Amount Address Postal Code ALE /11 $ Fifth treet Or ALE /11 $ Fifth treet Or ALE /11 $ Fifth treet Or ALE or /11 $ Fifth treet ALE or /11 $ Fifth treet Expected Result Approved, both address & zip match Approved, address match, zip not match Approved, zip match, address does not match Approved, address and zip do not match Approved, international non- AV participant AV06 ALE or /11 $ Fifth treet Declined, AV Unavailable

15 4d Checking Account and avings 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 , for Decline Testing use routing number of For the cardholder name, use "John Q. Public" or the name of your favorite tar Wars character. Test Case Type Account Number Check Number Amount Expected Result ACH01 CHECK $10.00 Approved ACH02 CHECK $10.00 Approved ACH03 CHECK $10.00 Approved ACH04 CHECK $10.00 Decline ACH05 CHECK $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 pecial 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 ystems (CM) 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 CM package. 2. The developer should take into account the need to disable the ubmit 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 ubmit 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 QA Level A compliant. Any form validation for required fields or completeness must take place on the client s machine via Javacript, AJAX, jquery, etc. Checks may need to be implemented to check for Javacripting 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, afari, 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, AV codes located here - ample Code in PHP may be downloaded here - For integration assistance please contact via [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.