Title: ematters Integration API Specification. Product of: ematters Australia Pty Ltd. Version: 2.0 ABN: Date: 6 August 2012

Transcription

1 Product of: ematters Australia Pty Ltd Title: ematters Integration API Specification ABN: Version: 2.0 Date: 6 August 2012 ematters Integration API Specification

2 Contents 1 Document Control Revision History Introduction Available Functions Before You Start Getting Started API Requests Test Credit Card Numbers Getting Help ematters API (XML) - You Collect the Details Processing a Transaction Process and Complete a Pre-authorisation Processing Requests Without Credit Card Number Transaction Search Query our Bank Connections OnBill Recurring Transactions Automated Bill Response OnBill Masterfile Maintenance ematters API (https post) You collect the details Mandatory Fields Optional Fields Sample Https Form Mobile Phone Payment Page ematters Shared Payment Page - Redirect via HTTP Get Parameters ematters Shared Payment Page - Redirect via HTTP Post ematters Dedicated Payment Page - We collect the card details ematters BillSmart - Variable Recharge Amount XML Add to BillSmart XML Change to BillSmart XML Delete from BillSmart XML BillSmart Payment XML BillSmart Refund XML BillSmart Pre-Auth XML Retrieve Encrypted Card Number ematters Direct Debit Request via XML API Overview ematters DDR via Shared Payment Page Parameters Page 2 of 59

3 14 ematters Direct Credit (DCR) Parameters Appendix 1 - Test Credit Card Numbers Appendix 2 - Credit Card Response Codes Appendix 3 - Internet Merchant Facility Requirements and Contact Details Appendix 4 - Bank Help Desk Contact Details Page 3 of 59

4 1 DOCUMENT CONTROL 1.1 REVISION HISTORY Version Date Author Change Summary /03/2012 COS Completed version issued for client use /8/2012 COS Completed version issued for client use Page 4 of 59

5 2 INTRODUCTION ematters' API enables provides the ability for clients to integrate their software with ematters' payment gateway platform, allowing seamless payment processing and transaction reporting. This API provides integrators with a range of functions. The availability of these functions will depend on the facilities that have been put in place with ematters. 2.1 AVAILABLE FUNCTIONS This API specification enables the following functions to be integrated within your own systems: 1. Transaction Processing via XML (where you have an SSL certificate for collection of secure credit card data) a. Process a payment b. Process a refund c. Obtain a pre-authorisation d. Search for a transaction processed in the last seven days e. OnBill master file maintenance 2. Integrate the mobile phone payment page 3. Integrate with the ematters Shared Payment Page (where you don't have an SSL certificate for collection of secure credit card data) 4. Integrate with the ematters Dedicated Payment Page (where you don't have an SSL certificate for collection of secure credit card data, but want the payment page to look the same as your own web site) 5. Integrate with the BillSmart payment processing system via XML a. Add to BillSmart b. Change details in BillSmart c. Delete from BillSmart d. Process transactions using BillSmart e. Refund transactions f. Obtain a pre-authorisation 6. Integrate with ematters Direct Debit system via XML 7. Integrate with ematters Direct Credit system via XML These payment options are facilitated through various ematters products detailed below. Your ematters account must be configured for each of the relevant products before they can be used ONBILL OnBill Recurring Payments allows you to create and manage a recurring billing system for your customers. You can use the OnBill facility where you have your own SSL certificate and you adhere to the Visa AIS and MasterCard SDP programs. Refer to Sections 4 and 5 of this document for further details. Page 5 of 59

6 2.1.2 BILLSMART BillSmart is a unique and secure data storage facility. BillSmart stores all sensitive credit card information in a highly secure and (most importantly) a compliant data facility. With the BillSmart facility, once your customers have made their first payment we can securely retain their details, in compliance with PCI DSS, and allow you to rebill the same card at a later date. Refer to Section 11 of this document for further details MOBILE PHONE PAYMENTS The Mobile Phone Payment Page provides a fully integrated payment solution that enables your customers to make a payment to you from their web enabled smart phone. Refer to Section 6 of this document for further details WEB PAYMENT PAGE Web payments can be facilitated in two ways: 1. Shared Payment Page - hosted on our server with your data passed into the page. Refer to Sections 8 and 9 of this document for further details. 2. Dedicated Payment Page - also hosted on our server, but customized to your own branding. Refer to Section 10 of this document for further details DIRECT DEBIT ematters DDR (direct debit request) allows you to debit funds directly from your customers' bank account. It is ideal for subscriptions, monthly payments and other regular payments. It is not designed for once off payments. Refer to Sections 12 and 13 of this document for further details DIRECT CREDIT ematters DCR allows you to pay funds directly from your bank account into any other Australian bank account. Refer to Section 14 of this document for further details. Page 6 of 59

7 3 BEFORE YOU START 3.1 GETTING STARTED Once you have applied for your ematters account, you can start integration development and testing. Your Merchant and Terminal numbers are not required during this phase, however you will require these before you can go live. Contact your ematters Consultant for details of how to get started with integration. 3.2 API REQUESTS An important note about the XML requests contained within this document - all elements included in requests are case sensitive and must appear exactly as they do within this specification. 3.3 TEST CREDIT CARD NUMBERS Real credit card numbers should NEVER be used as part of the testing process. Appendix 1 of this document contains test card numbers that can be used. 3.4 GETTING HELP The ematters API is designed to be platform or programming language agnostic to allow integration with ematters regardless of the language that the client system is developed in. ematters does not retain code samples or examples in any programming language. If you want to get started with integration or have any implementation questions, you should your request to support@ematters.com.au. Page 7 of 59

