User Guide for Direct Post Method JavaScript Relay URL Redirect

Transcription

1 User Guide for Direct Post Method JavaScript Relay URL Redirect Version 4.0 Last Updated: 10/2/2017

2 Table of Contents Document Version... 4 Contact Information... 4 Direct Post Options... 5 Introduction Concept Overview Direct Post Method Data flow Requirements Submitting a Transaction Transaction Post URL HTML Form Post Syntax Authentication Information (Process Key) Donor s Information Fields Custom Information Fields Client Defined Fields Single Credit Card Transaction Fields Single ACH Transaction Fields Creating Secure Tokens Relay URL Encrypted Magnetic Stripe Readers Overview Supported Hardware Using the MSR s Development requirements - Magtek Magtek Dynamag USB Encrypted swiper Development requirements IDTech IDTech SecureMag USB card swipe JavaScript to choose card reader type Transaction Responses Standard Fields in the Transactions Response Single Credit Card Transaction Response Rejection codes for Credit Card Responses Single ACH Transaction Response Token Transactions Response Page 2 of 40

3 7.4.1 Non-recurring Tokens BTokens with a recurring schedule Relay Page Dynamic Page Front-end JavaScript to be returned to iats Code Behind to accept the HTTPS Post results from iats server Code Samples SAMPLE HTML Payment Form Without Card Reader SAMPLE HTML Payment Form With Card Reader Example Responses Single Credit Card Transaction Response Example Single ACH Transaction Response Example Creating a Token for Credit Card Transaction Response Creating a Token for ACH Transaction Response Appendix A: Testing Systems Page 3 of 40

4 Document Version Document Change Date of Change: DPM Guide Added process URL for UK/International system Added contact information Added fields in the Transaction response Sep 22, 2017 Contact Information North America: UK/International: Customer Care: Phone: North America: UK/Europe: Hours: 7:30am 5:00pm Pacific Standard Time, Monday to Friday Sales and Marketing: Phone: North America: UK/Europe: Hours: 7:00am 4:30pm Pacific Standard Time, Monday to Friday Partner Support: Hours: 7:00am 4:30pm Pacific Standard Time, Monday to Friday Page 4 of 40

5 Direct Post Options iats offers two options for the Direct Post Method: Option 1 This uses a JavaScript Relay URL redirect that allows the developer more control over the redirect page as well as the message that displays to the donor as a result of the transaction response (example rejection codes). All transaction detail is posted back to the relay page which can be used to capture into the developers database. Option 2 This does not utilize JavaScript but a Direct Redirect. This option only allows the programmer to redirect to two static pages a successful transaction page or a failed transaction page. As no relay page is utilized, the details of the transaction will be sent to a postback URL. Please refer to separate document for this option. DPM Relay URL DPM Direct Redirect Dynamic response page Yes, through JavaScript relay page. Relay URL sent in DPM transaction request. No, only static pages for success/fail. Both URL sent in DPM transaction request. Transaction results Posted back to relay URL Posted back to Postback URL Page 5 of 40

6 Introduction This user guide describes the web development required to process transactions via using the Direct Post Method. Direct Post is a fully PCI compliant service as the sensitive credit card data never flows through your servers or website. Your website does not have to handle any credit card data, and all transaction information is submitted directly to iats via Secure Sockets Layer (SSL) while keeping iats invisible to the donor. Your site can still collect all pertinent donor data and has been built to allow you to utilize your own unique website look and feel as well as response pages. The Direct Post Method can be combined with other iats Web Services such as CustomerLink (to manage recurring schedules), ProcessLink (to process transactions with a Token or do refunds using a Transaction ID), and ReportLink (pulling transaction reports from iats servers). These are explained further in our Web Service Guides and are available upon request. For managing recurring transactions, you have the option of managing them or having iats manage them for you: 1. If iats manages the recurring schedule: a. You use DPM to set up the individual Tokens (Customer Codes) and provide all payment and recurring details (amount, start/end date etc.), with the recurring tag set to true. 2. If you manage the recurring schedule: a. You use DPM to set up the individual Tokens (Customer Codes) and only provide the payment details, with the recurring tag set to false; b. Then, on the schedule date you send a batch file containing the Tokens (Customer Codes) and amount of charge using our ProcessLink Web Service. c. Any future updates (switch it OFF, delete, etc.) to the Tokens can be done via our CustomerLink Web Service. Please note that iats operates two server systems, one based in North America (NA) and one in the United Kingdom (UK). Clients in the United States and Canada will use the NA servers, while all other clients use our UK servers. The explanation of the specific services that follows will provide the links to each server address as available. Notes on International processing: 1. The same interface can be used for International processing on our UK servers however it should be noted that single ACH/EFT (Direct Debit) transactions are not allowed in the UK. Only recurring Direct Debit transactions can be initiated. 2. The recurring date format is different for UK. Please use the format DD/MM/YYYY where applicable. Page 6 of 40

7 1 Concept Overview With Direct Post, the transaction data is submitted directly to iats payment gateway by means of HTML form POST, bypassing the host s server. Upon authorization, iats posts the transaction result or the token information to the host s relay URL. Direct Post then redirects the end user s browser to the host s server using a client-side JavaScript. iats will be invisible with the host having full control during the process. The Direct Post method will provide the following options: 1. Processing a single credit card transaction (available for both NA and international processing) 2. Processing a single ACH transaction (available for only NA processing) 3. Creating a token to store payment details or for recurring transactions (available for both NA and international CC processing, and NA ACH/EFT only) 4. Create a token (without recurring) AND transact at the same time. 5. Create a token (with recurring) AND transact at the same time. 2 Direct Post Method Data flow 1. The website Host (merchant) creates an HTML payment form following the iats specifications described within this guide. The form must contain all required fields to complete the credit card or ACH transaction process successfully. See the Submitting Transaction section for more details. The HTML form should use the following syntax: North America <form action=" method="post" name="iats_dpm_form"> <input type="submit" value="submit Transaction"/> </form> UK/International <form action=" method="post" name="iats_dpm_form"> <input type="submit" value="submit Transaction"/> </form> iats provides a process URL where the transaction collected on the merchant s website should be submitted by means of HTML form POST. The host s payment form created in step 1 above will be posted to iats. Within the post data you will need to include the relay URL which is the page hosted on the merchants website to handle the response of the transaction result. Page 7 of 40

