GATEWAY FREEDOM INTEGRATION GUIDE

Transcription

1 Payment solutions for online commerce GATEWAY FREEDOM INTEGRATION GUIDE Copyright PayPoint.net 2010 This document contains the proprietary information of PayPoint.net and may not be reproduced in any form or disclosed to any third party without the expressed written permission of a duly authorised representative of PayPoint.net Limited. Registered in England No: VAT Reg. No:

2 PayPoint.net Gateway Freedom v th October 2010 Table of Contents 1 Introduction Protocols XMLRPC SOAP Realtime Transactions Realtime Transaction Request Parameters Realtime Transaction Response Parameters Additional Response Parameters Example XMLRPC Request Example XMLRPC Response Example SOAP Request Example SOAP Response Refund Transactions Refund Transaction Request Parameters Refund Transaction Response Parameters Example XMLRPC Refund Request Example XMLRPC Refund Response Example SOAP Refund Request Example SOAP Refund Response Placing Deferred Transactions Releasing Deferred Transactions Release Request Parameters Cancelling Deferred Transactions Performing Repeat Transactions Repeat Request Parameters Using PayPoint.net s Scheduler repeat_callback Deleting Scheduled Transactions Optional Parameters Transaction Reports Transaction Report Parameters Testing Test Card Numbers test_status dups default_cv2avs PayPoint.net Custom Hosted Payment Pages Customising Your Template Uploading Your Template Referencing Your Template Customising the err_template Customising Payment Page Error Messages Digest Checking Mandating CV Page 2 of 23

3 1 Introduction The Web Freedom product allows you to use the customisable hosted payment pages, the API or both. Some merchants like to take the initial payment on the hosted payment pages and then use the API for tokenised repeats and refunds, as there are fewer PCI compliance implications. The first part of this integration guide explains the API and the second part is a supplement to the Gateway Hosted integration guide explaining how to customise the payment page. If you want to use the hosted payment pages you will need to download the Gateway Hosted integration guide which includes the basic concept and further optional parameters. 2 Protocols 2.1 XMLRPC It's a technical standard specification and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet. It's remote procedure calling using HTTP as the transport and XML as the encoding. XML-RPC is designed to be as simple as possible, while allowing complex data structures to be transmitted processed and returned. Details of the XML-RPC protocol can be found at Example code donated by merchants/developers can be found here: SOAP SOAP stands for "Simple Object Access Protocol" and is a lightweight XML-based communications protocol designed for the exchange of information in a platform-independent, distributed environment. PayPoint.net leverages the RPC (remote procedure call) capabilities of SOAP to provide a secure remote interface to our transactional network from within your own code, as though you were making a call to a local method or function. SOAP Services are defined using the WSDL (Web Services Definition Language) and are accessible via a URL which is known as a SOAP Endpoint. Endpoint: WSDL: Example code donated by merchants/developers can be found here: General resources for SOAP developers: Java Apache SOAP: Perl SOAP Lite: PHP SOAP Toolkit: Page 3 of 23

4 3 Realtime Transactions 3.1 Realtime Transaction Request Parameters Method Name: SECVPN.validateCardFull PARAMETER EXAMPLE DEFINITION mid vpn_pswd trans_id TRAN0001 ip This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). A unique transaction identifier created by yourself. This can be used to refer to a transaction at a later date (to refund it for example). The IP address that the cardholders machine is presenting to the internet. name Mr Cardholder The cardholders name as it is on their card. card_number amount expiry_date 0115 issue_number 1 start_date 0109 order shipping billing options prod=funny_book,item_amount=25.00x1;pr od=sad_book,item_amount=12.50x2 name=fred Bloggs,company=Online Shop Ltd,addr_1=Dotcom House,addr_2=London Road,city=Townville,state=Countyshire,post _code=ab1 C23,tel= ,fax= , =somebody@paypoint.net,url = name=fred Bloggs,company=Online Shop Ltd,addr_1=Dotcom House,addr_2=London Road,city=Townville,state=Countyshire,post _code=ab1 C23,tel= ,fax= , =somebody@paypoint.net,url = test_status=true,dups=false,card_type=visa,cv2=123 The card number (this should contain no spaces or hyphens). The example card number show to the left is a test Visa card which can be used during development. Any valid expiry date which is in the future can be used with this card number. The amount for the transaction. This should contain no currency symbols or formatting (for example do not send an amount with a comma in). The expiry date on the card. Should be formatted either as mm/yy or mmyy. The issue number on the card. This only applies to Maestro or solo cards. If the card in use does not have an issue number then an empty string should be passed in. The start date on the card. If the card does not have a start date then an empty string should used. Used to submit order details relevant to this transaction. Used to submit shipping address details relevant to this transaction. Used to submit billing address details relevant to this transaction. Used to submit optional parameters which are used to alter the behaviour of this transaction. Page 4 of 23