8 4 EMATTERS API (XML) - YOU COLLECT THE DETAILS This API can be used to process a number of different transaction types: Process a payment; Process a refund; Process a pre-authorisation (depending on your bank); Complete a pre-authorisation (depending on your bank); Search for a transaction (processed within the last seven days); Maintain OnBill data. These are explained further in the sections below. 4.1 PROCESSING A TRANSACTION PARAMETERS Note: All name values are case-sensitive, and should be used exactly as appearing in the name values below: Name Description Format Example password readers BinIPCheck Name CreditCardHolderName CreditCardNumber CreditCardExpiryMonth CreditCardExpiryYear CVV The Posting password as stored in the System Settings in Merchant Desk. This is NOT your login password This value is provided to you by ematters and will always correspond with your Merchant ID (except where you have multiple accounts). If must be entered exactly as shown in the documentation. Failure to include this accurately will result in failed transactions Instructs the ematters gateway to compare the IP address of the transaction with the country of origin of the bank. If it matches, the transaction proceeds as normal. If it does not match, the transaction fails The name shown on the receipt and also in Merchant Desk Customer address. If Send is No, this is optional. If Send is Yes, this field is mandatory. YES or NO ABC123 MEL0036 YES John Citizen buyer@xyz.com.au Full name of the cardholder Mr J Citizen Full credit card number. Can be entered in the following formats: Two digit expiry month Integer Two or four digit expiry year Integer 12 or 2012 Card Verification Value - three digits on the back of a Integer 584 Page 8 of 59

9 Name Description Format Example Visa/Mastercard/ Diners or four digits on the front of an AMEX FinalPrice IPAddress OnBill OnBillAmount OnBillAutoUpdate OnBillDate OnBillFrequency Contains the amount of the transaction in dollars and cents. No dollar sign required The IP address of your customer's computer. Used for blocking transactions from high-risk countries and for following up fraud This is used to indicate that the transaction is to be lodged with the ematters OnBill Recurring Transaction system, repeating the processing at regular intervals This field must be provided if OnBill is YES. The amount that each FUTURE transaction will be processed for. Entered in dollars and cents, but without a dollar sign This field must be provided if OnBill is YES. Used to specify if ematters are to send an XML update after each recurring transaction. This is needed if you want to update your database with each subsequent transaction. Refer also to Section 5.1 for further details This field must be provided if OnBill is YES. The date of the FIRST recurring transaction. Only use this where you want to charge the client on a set frequency, but don't want this to start this frequency from the date of purchase. For example, if a purchase occurs on 01/02/2011 and you want the recurring payment to commence three months after the purchase date then the OnBillDate would be set to 01/05/2011. Depending on the other values provided, ematters would then process the recurring payment from 1 st May onwards This field must be provided if OnBill is YES. This field is used to determine when a recurring payment will be processed as follows: If OnBillType = FRE then the value provided in this field will be the number of days between each payment. For example, if OnBillFrequency = 30, the payment will be processed every 30 days; Numeric YES or NO YES Numeric YES or NO dd/mm/yyyy YES Numeric 30 01/05/2011 Page 9 of 59

10 Name Description Format Example If OnBillType = OAD then the value provided in this field will be the day of each month that a payment is processed. For example, if OnBillFrequency = 30, the payment will be processed on the 30 th of each month. OnBillQty OnBillReturnURL OnBillType SubMerchant UID Category The TOTAL number of payments to process, including the initial payment that is part of this transaction. For example, a value of '3' indicates to process this initial payment plus two further future payments at the intervals indicated with the OnBillFrequency. If no value is provided for this field, the payments will continue to be processed indefinitely The URL that will be used by ematters to send an XML string to each time a transaction is processed, excluding the initial transaction. This value is mandatory if OnBillAutoUpdate = YES This field must be provided if OnBill is YES. Specifies if the recurring transaction is to be processed every x days, or on the x day of the month, e.g. every 14 days, 16 th of each month. For every x days, use FRE. For a specific day of the month, use OAD Allows a grouping of transactions within Merchant Desk. Used for reporting only - does not affect banking. This can only be used where you have set up a sub merchant with your ematters account Unique identifier for the transaction, which provides an audit trail from the ematters system to your own system. Each transaction submitted to the ematters Merchant system must have a different UID. When a transaction is approved, the UID is locked and no further transactions with that UID will be approved on that day We recommend not using special characters for this field. This is an optional field. Links the transaction with the list of Category Codes you have created in Merchant Desk Numeric 3 FRE or OAD Alphanumeric OAD Numeric 02 EVENT01 ABC Page 10 of 59