8 2. After receiving the transaction data or new token request, the iats payment gateway will process the transaction and return the transaction result back to the merchant s relay URL by means of HTTPS POST. 3. Based on the Transaction results (approval, decline or new token), the merchant provides iats with a return page with the required redirect JavaScript to send the donor to. The host will need to have different transaction response pages for approval, declined and new token transactions. See the Submitting Transaction section for more details. 4. iats will then redirect the end user s browser to the JavaScript returned to iats from the merchant to show the customized response page. In this process the end user will stay on merchant s website, however they will see the browser refresh when they are redirected to the response page. Merchants Server will host: The Payment Form Relay URL s for iats The Response Pages Payment Form 1. HTTP Post 3. Based on Results, send iats Approval, Decline or Token Page Redirect JavaScript containing the redirect URL 2. Post back to Relay URL Page w/transaction Results Approval, Decline or New Token Response Page 4. Redirect Donor iats Server will: Processes the requested Transactions (Single Credit Card/ACH, Token) Send Transaction Results to merchant s relay URL Redirect Donor to Response Pages supplied by merchant s relay URL Page 8 of 40

9 3 Requirements 1. Merchant must have received the client s valid iats Process Key associated with their Client Code which is has been enabled to process credit card and/or ACH transactions. Instructions on how the client creates the Process Key are included below. 2. Merchant needs to create the HTML payment form on their own web server. The form must have the required payment fields following the iats specifications in this document. The standard API consists of required and optional fields that can be submitted to iats for real time credit card transaction processing. See the Submitting Transaction section for more details 3. Merchant needs to build relay pages to be able to handle the https post transaction result from the iats payment gateway. The relay page will return a client side JavaScript to iats with redirect response page URL. 4. Merchant needs to build a transaction response page to be displayed to the end user for the various responses: Success, Failed, Token and Token with success or failed transaction. Page 9 of 40

10 4 Submitting a Transaction 4.1 Transaction Post URL The Direct Post transaction should POST to the following URLs: North America UK/International HTML Form Post Syntax Transaction data will be submitted to iats by means of HTML form POST. The host needs to have the HTML form collect the transaction data from the end user and the form should be in the following syntax: North America <form action=" method="post" name="iats_dpm_form"> <input type="submit" value="submit Transaction"/> </form> UK/International <form action=" method="post" name="iats_dpm_form"> <input type="submit" value="submit Transaction"/> </form> The following sections describe the required and optional form fields that can be submitted to iats payment gateway by using Direct Post. 4.3 Authentication Information (Process Key) The transaction authentication used by the Direct Post is the Process Key. The Process Key is encrypted and secure. Each merchant can generate a unique process key after receiving a valid iats Client Code. To create a Process Key: (1) Log on to the iats portal (2) Go to User Profile (3) Select Change Password (4) Under Manage process key section, click the Create New Process Key button. Page 10 of 40

11 Notes on Process Key: If the Create button is clicked again at some point in the future, a new Process Key will be generated, invalidating the old one. If this occurs, the new Key will need to be added to the code to replace the old one. Changes to the Client Code password at a future time will not affect the existing process key or make it invalid. The process key should be embedded in the payment form but not visible to the donor. The Process Key field must be submitted using the syntax below. <input type="hidden" name="iats_dpm_processid" value="put process key here"/> Field name Value Note IATS_DPM_ProcessID Process Key Merchant- and transaction-specific encrypted key for authentication. Required field. Page 11 of 40

12 4.4 Donor s Information Fields The following table represents the HTML form donor information fields that can be submitted to iats using Direct Post. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> Field name Value Note Required or Optional IATS_DPM_Title Title for the end user. Up to 39 characters. Optional but recommended IATS_DPM_FirstName First name for the end user. Up to 39 characters. Optional but recommended IATS_DPM_LastName Last name for the end user. Up to 39 characters. Optional but recommended IATS_DPM_Address Address for the end user. Up to 99 characters Optional IATS_DPM_City City of the address. Up to 39 characters Optional IATS_DPM_Province Province of the address. Up to 39 characters Optional IATS_DPM_Country Country of the address. Up to 39 characters Optional IATS_DPM_ZipCode Zip code of the address. Up to 10 characters. Optional but. recommended IATS_DPM_Phone Phone number for the end users. Up to 39 characters. Optional IATS_DPM_Phone2 Phone number for the end users. Up to 39 characters Optional IATS_DPM_Fax Fax number for the end user. Up to 39 characters Optional IATS_DPM_ for the end user. Up to 39 characters. Optional but recommended IATS_DPM_Comment Comment associated with the transaction. Up to 110 characters Optional Page 12 of 40