5 3.2 Realtime Transaction Response Parameters The parameters below are the commonly returned parameters for a simple test payment request. PARAMETER EXAMPLE DEFINITION valid true This is true or false and indicates the acceptance or not of the card details. trans_id code TRAN0001 A We send you back the same trans_id that you sent us with your mandatory parameters so that you can update your system appropriately. A short code giving extensive details of failure states. This is the parameter that should be used to programmatically determine whether or not a particular transaction was authorised. See Figure 1 below for possible values. auth_code 9999 This is the authorisation code obtained from the bank for this transaction. This is only returned if valid=true. For a transaction sent when test_status=true, the auth_code will always be message TEST AUTH A message to give you more information. This should NOT be displayed to the cardholder. amount This is the amount actually authorised by the bank. test_status true Returns the test flag you sent in your request. Only returned if you send a test_status parameter. Figure 1: Possible code values and their meanings Code A N C F P:A P:X P:P P:S P:E P:I P:C P:T P:N P:M P:B P:D P:V P:R P:# Definition Transaction authorised by bank. auth_code available as bank reference Transaction not authorised. Failure message text available to merchant Communication problem. Trying again later may well work The PayPoint.net system has detected a fraud condition and rejected the transaction. The message field will contain more details. Pre-bank checks. Amount not supplied or invalid Pre-bank checks. Not all mandatory parameters supplied Pre-bank checks. Same payment presented twice Pre-bank checks. Start date invalid Pre-bank checks. Expiry date invalid Pre-bank checks. Issue number invalid Pre-bank checks. Card number fails LUHN check (the card number is wrong) Pre-bank checks. Card type invalid - i.e. does not match card number prefix Pre-bank checks. Customer name not supplied Pre-bank checks. Merchant does not exist or not registered yet Pre-bank checks. Merchant account for card type does not exist Pre-bank checks. Merchant account for this currency does not exist Pre-bank checks. CV2 security code mandatory and not supplied / invalid Pre-bank checks. Transaction timed out awaiting a virtual circuit. Merchant may not have enough virtual circuits for the volume of business. Pre-bank checks. No MD5 hash / token key set up against account Note: Pre-auth checks can have several errors, e.g. P:NEC means the name, expiry date and card number fields are all invalid or not supplied. Page 5 of 23

6 3.3 Additional Response Parameters Below are some additional parameters you may receive in the response depending the contents of your request. PARAMETER EXAMPLE DEFINITION card_no 1111 Last 4 digits of the card number. Supplied if you sent repeat=true in the options field of your request. card_type Visa Card type. Supplied if you sent repeat=true in the options field of your request. currency customer EUR Mr Cardholder The currency of the transaction. Only supplied when a currency other than the default (GBP) is used. Cardholders name. Supplied if you sent repeat=true in the options field of your request. The Apacs approved text that is supplied as a result of the CV2 and AVS anti-fraud checks. There are five core values defined, these are: ALL MATCH All the data provided matched that which the card issuer had on record. SECURITY CODE MATCH ONLY Only the security code matched ADDRESS MATCH ONLY Only the address matched NO DATA MATCHES None of the data matched DATA NOT CHECKED The cv2avs system is unavailable or not supported by this card issuer. cv2avs ALL MATCH With these core codes an address is only understood to match if and only if both the address and the postcode match at the same time. This is a little strict for some people so the following codes have been introduced too: PARTIAL ADDRESS MATCH / POSTCODE The postcode matched but the address did not. PARTIAL ADDRESS MATCH / ADDRESS The address matched but the postcode did not. SECURITY CODE MATCH / POSTCODE The security code and postcodes matched but the address did not. SECURITY CODE MATCH / ADDRESS The security code and address matched but the postcode did not. expiry 0115 resp_code 5 Codes are only supplied when CV2 and/or Billing Address data is supplied in your request. Expiry date. Supplied if you sent repeat=true in the options field of your original request. This parameter is only returned when a transaction is declined and code=n. This is the bank's failure code for your information only, do not show it to the customer. 2 or 83 5 or Referral Not Authorised General error (retrying after 1 minute may succeed, depending on error) Page 6 of 23