11 Name Description Format Example Action Instructs the ematters gateway how to handle this request. Possible values are: Process Refund Pre-auth Complete Process OUTPUT FIELDS Name Description Format Example emattersrcode The bank response code Numeric 08 emattersuid The UID from the input value Numeric emattersamount The payment amount from the input value Numeric emattersauthcode The bank authorization code. Numeric ematterscardtype The type of credit card used VISA ematterstrxnreference emattersresponsetext emattersmainid The ematters Transaction Reference. Used for all future XML queries The ematters response in readable format Unique ematters transaction ID for retrieving the transaction through XML for Complete and Search Numeric TRANSACTION APPROVED 283F8CCEAA7F4685CA2 574A8003D91C SAMPLE - PAYMENT XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <readers>mel0036</readers> <password>abc123</password> <Name>John Doe</Name> < >John.doe@eMatters.com.au</ > <CreditCardHolderName>John Doe</CreditCardHolderName> <CreditCardNumber> </CreditCardNumber> <CreditCardExpiryMonth>09</CreditCardExpiryMonth> <CreditCardExpiryYear>15</CreditCardExpiryYear> <CVV>987</CVV> <UID>001</UID> <Category>02</Category> <IPAddress> </IPAddress> Page 11 of 59

12 <FinalPrice>10.99</FinalPrice> <Action>Process</Action> </ematters> Response <emattersresponse> <emattersrcode>08</emattersrcode> <emattersuid>001</emattersuid> <emattersamount>10.99</emattersamount> <emattersauthcode> </emattersauthcode> <ematterscardtype>visa</ematterscardtype> <ematterstrxnreference> </ematterstrxnreference> <emattersmainid> </emattersmainid> </emattersresponse> SAMPLE - REFUND XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <readers>mel0036</readers> <password>abc123</password> <Name>John Doe</Name> < >John.doe@eMatters.com.au</ > <CreditCardHolderName>John Doe</CreditCardHolderName> <CreditCardNumber> </CreditCardNumber> <CreditCardExpiryMonth>04</CreditCardExpiryMonth> <CreditCardExpiryYear>09</CreditCardExpiryYear> <CVV>987</CVV> <UID>001</UID> <IPAddress> </IPAddress> <FinalPrice>10.99</FinalPrice> <Action>Refund</Action> </ematters> Response <emattersresponse> <emattersrcode>08</emattersrcode> <emattersuid>001</emattersuid> <emattersamount>10.99</emattersamount> Page 12 of 59

13 <emattersauthcode> </emattersauthcode> <ematterstrxnreference> </ematterstrxnreference> <emattersmainid> </emattersmainid> </emattersresponse> Page 13 of 59

14 4.2 PROCESS AND COMPLETE A PRE-AUTHORISATION Pre-authorisations can only be completed where the merchant bank allows this function. Where a pre-authorisation is processed, this will remain against the cardholder's account for four to 10 days, depending on the issuing bank. Once a pre-authorisation has been processed, it cannot be deleted PARAMETERS Name Description Format Example password readers Name CreditCardHolderName CreditCardNumber CreditCardExpiryMonth CreditCardExpiryYear UID FinalPrice ematterspreauthcode The Posting password as stored in the System Settings in Merchant Desk. This is NOT your login password This value is provided to you by ematters and will always correspond with your Merchant ID (except where you have multiple accounts). If must be entered exactly as shown in the documentation. Failure to include this accurately will result in failed transactions The name shown on the receipt and also in Merchant Desk ABC123 MEL0036 John Citizen Customer's address buyer@xyz.com.au Full name of the cardholder Mr J Citizen Full credit card number. Can be entered in the following formats: Two digit expiry month Integer Two or four digit expiry year Integer 12 or 2012 Unique identifier for the transaction, which provides an audit trail from the ematters system to your own system. Each transaction submitted to the ematters Merchant system must have a different UID. When a transaction is approved, the UID is locked and no further transactions with that UID will be approved on that day We recommend not using special characters for this field. This field is only used where the Action = PreAuth. Contains the amount of the transaction in dollars and cents. No dollar sign required This field is only used where the Action = Complete. The pre-authorisation code that was previously issued Alphanumeric ABC Numeric Numeric IPAddress The IP address of your customer's Page 14 of 59

15 Name Description Format Example computer. Used for blocking transactions from high-risk countries and for following up fraud Action Instructs the ematters gateway how to handle this request. Possible values are: PreAuth Complete PreAuth OUTPUT FIELDS Name Description Format Example emattersrcode The bank response code Numeric 08 emattersuid The UID from the input value Numeric emattersamount ematterspreauthcode emattersauthcode ematterstrxnreference emattersmainid The payment amount from the input value The pre-authorisation code issued by the bank. This field will be included in the result where the Action for the request was PreAuth The authorization code issued by the bank. This field will be included in the result where the Action for the request was Complete The ematters Transaction Reference. Used for all future XML queries Unique ematters transaction ID for retrieving the transaction through XML for Complete and Search Numeric Numeric Numeric Numeric F8CCEAA7F4685CA2 574A8003D91C SAMPLE - PRE-AUTH XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <readers>mel0036</readers> <password>abc123</password> <Name>John Doe</Name> < >John.doe@eMatters.com.au</ > <CreditCardHolderName>John Doe</CreditCardHolderName> <CreditCardNumber> </CreditCardNumber> <CreditCardExpiryMonth>04</CreditCardExpiryMonth> <CreditCardExpiryYear>09</CreditCardExpiryYear> <UID>001</UID> Page 15 of 59