13 4.5 Custom Information Fields The following table represents the HTML form fields of custom information can be submitted to IATS using Direct Post. All fields in this section are optional and will be stored in the iats system and available via ReportLink web service. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> Field name Value Note IATS_DPM_Invoice Invoice # for the end user Up to 39 characters For credit card/acheft single transaction only. IATS_DPM_Item1 Item1 for custom question Up to 39 characters IATS_DPM_Item2 Item2 for custom question Up to 39 characters IATS_DPM_Item3 Item3 for custom question Up to 39 characters IATS_DPM_Item4 Item4 for custom question Up to 39 characters IATS_DPM_Item5 Item5 for custom question Up to 39 characters IATS_DPM_Item6 Item6 for custom question Up to 39 characters 4.6 Client Defined Fields The following table represents the HTML form fields of client defined can be submitted to iats using Direct Post. iats neither stores nor processes this field s value, only acting as a pass-through to the postback URL. iats will accept up to 3 client-defined fields with the prefix IATS_DPM_ClientDefined_. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> Field name Value Note IATS_DPM_ClientDefined_(insert name) Value of client defined field 1 Up to 150 characters IATS_DPM_ClientDefined_(insert name) Value of client defined field 2 Up to 150 characters IATS_DPM_ClientDefined_(insert name) Value of client defined field 3 Up to 150 characters Page 13 of 40

14 4.7 Single Credit Card Transaction Fields The following table represents the fields required for submitting a single credit card transaction using Direct Post. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> Field name Value Note Required or Optional IATS_DPM_AccountNumber Credit card number Up to 600 characters. Required Large max value due to ability to capture encrypted swiper details in this field, see section on encrypted card readers below. IATS_DPM_ExpiryDate Expiry Date Up to 5 characters Required Must be in the format of MM/YY IATS_DPM_CVV2 CVV2. Up to 4 characters. Required Must be digits only. IATS_DPM_MOP Credit card type. We accept the following card Optional VISA or MC or AMX or DSC types: VISA, MC, AMX, DSC IATS_DPM_Amount Total processed amount Numbers and decimal. Do not put currency symbol in this field. Processed amount must be greater than zero, and cannot exceed limit associated with merchant s iats Client Code. Required Page 14 of 40

15 4.8 Single ACH Transaction Fields The following table represents the fields required for submitting a single ACH transaction using Direct Post. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> Field name Value Note Required or Optional IATS_DPM_AccountNumber ACH Account number. Up to 40 characters. Must be digits only Required USD: Routing no. (9 digits) + account no. (# of digits varies) CAD: Bank no. (3 digits) + transit no. (5 digits) + account no. (# of digits varies) *Order must be followed with NO spaces example for CDN * IATS_DPM_MOP ACHEFT Up to 10 characters. The value must be ACHEFT to process ACH transactions. For other values or this field being blank, the transaction will be processed as a credit card. IATS_DPM_AccountType Debit card account type. CHECKING or SAVING Will not accept values other than CHECKING or SAVING. IATS_DPM_Amount Total processed amount. Numbers and decimal. Do not put currency sign in this field. Processed Amount must be greater than zero, and cannot exceed limit associated with merchant s iats Client Code. Required Required Required Page 15 of 40

16 4.9 Creating Secure Tokens Instead of processing a real-time transaction, the merchant can use the Direct Post to create a token which can be used for transactions at a later stage with the iats web services or to set up recurring transactions to be auto processed by iats. The iats payment gateway will return a token ID to the Host which can be used to: - Access and update payment information associated with the token iats CustomerLink Web Service - Process a single transaction on a recurring schedule using ProcessLink Web Service Please refer to the iats Web Service Guides for more details on the services offered. The data fields are name and value pairs, using the following HTML syntax: <input name="field Name" value="value"/> The following table represents the fields required for creating a secure token using Direct Post. The Host will need to have the credit card or bank account fields in the form. This payment information is what will be stored in the iats system which is associated with the token. Field name Value Note Required or Optional IATS_DPM_ProcessOption Request type of process (1) TRANSACTION (2) TOKEN (3) TOKENANDTRANSACTION This field instructs iats to create only transact, only create a token or create and tokenize at the same time Required IATS_DPM_RecurringOn The request to turn on recurring transactions. Value of TRUE or FALSE If the value is TRUE, iats will set up and process the recurring transaction based on recurring settings below. Required if ProcessOption is TOKEN or TOKENANDTRANSACTION IATS_DPM_BeginDate Recurring transaction begin date. Must be in date format: MM/DD/YYYY For the UK: DD/MM/YYYY IATS_DPM_EndDate Recurring transaction end date. Must be in date format: MM/DD/YYYY IATS_DPM_ScheduleType IATS_DPM_ScheduleMonth IATS_DPM_ScheduleDate Recurring transaction schedule type. MONTHLY or WEEKLY or QUARTERLY or ANNUALLY Month for annual recurring transaction. Date for monthly recurring transaction. For the UK: DD/MM/YYYY Set up schedule type Number from 1 to 12 Number from 1 to 31 Required if ProcessOption is TOKEN or TOKENANDTRANSACTION Required if ProcessOption is TOKEN or TOKENANDTRANSACTION Required if ProcessOption is TOKEN or TOKENANDTRANSACTION Required if ProcessOption is TOKEN or TOKENANDTRANSACTION Required if ProcessOption is TOKEN or TOKENANDTRANSACTION Page 16 of 40

17 5 Relay URL The following table describes form fields that can be submitted to configure the relay response. The relay URL should be embedded in the payment form but not visible to the end user. The relay URL fields are submitted using the syntax below. <input name="iats_dpm_relayurl" value="url"/> Field name Value Note Required or Optional IATS_DPM_RelayURL The URL on the merchant s website to which iats posts transaction results to for a relay response. iats will post transaction result to this URL. The value must contain a valid URL including prefix: or Required 6 Encrypted Magnetic Stripe Readers 6.1 Overview Our encrypted magnetic stripe readers (MSRs) are fully PCI compliant as the sensitive credit card data is encrypted immediately within the device before the data flows through to the computer or device. This means your servers do not have to handle any clear text credit card data. The encrypted MSRs are designed to work with the Direct Post Method. When a credit card is swiped through the MSR, it will read and encrypt the track data on the magnetic stripes and pass the encrypted data to the Account Number field in DPM to the relevant web service to either a) process the transaction directly or b) tokenize the details for future transactions, or c) process the transaction directly and tokenize the details for future transactions 6.2 Supported Hardware The following supported magnetic stripe readers should be ordered directly from as they contain encryption keys only accessible by iats: USB (PC and Mac) - MagTek DynaMag - ID Tech SecureMag 6.3 Using the MSR s As there are a number of variations of the swiper, iats needs to know which swiper is being used so that iats can supply the correct encryption key to the transaction. Once the user has swiped the card in the Credit Card field, the swiper type needs to be appended to the front of the transaction string before being sent to iats. Page 17 of 40