7 3.4 Example XMLRPC Request <?xml version="1.0"?> <methodcall> <methodname>secvpn.validatecardfull</methodname> <params> <value><string></string></value> <value><string></string></value> <value><string>tran0001</string></value> <value><string> </string></value> <value><string>mr Cardholder </string></value> <value><string> </string></value> <value><string>50.00</string></value> <value><string>0115</string></value> <value><string>1</string></value> <value><string>0109</string></value> <value><string>prod=funny_book,item_amount=25.00x1;prod=sad_book,item_amount=12.50x2</string></value> <value><string></string></value> <value><string></string></value> <value><string>test_status=true,dups=false,card_type=visa,cv2=123</string></value> </params> </methodcall> 3.5 Example XMLRPC Response <?xml version="1.0" encoding="iso "?> <methodresponse> <params> <value>?valid=true&trans_id=trans_id&code=a&auth_code=9999&message=test AUTH&amount=10.51&test_status=true </value> </params> </methodresponse> Page 7 of 23

8 3.6 Example SOAP Request <soapenv:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soapenv=" xmlns:sec=" <soapenv:header/> <soapenv:body> <sec:validatecardfull soapenv:encodingstyle=" <mid xsi:type="xsd:string"></mid> <vpn_pswd xsi:type="xsd:string"></vpn_pswd> <trans_id xsi:type="xsd:string">tran0001</trans_id> <ip xsi:type="xsd:string"> </ip> <name xsi:type="xsd:string">mr Cardholder</name> <card_number xsi:type="xsd:string"> </card_number> <amount xsi:type="xsd:string">50.00</amount> <expiry_date xsi:type="xsd:string">0115</expiry_date> <issue_number xsi:type="xsd:string">1</issue_number> <start_date xsi:type="xsd:string">0109</start_date> <order xsi:type="xsd:string">prod=funny_book,item_amount=25.00x1;prod=sad_book,item_amount=12.50x2</order> <shipping xsi:type="xsd:string"></shipping> <billing xsi:type="xsd:string"></billing> <options xsi:type="xsd:string">test_status=true,dups=false,card_type=visa,cv2=123</options> </sec:validatecardfull> </soapenv:body> </soapenv:envelope> 3.7 Example SOAP Response <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <ns1:validatecardfullresponse soapenv:encodingstyle=" xmlns:ns1=" <validatecardfullreturn xsi:type="soapenc:string" xmlns:soapenc=" 9&message=TEST AUTH&amount=50.0&test_status=true</validateCardFullReturn> </ns1:validatecardfullresponse> </soapenv:body> </soapenv:envelope> Page 8 of 23