16 <IPAddress> </IPAddress> <FinalPrice>10.99</FinalPrice> <Action>PreAuth</Action> </ematters> Response <emattersresponse> <emattersrcode>208</emattersrcode> <emattersuid>001</emattersuid> <emattersamount>10.99</emattersamount> <ematterspreauthcode> </ematterspreauthcode> <ematterstrxnreference> </ematterstrxnreference> <emattersmainid> </emattersmainid> </emattersresponse> SAMPLE - PRE-AUTH COMPLETION XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <readers>mel0036</readers> <password>abc123</password> <Name>John Doe</Name> < >John.doe@eMatters.com.au</ > <CreditCardHolderName>John Doe</CreditCardHolderName> <CreditCardNumber> </CreditCardNumber> <CreditCardExpiryMonth>04</CreditCardExpiryMonth> <CreditCardExpiryYear>09</CreditCardExpiryYear> <ematterspreauthcode> </ematterspreauthcode> <UID>001</UID> <IPAddress> </IPAddress> <FinalPrice>10.99</FinalPrice> <Action>Complete</Action> </ematters> Response <emattersresponse> <emattersrcode>08</emattersrcode> <emattersuid>001</emattersuid> Page 16 of 59

17 <emattersamount>10.99</emattersamount> <emattersauthcode> </emattersauthcode> <ematterstrxnreference> </ematterstrxnreference> <emattersmainid> </emattersmainid> 4.3 PROCESSING REQUESTS WITHOUT CREDIT CARD NUMBER There are two types of transactions that may be processed without supplying a credit card number - Refund and Pre-authorisation Completion. These can only be done when related to a previous transaction where the credit card number was provided PARAMETERS Name Description Format Example readers This value is provided to you by ematters and will always correspond with your Merchant ID (except where you have multiple accounts). If must be entered exactly as shown in the documentation pin This field is only used where Action = Refund. The Search PIN as shown in the Merchant Desk, Account Management, Profile document. This is your secure PIN and must not be divulged to anyone password UID Trxn The Posting password as stored in the System Settings in Merchant Desk. This is NOT your login password Unique identifier for the transaction, which provides an audit trail from the ematters system to your own system. Each transaction submitted to the ematters Merchant system must have a different UID. When a transaction is approved, the UID is locked and no further transactions with that UID will be approved on that day We recommend not using special characters for this field. Unique ematters transaction ID. This will be the emattersmainid that was provided in the response for the original pre-authorisation transaction RefundAmount This field is only used where Action = Refund. Contains the amount of the refund transaction in dollars and cents. No dollar sign required CompleteAmount This field is only used where Action = Complete. Action Contains the amount that the preauthorisation is being completed for in dollars and cents. No dollar sign required Instructs the ematters gateway how to handle this request. Possible values are: Refund Complete MEL Alphanumer ic ABC123 ABC Numeric Numeric F8CCEAA7F4685CA 2574A8003D91C9 PreAuth Page 17 of 59

18 4.3.2 OUTPUT FIELDS Name Description Format Example emattersrcode The bank response code Numeric 08 emattersuid The UID from the input value Numeric emattersamount The amount from the input value Numeric emattersauthcode The authorization code issued by the bank Numeric SAMPLE - REFUND (WITHOUT CREDIT CARD NUMBER) XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <readers>mel0036</readers> <pin>939494</pin> <password>abc123</password> <UID>001</UID> <Trxn> </Trxn> <RefundAmount>10.99</RefundAmount> <Action>RefundTrans</Action> </ematters> Note: In the above example the field Trxn should be the emattersmainid reference given in the original purchase response Response <emattersresponse> <emattersrcode>08</emattersrcode> <emattersuid>001</emattersuid> <emattersamount>10.99</emattersamount> <emattersauthcode> </emattersauthcode> </emattersresponse> Page 18 of 59

19 4.3.4 SAMPLE - PRE-AUTH COMPLETION (WITHOUT CREDIT CARD NUMBER) XML POSTING STRING: Request <?xml version="1.0" encoding="iso "?> <ematters> <Readers>MEL0036</Readers> <Password>ABC123</Password> <UID>001</UID> <Trxn> </Trxn> <CompleteAmount>1.99</CompleteAmount> <Action>Complete</Action> </ematters> Note: In the above example the field Trxn should be the emattersmainid reference given in the original purchase response Response <emattersresponse> <emattersrcode>08</emattersrcode> <emattersuid>001</emattersuid> <emattersamount>10.99</emattersamount> <emattersauthcode> </emattersauthcode> </emattersresponse> Page 19 of 59

20 4.4 TRANSACTION SEARCH This enables your system to search for a specific transaction in ematters. It is useful if you wish to give your operators access to query our system, but do not want them to login to the Merchant Desk system. NOTE: Only transactions processed within the last 7 days can be found using this method. All prior transactions must be manually located within the merchant desk PARAMETERS Name Description Format Example UID readers pin The UID of the transaction to search for This value is provided to you by ematters and will always correspond with your Merchant ID (except where you have multiple accounts). If must be entered exactly as shown in the documentation The Search PIN as shown in the Merchant Desk, Account Management, Profile document. This is your secure PIN and must not be divulged to anyone MEL OUTPUT FIELDS Name Description Format Example name The name of the customer John Citizen response The bank response code Numeric 08 date The date and time of the transaction Date/time dd/mm/yy yy hh:mm AM/PM 10/03/ :01:45 AM The tags <name>, <response> and <date> will be repeated for as many transactions that are found that match the criteria SAMPLE XML POSTING STRING: Request <?xml version="1.0"?> <findtrans> <uid>003</uid> <readers>mel0658</readers> <pin>12345</pin> </findtrans> Page 20 of 59