18 For example: IATS_DPM_AccountNumber = [Encryption string] 6.4 Development requirements - Magtek Magtek Dynamag USB Encrypted swiper The Magtek Dynamag is a USB encrypted swiper for use on PC s. When you swipe the USB device a complete string of masked as well as encrypted data. You can use the masked data for the name of the client, the expiry date and last 4 digits of the credit card. For the USB swipers, the entire string (masked and encrypted) as well as the identification of the swiper type needs to be passed through to iats. Magtek USB encrypted swipe example: %B ^YOU/AGIFTFOR^ ?; = ? F2E4 4C1E BC08BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC427958C E07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B D3C33B0CEBAC0147D7B489E AE E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D16959F CA573B81CE4ED3CF0BC0FA 1B3067C034A946E9F80F3D7B For the Magtek Dynamag, please append the data in the following order and delimitation: Entire USB output Where: - SwiperType : 02 for Magtek Dynamag - Entire USB output string (no parsing) : Delimiter MagTek USB swipe to be entered into IATS_DPM_AccountNumber field %B ^YOU/AGIFTFOR^ ?; = ? F2E44C1E BC08BB06CE1A9CD897EC00E2BB035C6D9FDF625F7AF63034BDBEC092D8C035B05301A89C056854B6EC CE07AD5E585E4E37E2867B3 2CAF4061ACD747C310DA546974D045C8C446C7C6B8577B D3C33B0CEBAC0147D7 B489EAE E005095F7A5E2F9B3076FBA250877E9105BEE932ABF6A0F02B7D16959F CA573B81CE4ED3CF0 BC0FA1B3067C034A946E9F80F3D7B Page 18 of 40

19 6.5 Development requirements IDTech IDTech SecureMag USB card swipe The IDTech Secure Mag is a USB encrypted swipe for PC s and Laptops. When you swipe the USB device, it will collect a complete string of masked as well as encrypted data. You can use the unmasked data for the name of the client, the expiry date and last 4 digits of the credit card. For the USB swipers the entire string (masked and encrypted) needs to be passed through to iats. IDTECH USB encrypted swipe example: 02A001801F3B B%*4941********5889^YOU/AGIFTFOR^***********************?*;4941********5889=****** *********?*ACC8778A7A496718C9EF3F042025E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F010B9E9 DB243DBD3EB56825B6F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA D640B46EDA8 E6C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B A39DA8FFFF D68AA03 For the IDTech Secure Mag, please collate the data in the following order and delimitation: Entire USB output Where: - SwiperType : 00 for IDTech Secure Mag - Entire USB output string (no parsing) : Delimiter IDTech USB swipe to be entered into IATS_DPM_AccountNumber field 02A001801F3B B%*4941********5889^YOU/AGIFTFOR^***********************?*;4941********5889=* **************?*ACC8778A7A496718C9EF3F042025E239FDC93C1C616153EE8057CC23D3D28B68948BD00FCCF9E30D44F01 0B9E9DB243DBD3EB56825B6F0D64D6CDD0B12AF6F7C068C7A7CB17B45B9D5D9DF7F9CD340987AFF4C5F33AA D640B4 6EDA8E6C526BB5DE9E0C7C71AE6510C73F3A5ECFAADDCD3F62CBD1DBEE00990C21E9DA6A0170A3C363B1B A39DA 8FFFF D68AA03 Page 19 of 40