9 4 Refund Transactions 4.1 Refund Transaction Request Parameters Method Name: SECVPN.refundCardFull PARAMETER EXAMPLE DEFINITION mid vpn_pswd trans_id TRAN0001 This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). A unique transaction identifier created by yourself. This should be the trans_id of the transaction you would like to refund. If you reference a non-unique trans_id, it is the the most recent transaction with this trans_id that will be refunded. Warning: If you deferred and then released your original transaction, you should refund the sale transaction, not the original defer/released. amount remote_pswd new_trans_id TRAN0001_refund The amount to refund. This should contain no currency symbols or formatting (for example do not send an amount with a comma in). Your Remote password can be set from within the Extranet: (Click on "Account" then "Remote Passwords" and select Remote from the drop down list). A unique transaction identifier created by yourself. This will be the trans_id of the new transaction you are creating by performing this refund. 4.2 Refund Transaction Response Parameters The parameters below are the commonly returned parameters for a simple test refund request. PARAMETER EXAMPLE DEFINITION valid true This is true or false and indicates the acceptance or not of the request. trans_id code TRAN0001_refund A We send you back the same new_trans_id that you sent us with your mandatory parameters so that you can update your system appropriately. A short code giving extensive details of failure states. This is the parameter that should be used to programmatically determine whether or not a particular transaction was authorised. See Section 3.2 Figure 1 for possible values. auth_code 9999 This is the authorisation code obtained from the bank for this transaction. This is only returned if valid=true. For a transaction sent when test_status=true, the auth_code will always be Page 9 of 23

10 4.3 Example XMLRPC Refund Request <?xml version="1.0"?> <methodcall> <methodname>secvpn.refundcardfull</methodname> <params> <value><string></string></value> <value><string></string></value> <value><string>tran0001</string></value> <value><string>50.00</string></value> <value><string></string></value> <value><string>tran0001_refund</string></value> </params> </methodcall> 4.4 Example XMLRPC Refund Response <?xml version="1.0" encoding="iso "?> <methodresponse> <params> <value>?valid=true&trans_id=tran0001_refund&code=a&auth_code=9999 </value> </params> </methodresponse> Page 10 of 23

11 4.5 Example SOAP Refund Request <soapenv:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soapenv=" xmlns:sec=" <soapenv:header/> <soapenv:body> <sec:refundcardfull soapenv:encodingstyle=" <mid xsi:type="xsd:string"></mid> <vpn_pswd xsi:type="xsd:string"></vpn_pswd> <trans_id xsi:type="xsd:string">tran0001</trans_id> <amount xsi:type="xsd:string">50.00</amount> <remote_pswd xsi:type="xsd:string"></remote_pswd> <new_trans_id xsi:type="xsd:string">tran0001_refund</new_trans_id> </sec:refundcardfull> </soapenv:body> </soapenv:envelope> 4.6 Example SOAP Refund Response <soapenv:envelope xmlns:soapenv=" xmlns:xsd=" xmlns:xsi=" <soapenv:body> <ns1:refundcardfullresponse soapenv:encodingstyle=" xmlns:ns1=" <refundcardfullreturn xsi:type="soapenc:string" xmlns:soapenc=" A&auth_code=9999</refundCardFullReturn> </ns1:refundcardfullresponse> </soapenv:body> </soapenv:envelope> Page 11 of 23

12 5 Placing Deferred Transactions Deferred transactions are transactions that take place in two stages. The first time a deferred transaction is sent to PayPoint.net an authorisation takes place and funds in the cardholders account are frozen pending release but the money will not be debited. In order for these frozen funds to be released you need to follow up with a release request. The frozen funds will timeout and become un-frozen if the deferred transaction is never released. Deferred transactions are created by submitting the deferred parameter inside the options parameter of a standard realtime transaction request. See Section 3. There are two possible values for the deferred parameter; true or reuse: deferred=true If deferred=true is used then only one unit of currency is authorised against (and subsequently frozen pending release) in the initial deferred transaction. This is useful for avoiding tying up funds in your customers account if all you want to do is get their details into the system. Important Note: When a deferred=true transaction is released, a new authorisation takes place. Therefore it is entirely possible that an authorised deferred=true transaction may be declined on the subsequent attempt to release it. It is for this reason that we would remind merchants not to ship any goods unless they have successfully released a deferred transaction. deferred=reuse If deferred=reuse is used, the initial deferred transaction will authorise for the full amount but on release will use the original auth code (that which was obtained by the initial deferred transaction) if it is still valid. If not still valid, releasing will cause a new authorisation to take place (as is the case with deferred=true). What do we mean by still valid?... The current validity of an authorisation code that was obtained using deferred=reuse is determined by: Whether or not the card used is a credit or debit card. The amount of time that has passed since the initial deferred transaction occurred. By default it will reuse the same authorisation code in the same day for debit cards and within the last 7 days for credit cards. The full syntax is 'reuse:<credit period>:<debit period>'. So the default is implicitly 'reuse:7:1'. If you wish you may alter these default settings when sending the initial deferred transaction. Examples Use default settings: deferred=reuse Set credit card auth codes to be valid for 5 days and debit card auth codes to be valid for 3 days: deferred=reuse:5:3 Set debit card auth codes to be valid for 2 days but leave credit card auth code validity period at the default value (7 days): deferred=reuse::2 Set credit card auth codes to be valid for 6 days but leave debit card auth code validity period at the default value (1 day): deferred=reuse:6 Important Note: It cannot be 100% guaranteed that a chargeback will not occur just because the original authorisation code was reused. The longer the period of time an authorisation code is considered to be valid, the greater the risk please bear in mind that you alter the default time periods at your own risk. Page 12 of 23