21 Response <?xml version='1.0' encoding='iso '?> <findresponse> <name>john Smith</name> <response>51</response> <date>11/11/2004 8:35:37 PM</date> <name>james Doe</name> <response>08</response> <date>11/11/2004 8:57:09 PM</date> </findresponse> Page 21 of 59

22 4.5 QUERY OUR BANK CONNECTIONS This feature allows you to query our servers and determine if we are experiencing any issues with our connections with our banks. You can optionally do this before each transaction if you redirect your customer to us, or on a regular basis. If you are using our Extended or Direct Edition, each connection check incurs a fee (refer to ematters for further details). It is free in the Enterprise Version PARAMETERS Name Description Format Example Readers This value is provided to you by ematters and will always correspond with your Merchant ID (except where you have multiple accounts). If must be entered exactly as shown in the documentation MEL0036 Bank The abbreviation for the bank you want to check CBA OUTPUT FIELDS Name Description Format Example Bank The abbreviation for the bank you are checking Status The current status of the bank Operational CBA Using this method, it is possible to query individual connections into each bank. For example, our dual CBA connections can be queried by sending CBA as the bank in the first instance, followed by CBB for the second check SAMPLE XML POSTING STRING: Request <?xml version="1.0"?> <ematters> <Readers>MEL0900</Readers> <Bank>CBA</Bank> </ematters> Response <?xml version="1.0"?> <ematters> <Bank>CBA</Bank> <Status>Operational</Status> </ematters> Page 22 of 59

23 5 ONBILL RECURRING TRANSACTIONS Part of the core ematters system is our OnBill recurring system. All credit cards can be set, either at the time of purchase or before, or even afterwards, to be charged on a regular monthly basis. This is useful if you have a membership or subscription service. An important feature is where we update your database after EVERY transaction. So as soon as the transaction is completed each day, your database will receive an XML feed with the updates, allowing you to track your customer payment history as it happens, automatically and simply. 5.1 AUTOMATED BILL RESPONSE Each time we process an OnBill Transaction, we can send an automated response back to your server/database to allow you to update the member record. For this to operate, you MUST have previously set the field <OnBillReturnURL> to a script on your server capable of accepting XML tags. This script would read the XML that we send and then update the customer record (refer to Section 4.1 Processing a Transaction above for further details) OUTPUT FIELDS Name Description Format Example uid The UID of the transaction that has been rebilled readers The code supplied by ematters MEL0036 rcode The response code for the transaction Integer 08 authcode The bank authorization code. This may be blank for non-approved transactions Integer SAMPLE XML POSTING STRING: Response <?xml version="1.0"?> <onbill> <uid>003</uid> <readers>mel0658</readers> <rcode>08</rcode> <authcode>199202</authcode> </onbill> Page 23 of 59

24 5.2 ONBILL MASTERFILE MAINTENANCE We can accept an XML string from your web server/application to maintain various fields within the OnBill Recurring system. It is vital that the field values are checked before you send them to us, as it is possible that you could edit a Recurring entry that will never be billed. The following fields can be amended: Field Name NextProcess FinalPrice CreditCardExpiryMonth CreditCardExpiryYear StopFlag Description The date the next payment will be processed. Must be provided in date format (dd/mm/yyyy). The date must be tomorrow or later The amount to be charged. Must be provided in dollars and cents without any leading spaces or dollar sign (e.g ) Two digit month value Two digit year value Indicates that you want to stop the processing of this transaction in the future. If you submit a value of YES, processing will be stopped. If you submit a value of NO, processing will be reactivated Enables you to change the address recorded for the customer Changes to any other fields can only be done through the Merchant Desk system PARAMETERS Name Description Format Example Action UID Readers pin Fieldname Specifies that a CHANGE action is to be performed The unique ID that is stored for each customer record. This will identify the customer for which the recurring payments are to be updated Change Your ematters login MEL0036 Your ematters PIN Specify which field you want to change within the OnBill system. The following fields can be amended: - NextProcess - FinalPrice - CreditCardExpiryMonth - CreditCardExpiryYear - StopFlag FinalPrice OUTPUT FIELDS Name Description Format Example name The name of the customer that was updated John Citizen FieldName The field that has been amended (from the input request) NextProcess Page 24 of 59

25 Name Description Format Example FieldValue Result The new value that has been saved (from the input request) Where the update was successful, a value of Saved will exist. Where the update was not successful, a value of Error - Result Not Saved will exist 01/05/2012 Saved SAMPLE Request XML POSTING STRING: <?xml version="1.0"?> <ematters> <Action>Change</Action> <UID>16</UID> <Readers>MEL0761</Readers> <PIN>39393</PIN> <Fieldname>NextProcess</Fieldname> <Fieldvalue>01/02/2002</Fieldvalue> </ematters> Response <ematters> <name>john Smith</name> <FieldName>NextProcess</FieldName> <FieldValue>01/02/2004</FieldValue> <Result>Saved</Result> </ematters> Page 25 of 59