20 6.6 JavaScript to choose card reader type If you want to use the card readers as per above, then you can use the following piece of JavaScript to choose the reader type and append the correct number to the string when the form is submitted. This allows the user to use the card reader directly without needing to add the reader type each time. Add the following script to the header: <head> <script type="text/javascript"> /** * Preprocess IATS_DPM_AccountNumber field if using a USB card reader. */ function usbreaderpreprocess() { // Get the USB card reader type. var usbdevicetype = document.getelementbyid('usb_device_type').value; if (usbdevicetype!= '') { // Get the unprocessed USB card reader input. var readerinput = document.getelementbyid('iats_dpm_accountnumber').value; // Prepend USB card reader type to the reader input. var processedreaderinput = usbdevicetype + ' + readerinput; // Update the form with the processed reader input. document.getelementbyid('iats_dpm_accountnumber').value = processedreaderinput; // Parse the payer's name from the reader input. var namematch = readerinput.match(/\^([a-z]+)\/([a-z]+)\^/gi); if (namematch!= null) { var namestring = namematch[0].replace(/\^/g, ''); var nameparts = namestring.split('/'); } } } // Update the form with the payer's first and last names. document.getelementbyid('iats_dpm_firstname').value = nameparts[1]; document.getelementbyid('iats_dpm_lastname').value = nameparts[0]; </script> </head> Page 20 of 40

21 Add the following to your body: <label class="" for="usb_device_type">usb Device</label> <select id="usb_device_type"> <option value="">none</option> <option value="00">idtech SecureMag USB swiper</option> <option value="02">magtek Dynamag USB swiper</option> </select> <br /><br /> Also, make sure to add the OnSubmit function to the form action: North America <form action=" method="post" name="iats_dpm_form" onsubmit="usbreaderpreprocess()"> UK/International <form action=" method="post" name="iats_dpm_form" onsubmit="usbreaderpreprocess()"> The above code combined will give you ability to choose the swiper being used. You could of course pre-fill the card reader type and hide the field so its completely anonymous to the users. Page 21 of 40

22 7 Transaction Responses When a Relay Response is configured, the transaction response that is returned to the merchant from the iats payment gateway is a set of fields that provides information about the status of the transaction. For single credit card transactions iats will provide real-time transaction approval or rejection results. For ACH transactions, the result is always approved because it takes at least one day to settle the transaction. For the ACH process please refer to the Web Service documentation ProcessLink. If the request is to create a token, the response is the detail of the token information created by iats system. The merchant server can parse the data in the returned response and customize the message to display to the end user. 7.1 Standard Fields in the Transactions Response Below is the table for all the standard fields iats will return to the merchant s relay URL. iats will return all donors information collected on the merchant s HTML payment form. Field name Value Note IATS_Title Title for the end user Up to 39 characters IATS_FirstName First name for the end user Up to 39 characters IATS_LastName Last name for the end user Up to 39 characters IATS_Address Address for the end user Up to 99 characters IATS_City City of the address Up to 39 characters IATS_State State/Province of the address Up to 39 characters IATS_Country Country of the address Up to 39 characters IATS_ZipCode Zip code of the address Up to 10 characters IATS_Phone Phone number for the end user Up to 39 characters IATS_Phone2 Phone number 2 for the end user Up to 39 characters IATS_Fax Fax number for the end user Up to 39 characters IATS_ for the end user Up to 39 characters IATS_Comment Comment for the end user Up to 39 characters IATS_Invoice Invoice # for the end user Up to 39 characters For credit card/acheft single transaction only IATS_Item1 Item1 for custom question Up to 39 characters IATS_Item2 Item2 for custom question Up to 39 characters IATS_Item3 Item3 for custom question Up to 39 characters IATS_Item4 Item4 for custom question Up to 39 characters IATS_Item5 Item5 for custom question Up to 39 characters IATS_Item6 Item6 for custom question Up to 39 characters IATS_Item7 Not available for Direct Post Method yet IATS_Item8 Not available for Direct Post Method yet IATS_Item9 Not available for Direct Post Method yet IATS_Item10 Not available for Direct Post Method yet IATS_Item11 Not available for Direct Post Method yet Page 22 of 40

23 IATS_Item12 Not available for Direct Post Method yet IATS_Item13 Not available for Direct Post Method yet IATS_Item14 Not available for Direct Post Method yet IATS_Item15 Not available for Direct Post Method yet IATS_ClientDefined_(insert name) Value of client defined field 1 Up to 150 characters IATS_ClientDefined_(insert name) Value of client defined field 2 Up to 150 characters IATS_ClientDefined_(insert name) Value of client defined field 3 Up to 150 characters IATS_Payment_AgencyCodeHash Client code hash SHA 1 of 4 character client code in uppercase IATS_Payment_SubCode Last two digits of user name Example: TEST88 sub-code is 88 IATS_Amount Transaction amount 7.2 Single Credit Card Transaction Response Below is the table of results for a transaction that iats will return to merchant s relay URL for a single credit card transaction. Field name Value Note IATS_AccountNumber Last four digits of processed credit Up to 4 characters card number IATS_MOP Method of Payment Up to 10 characters. We accept the following card types: VISA, MC, AMX, DSC IATS_PaymentType Payment Type: credit card or ACH Value of CreditCard IATS_Result Transaction result OK: approval code Reject: rejection code Reject: TIMEOUT IATS_TransID Transaction ID This value is the transaction ID the merchant can use to search the transaction in iats customer portal IATS_ExpiryMonth Credit card expiry month Two digit number, from 1-12 IATS_ExpiryYear Credit card expiry year Four digit number, example 2017 Page 23 of 40

24 7.2.1 Rejection codes for Credit Card Responses Below is the list of transaction rejection codes. For a more detailed list, please refer to Page 24 of 40

25 7.3 Single ACH Transaction Response Below is the table of transaction result fields that iats will return to merchant s relay URL for a single ACH transaction. Field name Value Note IATS_AccountNumber Last four digits of account number IATS_MOP Method of Payment Value of ACHEFT IATS_PaymentType Payment Type, credit card or ACH Value of ACH IATS_Result Transaction result Value of OK: ACH transactions are not real time and takes at least one day to process. iats will return temporary approval result. Successful or rejected ACH transactions should be retrieved using the iats Web Service ReportLink IATS_TransID Transaction ID This value is the transaction ID the merchant can use to search the transaction in iats customer portal IATS_DebitAccountType Account type Value of CHECKING or SAVING Page 25 of 40

26 7.4 Token Transactions Response Below is the table of the response fields iats will return to merchant s relay URL for a request to create a token Non-recurring Tokens Field name Value Note IATS_AccountNumber Last four digits of processed Up to 4 characters account number IATS_PaymentType Method of Payment Value of CreditCard or ACH IATS_Result TokenCreated or TokenFailed IATS_ResultDetail Token ID or Error message If the Token is created successfully, it will start with a letter followed by number, for example A If it fails the detail will be in the message BTokens with a recurring schedule The following fields are for when a recurring setting was set up for the token. If the host posts recurring settings in the original request, iats will post the same settings back. Otherwise iats will return default settings. Field name Value Note IATS_BeginDate Recurring transaction begin date Default value is today s date IATS_EndDate Recurring transaction end date Default value is today s date IATS_ScheduleType IATS_RecurringOn Recurring transaction schedule type. MONTHLY or WEEKLY or QUARTERLY or ANNUALLY Recurring turned on. ON or OFF Value of MONTHLY or WEEKLY or QUARTERLY or ANNUALLY Default value is MONTHLY. Value of ON or OFF. Default value is OFF. Page 26 of 40

27 8 Relay Page Direct Post provides a relay response feature to communicate the transaction results to the merchant. The merchant can use the relay response feature to create a custom response page using transaction results returned by iats. The response page is then relayed to the customer s web browser. 8.1 Dynamic Page To create a dynamic page to redirect the donor to various pages depending on the results of the transaction then the relay page sent to iats must contain the following JavaScript to redirect the end user to the correct URL Front-end JavaScript to be returned to iats Relay.aspx <%@ Page Language="C#" CodeBehind="relayPage.aspx.cs" Inherits="IATSDirectPostTest.relayPage" %> <html> <head> <script type='text/javascript' charset='utf-8'> window.location = '<%=redirecturi %>'; </script> </head> <body></body> </html> Code Behind to accept the HTTPS Post results from iats server Relaypage.aspx.cs Namespace IATSDirectPostTest { public partial class relaypage : System.Web.UI.Page { public string redirecturi = ""; protected void Page_Load(object sender, EventArgs e) { //Get transaction result from POST data if(request.form["iats_result"]!=null && Request.Form["IATS_Result"].Contains("OK")){ //If the transaction is approval, redirect to approval response page. redirecturi = " } //If the transaction is rejected, redirect to rejected response page. else redirecturi = " } } } Page 27 of 40

28 9 Code Samples Below is an example of the Direct Post HTML form and relay page. This includes all the fields so remove those that are not necessary. Make sure you include your Relay URL at the end of the form. 9.1 SAMPLE HTML Payment Form Without Card Reader <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>dpm Test Merchant</title> <style type="text/css"> label { float: left; width: 400px; } </style> </head> <body> <form action=" method="post" name="iats_dpm_form"> <div><strong>direct Post Authentication: TEST88 Processkey: PA0940D765F2BD67BD97B82EFAA4D72BE9</strong> <label class="" for="iats_dpm_processid">processkey</label> <input name="iats_dpm_processid" class="" id="iats_dpm_processid" value="pa0940d765f2bd67bd97b82efaa4d72be9" /> <br /><br /> <div><strong>donors information</strong> <label class="" for="iats_dpm_title">title</label> <input name="iats_dpm_title" class="" id="iats_dpm_title" maxlength="39" /> <label class="" for="iats_dpm_firstname">first Name</label> <input name="iats_dpm_firstname" class="" id="iats_dpm_firstname" maxlength="39" /> <label class="" for="iats_dpm_lastname">last Name</label> <input name="iats_dpm_lastname" class="" id="iats_dpm_lastname" maxlength="39" /> <label class="" for="iats_dpm_address">address</label> <input name="iats_dpm_address" class="" id="iats_dpm_address" maxlength="39" /> <label class="" for="iats_dpm_city">city</label> <input name="iats_dpm_city" class="" id="iats_dpm_city" maxlength="39" /> Page 28 of 40

29 <label class="" for="iats_dpm_province">state/province</label> <input name="iats_dpm_province" class="" id="iats_dpm_province" maxlength="39" /> <label class="" for="iats_dpm_country">country</label> <input name="iats_dpm_country" class="" id="iats_dpm_country" maxlength="39" /> <label class="" for="iats_dpm_zipcode">zip Code</label> <input name="iats_dpm_zipcode" class="" id="iats_dpm_zipcode" maxlength="39" /> <label class="" for="iats_dpm_phone">phone</label> <input name="iats_dpm_phone" class="" id="iats_dpm_phone" maxlength="39" /> <label class="" for="iats_dpm_phone">phone2</label> <input name="iats_dpm_phone2" class="" id="iats_dpm_phone2" maxlength="39" /> <label class="" for="iats_dpm_phone">fax</label> <input name="iats_dpm_fax" class="" id="iats_dpm_fax" maxlength="39" /> <label class="" for="iats_dpm_ "> </label> <input name="iats_dpm_ " class="" id="iats_dpm_ " maxlength="39" /> <label class="" for="iats_dpm_comment">comment</label> <input name="iats_dpm_comment" class="" id="iats_dpm_comment" maxlength="39" /> <label class="" for="iats_dpm_item1">item1</label> <input name="iats_dpm_item1" class="" id="iats_dpm_item1" maxlength="39" /> <label class="" for="iats_dpm_item2">item2</label> <input name="iats_dpm_item2" class="" id="iats_dpm_item2" maxlength="39" /> <label class="" for="iats_dpm_item3">item3</label> <input name="iats_dpm_item3" class="" id="iats_dpm_item3" maxlength="39" /> <label class="" for="iats_dpm_item4">item4</label> <input name="iats_dpm_item4" class="" id="iats_dpm_item4" maxlength="39" /> <label class="" for="iats_dpm_item5">item5</label> <input name="iats_dpm_item5" class="" id="iats_dpm_item5" maxlength="39" /> <label class="" for="iats_dpm_item6">item6</label> <input name="iats_dpm_item6" class="" id="iats_dpm_item6" maxlength="39" /> <label class="" for="iats_dpm_clientdefined_name1">client Defined Field 1</label> <input name="iats_dpm_clientdefined_name1" class="" id="iats_dpm_clientdefined_name1" maxlength="150" /> Page 29 of 40

30 <label class="" for="iats_dpm_clientdefined_name2">client Defined Field 2</label> <input name="iats_dpm_clientdefined_name2" class="" id="iats_dpm_clientdefined_name2" maxlength="150" /> <label class="" for="iats_dpm_clientdefined_name3">client Defined Field 3</label> <input name="iats_dpm_clientdefined_name3" class="" id="iats_dpm_clientdefined_name3" maxlength="150" /> <br /><br /> <div><strong>amount</strong> <label class="" for="iats_dpm_amount">amount</label> <input name="iats_dpm_amount" class="" id="iats_dpm_amount" maxlength="39" /> <br /><br /> <div><strong>payment</strong> <label class="" for="iats_dpm_mop">method of Payment</label> <input name="iats_dpm_mop" class="" id="iats_dpm_mop" maxlength="39" /> <label class="" for="iats_dpm_accountnumber">account Number</label> <input name="iats_dpm_accountnumber" class="" id="iats_dpm_accountnumber" maxlength="600" /> <label class="" for="iats_dpm_expirydate">expiry (for credit card)</label> <input name="iats_dpm_expirydate" class="" id="iats_dpm_expirydate" maxlength="39" /> <label class="" for="iats_dpm_cvv2">cvv2 (for credit card)</label> <input name="iats_dpm_cvv2" class="" id="iats_dpm_cvv2" maxlength="39" /> <label class="" for="iats_dpm_debitaccounttype">debit Account Type (for ACH)</label> <input name="iats_dpm_debitaccounttype" class="" id="iats_dpm_debitaccounttype" maxlength="39" /> <br /><br /> <div><strong>process Option</strong> <label class="" for="iats_dpm_processoption">process Option</label> <input name="iats_dpm_processoption" class="" id="iats_dpm_ ProcessOption" maxlength="39" /> <br /> <label class="" for="iats_dpm_recurringon">enter True for Recurring</label> <input name="iats_dpm_recurringon" class="" id="iats_dpm_recurringon" maxlength="39" /> <br /> <label class="" for="iats_dpm_begindate">begindate</label> <input name="iats_dpm_begindate" class="" id="iats_dpm_begindate" maxlength="39" /> <br /> <label class="" for="iats_dpm_enddate">enddate</label> <input name="iats_dpm_enddate" class="" id="iats_dpm_enddate" maxlength="39" /> <br /> <label class="" for="iats_dpm_scheduletype">scheduletype</label> <input name="iats_dpm_scheduletype" class="" id="iats_dpm_scheduletype" maxlength="39" /> <br /> <label class="" for="iats_dpm_schedulemonth">schedulemonth (If Schedule Type is Annual)</label> <input name="iats_dpm_schedulemonth" class="" id="iats_dpm_schedulemonth" maxlength="39" /> <br /> <label class="" for="iats_dpm_scheduledate">scheduledate (If Schedule Type is Monthly)</label> <input name="iats_dpm_scheduledate" class="" id="iats_dpm_scheduledate" maxlength="39" /> <br /> Page 30 of 40

31 <br /><br /> <div><strong>relay Response</strong> <label class="" for="iats_dpm_relayurl">relay URL</label> <input type="input" name="iats_dpm_relayurl" class="" id="iats_dpm_relayurl" value="enter RELAY URL HERE" /> <br /><br /> <input type="submit" value="process"/> </form> </body> Page 31 of 40

32 9.2 SAMPLE HTML Payment Form With Card Reader <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" " <html xmlns=" <head> <title>dpm Test Merchant</title> <style type="text/css"> label { float: left; width: 400px; } </style> <script type="text/javascript"> /** * Preprocess IATS_DPM_AccountNumber field if using a USB card reader. */ function usbreaderpreprocess() { // Get the USB card reader type. var usbdevicetype = document.getelementbyid('usb_device_type').value; if (usbdevicetype!= '') { // Get the unprocessed USB card reader input. var readerinput = document.getelementbyid('iats_dpm_accountnumber').value; // Prepend USB card reader type to the reader input. var processedreaderinput = usbdevicetype + ' + readerinput; // Update the form with the processed reader input. document.getelementbyid('iats_dpm_accountnumber').value = processedreaderinput; // Parse the payer's name from the reader input. var namematch = readerinput.match(/\^([a-z]+)\/([a-z]+)\^/gi); if (namematch!= null) { var namestring = namematch[0].replace(/\^/g, ''); var nameparts = namestring.split('/'); } } } // Update the form with the payer's first and last names. document.getelementbyid('iats_dpm_firstname').value = nameparts[1]; document.getelementbyid('iats_dpm_lastname').value = nameparts[0]; </script> </head> <body> <form action=" method="post" name="iats_dpm_form" onsubmit="usbreaderpreprocess()"> <div><strong>direct Post Authentication: TEST88 Processkey: PA0940D765F2BD67BD97B82EFAA4D72BE9</strong> Page 32 of 40

33 <label class="" for="iats_dpm_processid">processkey</label> <input name="iats_dpm_processid" class="" id="iats_dpm_processid" value="pa0940d765f2bd67bd97b82efaa4d72be9" /> <br /><br /> <label class="" for="usb_device_type">usb Device</label> <select id="usb_device_type"> <option value="">none</option> <option value="00">idtech SecureMag USB swiper</option> <option value="02">magtek Dynamag USB swiper</option> </select> <br /><br /> <div><strong>donors information</strong> <label class="" for="iats_dpm_title">title</label> <input name="iats_dpm_title" class="" id="iats_dpm_title" maxlength="39" /> <label class="" for="iats_dpm_firstname">first Name</label> <input name="iats_dpm_firstname" class="" id="iats_dpm_firstname" maxlength="39" /> <label class="" for="iats_dpm_lastname">last Name</label> <input name="iats_dpm_lastname" class="" id="iats_dpm_lastname" maxlength="39" /> <label class="" for="iats_dpm_address">address</label> <input name="iats_dpm_address" class="" id="iats_dpm_address" maxlength="39" /> <label class="" for="iats_dpm_city">city</label> <input name="iats_dpm_city" class="" id="iats_dpm_city" maxlength="39" /> <label class="" for="iats_dpm_province">state/province</label> <input name="iats_dpm_province" class="" id="iats_dpm_province" maxlength="39" /> <label class="" for="iats_dpm_country">country</label> <input name="iats_dpm_country" class="" id="iats_dpm_country" maxlength="39" /> <label class="" for="iats_dpm_zipcode">zip Code</label> <input name="iats_dpm_zipcode" class="" id="iats_dpm_zipcode" maxlength="39" /> <label class="" for="iats_dpm_phone">phone</label> <input name="iats_dpm_phone" class="" id="iats_dpm_phone" maxlength="39" /> <label class="" for="iats_dpm_phone">phone2</label> <input name="iats_dpm_phone2" class="" id="iats_dpm_phone2" maxlength="39" /> Page 33 of 40

34 <label class="" for="iats_dpm_phone">fax</label> <input name="iats_dpm_fax" class="" id="iats_dpm_fax" maxlength="39" /> <label class="" for="iats_dpm_ "> </label> <input name="iats_dpm_ " class="" id="iats_dpm_ " maxlength="39" /> <label class="" for="iats_dpm_comment">comment</label> <input name="iats_dpm_comment" class="" id="iats_dpm_comment" maxlength="39" /> <label class="" for="iats_dpm_item1">item1</label> <input name="iats_dpm_item1" class="" id="iats_dpm_item1" maxlength="39" /> <label class="" for="iats_dpm_item2">item2</label> <input name="iats_dpm_item2" class="" id="iats_dpm_item2" maxlength="39" /> <label class="" for="iats_dpm_item3">item3</label> <input name="iats_dpm_item3" class="" id="iats_dpm_item3" maxlength="39" /> <label class="" for="iats_dpm_item4">item4</label> <input name="iats_dpm_item4" class="" id="iats_dpm_item4" maxlength="39" /> <label class="" for="iats_dpm_item5">item5</label> <input name="iats_dpm_item5" class="" id="iats_dpm_item5" maxlength="39" /> <label class="" for="iats_dpm_item6">item6</label> <input name="iats_dpm_item6" class="" id="iats_dpm_item6" maxlength="39" /> <label class="" for="iats_dpm_clientdefined_name1">client Defined Field 1</label> <input name="iats_dpm_clientdefined_name1" class="" id="iats_dpm_clientdefined_name1" maxlength="150" /> <label class="" for="iats_dpm_clientdefined_name2">client Defined Field 2</label> <input name="iats_dpm_clientdefined_name2" class="" id="iats_dpm_clientdefined_name2" maxlength="150" /> <label class="" for="iats_dpm_clientdefined_name3">client Defined Field 3</label> <input name="iats_dpm_clientdefined_name3" class="" id="iats_dpm_clientdefined_name3" maxlength="150" /> <br /><br /> <div><strong>amount</strong> <label class="" for="iats_dpm_amount">amount</label> <input name="iats_dpm_amount" class="" id="iats_dpm_amount" maxlength="39" /> Page 34 of 40

35 <br /><br /> <div><strong>payment</strong> <label class="" for="iats_dpm_mop">method of Payment</label> <input name="iats_dpm_mop" class="" id="iats_dpm_mop" maxlength="39" /> <label class="" for="iats_dpm_accountnumber">account Number</label> <input name="iats_dpm_accountnumber" class="" id="iats_dpm_accountnumber" maxlength="600" /> <label class="" for="iats_dpm_expirydate">expiry (for credit card)</label> <input name="iats_dpm_expirydate" class="" id="iats_dpm_expirydate" maxlength="39" /> <label class="" for="iats_dpm_cvv2">cvv2 (for credit card)</label> <input name="iats_dpm_cvv2" class="" id="iats_dpm_cvv2" maxlength="39" /> <label class="" for="iats_dpm_debitaccounttype">debit Account Type (for ACH)</label> <input name="iats_dpm_debitaccounttype" class="" id="iats_dpm_debitaccounttype" maxlength="39" /> <br /><br /> <div><strong>process Option</strong> <label class="" for="iats_dpm_processoption">process Option</label> <input name="iats_dpm_processoption" class="" id="iats_dpm_ ProcessOption" maxlength="39" /> <br /> <label class="" for="iats_dpm_recurringon">enter True for Recurring</label> <input name="iats_dpm_recurringon" class="" id="iats_dpm_recurringon" maxlength="39" /> <br /> <label class="" for="iats_dpm_begindate">begindate</label> <input name="iats_dpm_begindate" class="" id="iats_dpm_begindate" maxlength="39" /> <br /> <label class="" for="iats_dpm_enddate">enddate</label> <input name="iats_dpm_enddate" class="" id="iats_dpm_enddate" maxlength="39" /> <br /> <label class="" for="iats_dpm_scheduletype">scheduletype</label> <input name="iats_dpm_scheduletype" class="" id="iats_dpm_scheduletype" maxlength="39" /> <br /> <label class="" for="iats_dpm_schedulemonth">schedulemonth (If Schedule Type is Annual)</label> <input name="iats_dpm_schedulemonth" class="" id="iats_dpm_schedulemonth" maxlength="39" /> <br /> <label class="" for="iats_dpm_scheduledate">scheduledate (If Schedule Type is Monthly)</label> <input name="iats_dpm_scheduledate" class="" id="iats_dpm_scheduledate" maxlength="39" /> <br /> <br /><br /> <div><strong>relay Response</strong> <label class="" for="iats_dpm_relayurl">relay URL</label> <input type="input" name="iats_dpm_relayurl" class="" id="iats_dpm_relayurl" value="enter RELAY URL HERE" /> <br /><br /> <input type="submit" value="process"/> </form> </body> Page 35 of 40