13 6 Releasing Deferred Transactions 6.1 Release Request Parameters Method Name: SECVPN.releaseCardFull PARAMETER EXAMPLE DEFINITION mid vpn_pswd trans_id TRAN0001 This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). A unique transaction identifier created by yourself. This should be the trans_id of the transaction you would like to release. If you reference a non-unique trans_id, it is the the most recent transaction with this trans_id that will be released. amount The amount to release. This should contain no currency symbols or formatting (for example do not send an amount with a comma in). remote_pswd new_trans_id TRAN0001_release Your Remote password can be set from within the Extranet: (Click on "Account" then "Remote Passwords" and select Remote from the drop down list). A unique transaction identifier created by yourself. This will be the trans_id of the new transaction you are creating by performing this release. 7 Cancelling Deferred Transactions To mark a deferred transaction as cancelled so it can t be released, you need to send the release request above with the amount set to -1 and send the new_trans_id as an empty string. Note: This purely marks the transaction as cancelled on the PayPoint.net system and doesn t send a request to the bank to remove the authorisation. Page 13 of 23

14 8 Performing Repeat Transactions 8.1 Repeat Request Parameters Repeat requests can be used for one off transactions or you can programme your system to call us on a regular basis to take payments. This is more flexible than the PayPoint.net scheduler mentioned in Section 9 as you have more control over the amount charged and when it s charged. There are two methods available for repeat requests. Method Name: SECVPN.repeatCardFull or SECVPN.repeatCardFullAddr SECVPN.repeatCardFull parameters are shown below. If you use SECVPN.repeatCardFullAddr you must add shipping, billing and options parameters on the end as in a standard transaction request in Section 3. You would use SECVPN.repeatCardFullAddr for instance if you wanted to defer the repeat, as you can include the deferred parameter in the options string. PARAMETER EXAMPLE DEFINITION mid vpn_pswd This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). trans_id TRAN0001 amount remote_pswd new_trans_id TRAN0001_repeat expiry_date 0115 A unique transaction identifier created by yourself. This should be the trans_id of the original transaction that has card details associated with it that you would like to use for this repeat transaction. Warning: If you reference a non-unique trans_id, it is the card details associated with the most recent transaction that will be used for this repeat transaction. The amount for the transaction. This should contain no currency symbols or formatting (for example do not send an amount with a comma in). Your Remote password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select Remote from the drop down list). A unique transaction identifier created by yourself. This will be the trans_id of the new transaction you are creating by performing this repeat. If the expiry date associated with the original transaction which you are referencing in order to create this repeat transaction has expired, you may provide a new expiry date using this parameter. Note: The amount bears no relation to the amount of the original transaction you are repeating. The request is purely re-using the card details from the original request. Page 14 of 23