26 6 EMATTERS API (HTTPS POST) YOU COLLECT THE DETAILS The fields are listed below, in no particular order of importance. Many fields are mandatory and MUST be sent with every transaction. Do not send EXTRA fields or the gateway will not process the transaction. If you receive an error Page Cannot Be Found it signifies an error in one of your field names or submit button. All the OnBill fields from the above XML section can be used in this method. Use this string to post the following fields to: MANDATORY FIELDS Name Description Format Example Click A system field that is required for our Merchant server to process your transaction Click= 0 Bank Instructs ematters as to which bank to use the primary (or if MultiBank is set to No ) the only bank to process against. StGeorge CreditCardExpiryMonth The 2 digit month. Numeric 04 CreditCardExpiryYear The 2 of 4 digit year Numeric 2005 or 05 CreditCardHolderName The full name of the CardHolder Mr J Doe CreditCardNumber The full card number in one of the following formats Can be any card which your account accepts, including Visa, Mastercard, Amex, Diners, JCB and ematters Voucher. CVV The three digits on the back of the card Numeric 584 FinalPrice Contains the amount of the transaction in dollars and cents. The $ sign is not required. Decimal MerchantID Contains the ematters Merchant Number as assigned when the application was submitted Numeric 36 Page 26 of 59

27 Name Description Format Example Mode Indicates if the transactions being processed are to be billed to the merchant as chargeable transactions. Please note, that in any mode, the transactions are still sent to the bank for processing. If you wish to process test transactions, please use the card numbers listed below. Live or Test Live These test card numbers only work in TEST mode. Approved Declined The expiry dates must be valid (but can be any valid date) Name The name shown on the receipt and also in the Merchant Desk. It is purely cosmetic and is optional. It is recommended because it makes searching in the Merchant Desk far simpler. John Doe NewMerchantID The merchant ID issued by the bank, supporting the newest version of our processing gateway. Usually only required by CBA and only use this if requested by ematters. Numeric Platform Instructs the gateway how to format the response back to your site. It depends upon the ReturnHTTP value. Intermediary-ASP Readers This is supplied by ematters and will always correspond with your MerchantID (except if you have multiple accounts). It must be entered exactly as shown in the documentation. Failure to include this accurately will result in failed transactions. MEL0036 Page 27 of 59