15 9 Using PayPoint.net s Scheduler The repeat option can be used for setting up scheduled transactions that automatically repeat at regular intervals. This is especially useful if you wish to set up some kind of subscription service. You simply send a standard transaction request as in Section 3 and add the repeat parameter to the options parameter. Note: The amount is fixed and once the schedule is setup it cannot be altered. If you need to alter the amount, you will need to delete the schedule and start another one. Example repeat= /monthly/12:50 In the example above, transactions will occur on a monthly basis for twelve months with the first transaction taking place on the 1st August Each repeat transaction will be for 50 units of currency. As you can see from the above example, the value for the repeat option is broken down into 4 parts: repeat=startdate/period/num_reptitions:amount startdate period num_repetitions amount The date on which the first repeat transaction should take place. This needs to be in the format YYYYMMDD The period between repetitions. Possible values are: daily weekly last (last Friday of each month) monthly quarterly half-yearly yearly A number indicating how many repetitions should occur. (Use -1 for infinite repetitions). This is optional and dictates the amount to charge each time. If no amount is specified, the amount from the original transaction which sent these details will be used. Repeat or scheduled transactions can be deleted from within the Extranet by referencing the trans_id of the original transaction that sent the scheduling information (click Transaction then click Delete Schedule and complete the form), or you can send a delete request via API. See Section 10. Note: PayPoint.net will not notify you when a card which is set to repeat expires. Therefore it s recommended that you keep track of your scheduled transaction expiry dates. You can obtain the expiry date of the card used by sending repeat=true in the options string of your original request and the expiry date will be returned in the response. 9.1 repeat_callback repeat_callback is used in conjunction with the repeat field. If supplied, we will generate a callback for each scheduled repeat. The value of this option should be the full path to a processing page on your server that wants to receive notification when repeat transactions occur. As with the repeat parameter, you need to include this in the options parameter. Note: Your repeat callback page must actually provide some HTML response when called by our server. This response must include at least an <html> start and end tag and a <body> start and end tag. Example repeat_callback= Page 15 of 23

16 10 Deleting Scheduled Transactions To delete a schedule you need to send the repeat request as in Section 8, with the Method name: SECVPN.repeatCardFullAddr which includes the extra order, shipping, billing and options parameters on the end. The parameters must be set as follows: Method name: SECVPN.repeatCardFullAddr PARAMETER EXAMPLE DEFINITION mid vpn_pswd trans_id TRAN0001 This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). A unique transaction identifier created by yourself. This should be the trans_id you used to create the schedule originally. amount -1 The amount must be -1 to delete the schedule. remote_pswd new_trans_id expiry_date order shipping billing options repeat_change=true,repeat=false Your Remote password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select Remote from the drop down list). This string must be blank. This string must be blank. This string must be blank. This string must be blank. This string must be blank. You must send repeat_change=true and repeat=false to delete the schedule. Page 16 of 23

17 11 Optional Parameters Below is a list of optional parameters which can be included in the options string. Remember: Not every method name has an options string! PARAMETER EXAMPLE DEFINITION Possible values for card_type are: card_type Visa American Express Delta Diners Card JCB Master Card Credit Debit Master Card Solo Maestro Visa Laser You should check with your merchant bank which card types you can accept. Delta is used for Visa Debit, Connect and Electron cards. Note: Historically you would have sent Master Card as a card type, however since the release of Debit MasterCards we have split the card type into two separate values as above. You can still use the historic Master Card but once the transaction reaches us we will label it as a Debit or Credit card in our database according to our BIN data. cv2 123 dups false See Section 13.3 repeat repeat true /monthly/12:50 test_status true See Section 13.2 usage_type E The CV2/security code on the card. 3 digits for most cards and 4 digits for American Express. This is mandatory on new PayPoint.net accounts as of July To remove this requirement you need to login to the Extranet and alter the CV2-AVS Options under Account then Account Options. See Section 9 - As you can see there are two uses for this option! See Section 9 - As you can see there are two uses for this option! The usage_type parameter is used to advise us what type of transaction you are processing. If you don t supply a usage_type then the default setting is Electronic Commerce. There are three possible values: usage_type=m usage_type=e usage_type=r MOTO (mail order/telephone order) ecommerce (Electronic commerce) Recurring payments Page 17 of 23

18 12 Transaction Reports 12.1 Transaction Report Parameters Method Name: SECVPN.getReport PARAMETER EXAMPLE DEFINITION mid vpn_pswd remote_pswd report_type cond_type XML-Report Date This is your PayPoint.net Gateway account name (usually six letters and two numbers). You can see this ID in the top right corner while logged into the Extranet. Your VPN password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select VPN from the drop down list). Your Remote password can be set from within the Extranet. (Click on "Account" then "Remote Passwords" and select Remote from the drop down list). Possible report types are: CSV CSV-All CSV-Summary CSV-Detail CSV-Five Summary Statement Origin-Statement XML-Report Each report type returns different data in different formats so you will need to find the one that suits your requirements. Possible condition types are: Date Batch TransId Represents the actual value for the condition type chosen. E.g. By Date 2000 : Transactions for : Transactions for April and May : Transactions from April 2000 to present condition By Transaction : Trans Id only 1234% : Transactions starting %5678 : Transactions starting 1234 and ending ~ : Transactions between and currency predicate GBP By Batch No. 100 : Batch 100 only : Batches 100 through 110 Note: There must be at least four characters preceding the '%' The 3 character currency code specifying the currency of the transactions you would like included in the report. Arbitrary Condition - advanced users only, otherwise use an empty string. html false Boolean value specifying whether to return report as html or not. showerrs false Boolean value specifying whether or not unauthorised transactions should be included in the report results. Page 18 of 23

19 13 Testing You can test your integration using your own account (for example: abcdef01) through the use of the test_status optional parameter. See Section 13.2 test_status 13.1 Test Card Numbers Below are some test card numbers. These can be used with any name and address details, any 3 digit CV2 security code and any expiry date which is in the future. Visa Master Card Credit You can of course make an attempt to use an expiry date which is set in the past in order to see what happens in that event! 13.2 test_status The test_status is used to stimulate either an authorised or declined response from PayPoint.net so that you can confirm that your web application behaves appropriately in each instance. There are three possible values: test_status=true Simulate an authorised callback without contacting the bank test_status=false Simulate a declined callback without contacting the bank test_status=live Send the transaction to the bank for authorisation The test_status parameter is sent in the options string dups By default PayPoint.net will stop the same trans_id from the same user being used twice in the same hour (this is to stop duplicates). Note: We believe this feature reduces customer bills by approximately 10% and also reduces the administration overhead, it is a 'best efforts' feature however and can never be 100%. You must accept that occasionally you will get duplicates. However, sometimes during the testing phase of your integration, it is useful to not have to bother creating a new trans_id for each transaction you send to PayPoint.net. If you wish to send test transactions with the same trans_id but want PayPoint.net to not perform duplicate checks, i.e.: you want PayPoint.net to allow these duplicate transactions into the system without blocking them as duplicates then you must send the dups parameter with a value of false within the options string. This will tell PayPoint.net to turn off duplicate checking for this transaction. This should be removed before going live default_cv2avs When you submit a payment with the test_status parameter, the details obviously don t go to the bank for checking, so you can use the default_cv2avs parameter in the options string to simulate the cv2avs response. See Section 3.3 for the possible values. Example default_cv2avs=all MATCH Note: This is especially useful if you have set the CV2-AVS Options within the Extranet and don t want to have to remove them for testing. Page 19 of 23

20 SECTION 2 This section describes how to customise the PayPoint.net Hosted Payment Pages. As mentioned in the beginning of this guide, some merchants like to use our Hosted Payment Pages to take the initial payment and then use the API for tokenised requests to take advantage of PayPoint.net s level 1 PCI compliance. You will need to download the Gateway Hosted integration guide for further information on mandatory security measures, callbacks and other elements of the Hosted method. Page 20 of 23