28 Name Description Format Example Return Is the internet address of the admin person at the Merchant (belongs to that of the Company). ReturnHTTP The address where the next sequence of events is executed. Usually a URL on your server if you are calling from a web server. If you are calling from your own server application, it is recommended to use the asterisk symbol in this field in conjunction with Platform variable shown below. Must contain one of the following values:- au/store/results.asp? or [ au/store/results.asp Value Result - Displays a standard EFTPOS receipt on the user s terminal. Good for donations or simple payment pages. Some configurations need to have a [ at the start of the return url. * Displays the response on the screen, dependant upon the Platform value URL Sends the user to that URL, with parameters after the URL providing the response code and UID. Send A flag to indicate if the cardholder is to receive a copy of the EFTPOS receipt as generated by ematters. Yes Submit For web processing, this is required to be in the format as shown below. It is the standard submit button. <input TYPE="SUBMIT" VALUE="SUBMIT"> UID Our Unique Identifier, providing an audit trail from our system to your system. This number must be fully numeric, must be no longer than 13 digits and is created by your system. Each transaction that is submitted to the ematters Merchant System must have a different UID. When a transaction is approved,.the UID is locked and no further transactions with that UID will be approved on that day. Numeric Page 28 of 59

29 6.2 OPTIONAL FIELDS If used, these fields must contain a value. Name Description Format Example ABN Category Displays on the receipt after the company name. Must be in the format of ABN xx xxx xxx xxx Links the transaction with the list of Category Codes you have created on the website. ABN Numeric 01 CompanyName Contains the Company Name that appears on the receipt that is ed (optionally) to the end user. Acme Australia Pty Ltd CustomerCellPhone Allows ematters to use our SMS Gateway to send an SMS to your customer during the transaction. Numeric CustomerCountry Determines which format to use for the delivery of the SMS message. Australia The address of the Customer. If Send is No, then this is optional. If Send is Yes, then this field is required. buyer@xyz.com IPAddress The IP Address of your customer s workstation. Used for blocking transactions from HighRisk countries and for following up fraud IPBankCheck Instruct the ematters gateway to compare the IP Address of the transaction with the Country of origin of the bank. If it matches, the transaction proceeds as normal. If it does not match, the transaction fails. Yes or No MerchantCellPhone Specifies the Cell phone number to which we send a notification. It is for Merchant usage only. Mandatory if SMSGatewayEnabled is present. Numeric OnBill Specifies that this transaction is to be lodged with the ematters OnBill Recurring Transaction System, repeating the processing at regular intervals. YES OnBillAmount The price that each FUTURE transaction is charged. Decimal OnBillAutoUpdate Specifies if we are to send an XML update after each recurring transaction. This is needed if you want to update your database with each subsequent transaction. Must also include OnBillReturnURL as shown below. YES OnBillDate The date of the FIRST recurring transaction. Only use this in special circumstances, where you want to charge the client every 30 days from their date of purchase, but wish to give them 3 months free. If today was 01/01/2005, then OnBillDate would be set to 01/04/2005. Then, depending on the other flags, we would process this on the 1 st of each month from April Date 01/05/2009 Page 29 of 59

30 Name Description Format Example onwards. OnBillFrequency OnBillQty Specifies the number of days between processing of this transaction. Must be present if OnBill field is set. If OnBillType=FRE, then this denotes that the transaction will be processed every 30 days. If OnBillType=OAD, then this transaction will be re-processed on the 30 th of each month (assuming the value of this field is 30). Specified the TOTAL number of instalments to process. A value of 3 indicates our system to take this payment, then 2 more at the intervals as shown above. Numeric 30 Numeric 3 OnBillReturnURL The URL we will send an XML string to each time a transaction is made AFTER the initial one. g.cfm OnBillType Specifies if this recurring transaction is to be processed every x days, or on the x day of the month. (i.e. every 14 days, or on the 15 th of each month) OAD (for OnADay) or FRE (Frequency) Principal If Send is set to yes, then this value sets the From name on the . If this is left blank, all s will be sent from payments@ematters.com.au. payments@acme.com.a u SMSGatewayEnabled Allows notification of a sale through the ematters SMS Gateway. Yes SubMerchant Allows a break-down of transactions within the Merchant Desk. Used for reporting only, does not effect banking. Can be anything you require. SOCG101 Page 30 of 59

31 6.3 SAMPLE HTTPS FORM <html> <head> <title>posted Payment Page</title> </head> <body> <form METHOD="post" ACTION=" <input type="hidden" name=" Click" value="0"> <input type="hidden" name="return " > <input type="hidden" name="returnhttp" value="*"> <input type="hidden" name="merchantid" value="36"> <input type="hidden" name="send " value="yes"> <input type="hidden" name="bank" value="national"> <input type="hidden" name="platform" value="plaintext"> <input type="hidden" name="mode" value="live"> <input type="hidden" name="readers" value="mel0036"> <input type="hidden" name="principal" <p>unique ID Number <input name="uid" value="1" size="20"></p> <p>customer Name <input NAME="Name" VALUE="John Doe" SIZE="20" MAXLENGTH="40"></p> <p>customer <input NAME=" " SIZE="25" MAXLENGTH="40"></p> <p>c V V <input type="text" name="cvv" size="4" value="123"></p> <p>card Number <input NAME="CreditCardNumber" VALUE=" " SIZE="24" MAXLENGTH="22"></p> <p>expiry <select NAME="CreditCardExpiryMonth" size="1"> <option>01 </option> <option>02 </option> <option>03 </option> <option>04 </option> <option>05 </option> <option>06 </option> <option>07 </option> <option>08 </option> <option>09 </option> <option>10 </option> <option>11 </option> <option>12</option> </select> / <select NAME="CreditCardExpiryYear" size="1"> <option value="2008">2008</option> <option value="2009">2009</option> <option value="2010">2010</option> <option value="2011">2011</option> <option value="2012">2012</option> </select> </p> <p>cardholder name <font FACE="Verdana"><input NAME="CreditCardHolderName" SIZE="20" MAXLENGTH="40"></font></p> <p>total Price <input NAME="FinalPrice" VALUE="$1.00" SIZE="10" MAXLENGTH="10"></p> <p>.<input TYPE="SUBMIT" VALUE="SUBMIT"></p> </p> </form> </body> </html> Page 31 of 59

32 7 MOBILE PHONE PAYMENT PAGE The Mobile Phone Payment Page provides a fully integrated payment solution that enables your customers to make a payment to you from their web enabled smart phone. Either allow them to browse from your website, or send them a quick with an embedded dynamic link. Our ematters.mobi solution delivers a custom payment page, with your Company Details clearly shown to your customer. Note: Please consult with ematters prior to using the Mobile Phone Payment Page in order to confirm your account profile is set correctly. The Mobile Phone Payment Page URL is A number of additional input tags are required to hold the information that the gateway requires and to customise the page to your reader. Refer to the Shared Payment Page section below for further details. Page 32 of 59

33 8 EMATTERS SHARED PAYMENT PAGE - REDIRECT VIA HTTP GET The Shared Payment page enables you to process payments through a web site without the need for you to have your own SSL certificate. ematters takes care of the collection and security of all card details. Note: Please consult with ematters prior to using the Shared Payment Page in order to confirm your account profile is set correctly. The base URL for the Shared Payment page is The form requires a number of hidden input tags to hold the information that the gateway requires. These are detailed in the next section below. An example of the Shared Payment Page is as follows: If the Extra Merchant Information link is selected in the Merchant Details, the following dialog will be displayed: Page 33 of 59

34 The value of the transaction can be displayed in another currency by clicking on one of the country symbols beside the Total Price field. Your logo can be added to the Shared Payment page if you require this. The logo must be provided to your ematters Consultant. 8.1 PARAMETERS Input Field Name Description Required Format &a= Your ematters account code Yes MEL0036 &p= &u= Price, in the format required by your currency. For example, AUD requires the format to be dollars and cents (25.50), whereas YEN requires just the whole number (126). You can supply the price with the parameter, e.g. p= If you want the customer to enter the price, use p=0 UID (unique reference number). If you provide u=0, ematters will create a unique identifier for you. Yes or 125 No Page 34 of 59

35 Input Field Name Description Required Format If the parameter is left out, the customer can enter their own UID. We will not approve the same UID in a 24 hour period. &cn= Customer name. Where more than one name is provided, separate each part of the name with + (e.g. Bill+Jones) No Bill+Jones &e= Customer No bill@bigpond.com &r= &t=1 &s= &c= &m=t URL to return to after the transaction has been processed Template number. When using the default Shared Payment page, use 1. If you have provided your own logo to ematters to display on the page, you will use the template number provided to you for this parameter Allows a grouping of transactions within Merchant Desk. Used for reporting only - does not affect banking. This can only be used where you have set up a sub merchant with your ematters account. Default will be 001 if no value provided Category Code. Links the transaction with the list of Category Codes you have created in Merchant Desk This is used for testing only and pre-fills the form with test data. NOT TO BE USED IN A LIVE SITE Yes No 1 No 001 No 03 &ob=yes Turns on OnBill for this transaction No YES &oba= &obt= &obd= &obf= &obq= &obup= &obr= The amount to be charged for all future amounts. If this parameter is not present, the amount defaults to the same as the p parameter (amount of the transaction) This is set to either OAD (on a day) or FRE (frequency). See XML guide for further details This is the next date that this transaction is to be processed If obt is set to OAD, then this is the day number of each month that the charge is to be made. If obt is set to FRE, this is the number of days between each charge This sets the number of charges to be made, including the first one. Use 9990 to make the arrangement unending This turns on the XML AutoUpdate for all future transactions. This can only be used if your system is capable of receiving XML data from our server on a daily basis. See the SML section for more details This is the URL to which our AutoUpdates are sent each day. We send an after each transaction, No Only use when ob=yes Only use when ob=yes Only use when ob=yes Only use when ob=yes Only use when ob=yes Only use when ob=yes Only use when ob=yes u/response.psp? t (use to populate with test data) FRE 12/09/ YES u/dailyupdate.asp Page 35 of 59

36 Input Field Name Description Required Format and also a daily report regardless of the setting here Page 36 of 59

37 9 EMATTERS SHARED PAYMENT PAGE - REDIRECT VIA HTTP POST The Shared Payment page is for use when you do not have your own SSL certificate. In the HTTP Post version, you use 'Method="post"' to deliver data to ematters. ematters will still collect the sensitive credit card details, however no account data is transferred via the URL. A sample HTML page is shown below, using a dummy account code of MEL0036. You will replace the value MEL0036 with your own account details, along with the Return URL (making it one to your own site). Note: You must have your Merchant Desk Profile configured correctly to use this feature, otherwise transactions may not be processed correctly. Please contact ematters via Help Desk to confirm your setup. Page 37 of 59

38 10 EMATTERS DEDICATED PAYMENT PAGE - WE COLLECT THE CARD DETAILS The Dedicated Payment Page is for use when you do not have your own SSL certificate but still want the payment page to look like your main website. Our consultants will modify our template to match your main website look and feel as closely as possible. The look and feel of this page is completely up to you and we work together with your designers to make sure it suits your requirements. If you update your own site, we can rework the payment page to reflect those changes. This service carries an integration fee to cover the time for our developers to implement and maintain this solution. We provide a cost estimate prior to commencing your customization, as no two pages are the same. You could expect to pay between $295 and $1,900 depending on your level of customization. Page 38 of 59

39 11 EMATTERS BILLSMART - VARIABLE RECHARGE AMOUNT ematters BillSmart is a way of providing a variable amount and variable timed re-bill. Firstly you need to create a customer record in our BillSmart database. This can be done during the successful approval of a transaction from within the ematters payment gateway. As soon as the customer is created, it is ready to re-bill. You simply send the customer number and the amount from your server to ours when you want the transaction billed. We re-create the transaction at ematters and process - all in real time. The second method of adding transactions to our BillSmart database is via our XML Update script XML ADD TO BILLSMART PARAMETERS Name Description Format Example Action UID Readers Name (Mandatory) Specifies what action is to be performed Change The unique ID that is stored for each customer record. This will identify the customer for which the recurring payments are to be updated This UID also becomes the Token you will call on future transactions Your ematters login MEL0036 The name shown on the receipt and also in Merchant Desk John Citizen Customer's address buyer@xyz.com.au CreditCardHolderName CreditCardNumber CreditCardExpiryMonth CreditCardExpiryYear CVV Full name of the cardholder Mr J Citizen Full credit card number. Can be entered in the following formats: Two digit expiry month Integer 11 Two digit expiry year Integer 12 Card Verification Value - three digits on the back of a Visa/Mastercard/ Diners or four digits on the front of an AMEX Integer SAMPLE Request XML POSTING STRING: <?xml version="1.0" encoding="iso "?> Page 39 of 59

40 <ematters> <Action>Add</Action> <UID>ACME001</UID> <Readers>MEL0761</Readers> <CustomerName>John Doe</CustomerName> <CreditCardNumber> </CreditCardNumber> <CreditCardExpiryMonth>09</CreditCardExpiryMonth> <CreditCardExpiryYear>05</CreditCardExpiryYear> <CreditCardHolderName>J Doe</CreditCardHolderName> <CVV>559</CVV> </ematters> Response Successful response <ematters> <response>01</response> <text>ok</text> </ematters> Response where UID is not unique <ematters> <response>07</response> <text>non Unique UID</text> </ematters> Response where the provided credit card expiry date is in the past <ematters> <response>04</response> <text>expired Card</text> </ematters> Response where no credit card details were provided <ematters> <response>05</response> <text>no CC Details</text> </ematters> Response where invalid credit card details were provided <ematters> Page 40 of 59