21 14 PayPoint.net Custom Hosted Payment Pages If you are going to use the Hosted Payment Pages, the page into which cardholders enter their credit card details is stored on the PayPoint.net servers and linked to from your website. You have the ability to customise this template so that its look and feel blends in with the rest of your site. Unlike many other Payment Service Providers, it is possible for you to have several different websites sending transactions through one PayPoint.net account (which has associated with it one Internet Merchant Account). You are therefore free to have several different templates, each of which fits in with your various websites. merchant=abcdef01, template= SECPay displays templ1.html for usage PayPoint.net Secure Servers merchant=abcdef01, template= SECPay displays templ2.html for usage merchant=abcdef01, template= SECPay displays templ3.html for usage 14.1 Customising Your Template The default payment page template can be found at the following address: Please visit the above page and save the HTML source code to your computer. The first thing you will notice when looking at this page is that it contains many server side variables such as ${bgcolor} These variables are replaced at runtime by software running on the PayPoint.net servers and should therefore be left intact. These variables exist in order to allow you to dynamically set their values without altering your template. The value of each variable can easily be set by sending a request parameter with exactly the same name. For example, you will notice that the standard template has a variable named ${bgcolor}. If you include the following hidden input field in the form which you POST to PayPoint.net: <input type= hidden name= bgcolor value= hotpink >..then the ${bgcolor} variable in your template would be replaced with the value hotpink and your template would be a nice shade of pink. This works for all of the variables present in the template and can be used for altering text, colours etc. Tip: sending a parameter with the same name as a variable in your template will dynamically replace that variable with the value of your parameter! PayPoint.net do not impose any restrictions on how you customise the look and feel of your template. You may add your own graphics and stylesheets and restructure the layout of the form fields in any way you choose. We do not specify that you must include our logo the look of this page is 100% up to you. Warning: avoid using Frontpage, Dreamweaver or any other WYSIWYG design tools with this template. More often than not, the use of one of these tools will break the template either by incorrectly manipulating the server side variables or by moving the </form> tag around. We therefore recommend that this template is customised by hand. Any images you add to your template must be uploaded to the PayPoint.net secure servers and referenced absolutely using an HTTPS URL. Example <img src= Page 21 of 23

22 14.2 Uploading Your Template Once you have customised your template you may upload it to the PayPoint.net servers from within the Extranet ( In the Extranet, choose Account then File Manager on the left hand side menu. This should display a form and allow you to upload your template and associated files through the browser Referencing Your Template In order to utilise your own custom template you must add the request parameter template to the list of parameters you post to the PayPoint.net servers. The template parameter is not mandatory and therefore if you do not use it, the default card payment page would be displayed to the cardholder and your template will not be used. After you have uploaded your template and other files to the PayPoint.net server, these files will be located in a directory which has the same name as your PayPoint.net username. Example and you would specify that it should be used by including the following request parameter amongst those that you POST to PayPoint.net: <input type= hidden name= template value= > Note: The location of your template file should be specified using http and not https Customising the err_template This is the HTML template we use for displaying error messages, if you wish you can supply your own by using this parameter. Depending on the error, our system calls one of two templates. This one is called if there is a problem with your callback page: This one for other errors: If you want to customise the error pages, you will need to combine the code in the above two pages into one page. This must be uploaded to the PayPoint.net servers from within the Extranet ( then referenced to by using the err_template parameter in your form POST. Example <input type= hidden name= err_template value= > Note: If this URL is wrong then there will be no template for displaying the error message to that effect, you have been warned... Page 22 of 23

23 14.5 Customising Payment Page Error Messages A set of parameters you can POST in your form that allows you to tailor the text shown in the event of an error. This is useful for tailoring error message text and foreign language errors. Parameter card_no_error card_type_error customer_name_error start_date_error expiry_date_error issue_error Default Value Card No Card Type Customer Name Start Date Expiry Date Issue No Warning: Please remember all parameters are case sensitive! 14.6 Digest Checking Digest checking is mandatory when using PayPoint.net s Hosted Payment Pages. Please refer to the Gateway Hosted integration guide Security section for further details on how to implement digest checking Mandating CV2 To mandate the CV2 code you can supply req_cv2=true in the options parameter of your form POST. Alternatively you can set the CV2-AVS options within the Extranet under Account then Account Options. To make the CV2 mandatory via the Extranet you must set it to Strict. REMINDER You WILL need to refer to the Gateway Hosted integration guide for more information on other aspects of using PayPoint.net s Hosted Payment Pages. Page 23 of 23