Payment Page Extensions. Online Payment Processing for Businesses Worldwide.

Transcription

1 Payment Page Extensions Online Payment Processing for Businesses Worldwide

2 Page 2 of 13 Contents About this guide... 3 Copyright... 3 Introduction... 3 Using an extension... 4 Additional information blocks... 4 Repeat Billing... 5 Payment Agreements... 5 Immediate Payment Amount... 6 Regular Payment Amount... 6 Agreement interval period... 6 Agreement term... 7 Start date... 7 Final payment amount... 7 Payment method... 8 Data security check... 8 Sample agreements... 8 Card Filter... 9 Card Discount Document history... 13

3 Page 3 of 13 About this guide This guide describes various extensions that are available for use with the Telr Hosted Payment Pages. This guide should be used in conjunction with the Hosted Payment Pages Integration Guide. Copyright 2014 Telr. All rights reserved. While every effort has been made to ensure the accuracy of the information contained in this publication, the information is supplied without representation or warranty of any kind, is subject to change without notice and does not represent a commitment on the part of Telr. We assume no responsibility and shall have no liability, consequential or otherwise, of any kind arising from this material or any part thereof, or any supplementary materials subsequently issued by Telr. Telr has made every effort to ensure the accuracy of this material. Introduction The Hosted Payment Page service is a secure PCI DSS compliant system, use of which does not require the merchant to have their own PCI compliance as card details are held only within the Telr systems. This is the fastest way to get up and running with on- line payments. This integration method uses HTML messages to pass information between your site and Telr. It is the simplest and easiest method of integration and will work on just about any platform. There is nothing to install with the Hosted Payment Page method of integration. All you need is a working Internet connection and your store ID.

4 Page 4 of 13 Using an extension The extensions are optional modules that can be used in addition to the standard payment request. You should first complete the integration process using a standard request before looking to add any of the additional modules. Each module is referenced by including the module name within the additional information blocks list (the ivp_extra field) as part of the transaction request. The additional data needed for any module can then also be added to the request. To indicate which additional information blocks you are sending, you must set the ivp_extra field in the main purchase request. If an information block is not listed within the ivp_extra field then that block will be ignored. If there are no additional information blocks being sent as part of the request, the ivp_extra field must be set to the word none. If one or more blocks are being sent, then the ivp_extra field must contain a comma separated list of the blocks. For example if the billing details, delivery details and card filter details are sent then ivp_extra must be set to bill,delv,filter Additional information blocks Bock bill delv xtra return repeat filter discount Description Supply card holder billing details such as name, address and . Supply delivery details Additional transaction details URL s to be used for Call- backs and returning the customer to your store Repeat billing details (recurring transactions) Card filter limit transactions to a specific card Card discount apply a discount if a specific card range is used Note: The bill, delv, xtra and return blocks are part of the standard payment request options, and as such are covered in the Hosted Payment Pages Integration Guide.

5 Page 5 of 13 Repeat Billing The Repeat Billing system gives merchants who use the Hosted Payment Pages the ability to setup and manage recurring payments, such as those used in a subscription service. Merchants who collect and store their shoppers' payment details on their own platform and use the Remote integration method as the gateway interface will need to implement their own subscription management system if this is required. Recurring payments can be made by either directly debiting a given card, or by sending an e- invoice before the payment is due. The ability to directly debit a card for each payment depends upon your acquiring bank allowing Continuous Authority transactions for your merchant account. Payment Agreements The Repeat Billing System allows you to create and manage what are termed Payment Agreements. These Payment Agreements specify the value and frequency of the payments to be made. Payment Agreements can be for a fixed term, or for an unlimited term. There are four basic elements to a Payment Agreement. These are as follows: Start date Term Payment interval (e.g. monthly) Regular payment amount There are two further optional elements that can be defined. These are as follows: Immediate payment amount Final payment amount With these six elements it is possible to create Payment Agreements that suit most subscription requirements or other regular payment requirements.

6 Page 6 of 13 Sending the payment agreement card details The pre- registered card details are sent as part of the transaction request in the repeat block, which consists of the following fields: Field Description Notes repeat_amount Regular payment amount The amount to be taken at each payment interval. repeat_period Agreement interval period This indicates both the interval count and interval type. The interval type can be either m for months or w for weeks. repeat_start Agreement start date Formatted as DDMMYYYY. The start date cannot be the same date that the agreement is made on, and cannot be a date that has already past. repeat_term Agreement term Indicates the number of regular payments to take. Set this to zero to indicate an unlimited term. repeat_final Final payment amount 0 if there is no final payment amount. repeat_method Payment method Card or Invoice repeat_custid Customer ID Your reference for this customer. repeat_signature Data security check Uses the same algorithm and key as for the main purchase details. All payment amounts are taken in the same currency as used for the main transaction request (as sent in the field). The amounts must be sent in major units (for example, 9 dollars 50 cents must be sent as 9.50 not 950). Immediate Payment Amount This specifies an amount to be taken at the same time that the agreement is setup. It is in addition to any amount that would be taken as part of the regular payment processing. If there is no amount to be taken, this should be set to zero. The immediate payment amount is sent as the ivp_amount field in the main transaction request. Regular Payment Amount This is the amount that will be taken from the card holder for each payment Agreement interval period This is formatted as a number followed by a single letter. There should be no spaces, and the number must be an integer value greater than zero. Valid letters are m or w which relate to Month or Week. Examples repeat_period=1m repeat_period=3w Payment taken every month Payment taken every three weeks.

7 Page 7 of 13 Agreement term This is a number indicating how many regular payments are to be taken. Set this to zero to indicate an agreement that does not have a fixed term. Examples repeat_period=1m repeat_term=12 repeat_period=3m repeat_term=0 12 payments taken one month apart agreement duration is 1 year. Payments taken every quarter, no fixed term. Payments will continue until such time as the agreement is cancelled. Start date This indicates when the first regular payment should be taken. It is an 8 digit value, formatted as DDMMYYYY where DD = 2 digit day, MM = 2 digit month and YYYY = 4 digit year. This date cannot be in the past, and cannot be the same date as the date the agreement is being made on (i.e. it cannot be today) When the payment interval is specified in weeks, it will be taken on the same day of the week as the day that this date represents. For example, as the 1 st of May 2011 ( ) is a Sunday, every payment would be taken on a Sunday. When the payment interval is specified in months, it will be taken of the same day of the month as the day given here. In the event that this is scheduled for a day that not all months have, then the payment will be taken on the last day of the month instead. For example, a payment scheduled for the 30 th of each month would be taken on the 28 th (or 29 th ) of February, and on the 30 th for all other months. The start date value can be supplied as the word next in which case the first regular payment will be scheduled for one payment interval on from today. Examples repeat_period=1m repeat_start= repeat_period=2w repeat_start= repeat_period=1m repeat_start=next First payment to be taken on the 10 th of August Subsequent payments will be taken on the 10 th of each month. First payment will be taken on the 3 rd of June As that is a Saturday, subsequent payments will be taken every two weeks on a Saturday. First payment will be taken 1 month from today. Subsequent payments will be taken on the same day of each month. Final payment amount This specifies an amount to be taken at the end of the agreement. This is only applicable for fixed term agreements (where repeat_term is non- zero). This final amount is in addition to any amount that would be taken as part of the regular payment processing. It will be taken at one payment interval following the last regular payment.

8 Page 8 of 13 Payment method This allows you to set which payment method is used for each recurring payment. If this is set to invoice then an invoice will be sent to the customer before each payment is due. This allows repeat billing to be used even where your acquiring bank does not support the use of Continuous Authority transactions. Invoice payments are taken using the Hosted Payment Pages and as such are full e- commerce class transactions. If this is set to card, then the card details collected from the customer at the time the agreement is created will be used for each repeat transaction. If no immediate payment amount is due, card details will still be collected and will be verified prior to the agreement being created. Your acquiring bank will need to support Continuous Authority transactions in order for you to use this method. Data security check The signature is calculated in the same way as the main purchase details, using the same algorithm and secret key. The signature calculated for the main purchase details is used as one of the elements for generating this signature, which ensures that the discount details received are known to belong to this purchase request. The fields used in the calculation are: repeat_amount repeat_period repeat_start repeat_term repeat_final repeat_method repeat_custid ivp_signature You must include repeat in the ivp_extra field from the main purchase request for this block to be accepted. Sample agreements Initial payment followed by monthly payments with no fixed term repeat_period=1m Take an immediate payment of $39.95, followed by payments of $19.95 repeat_start=next every month. ivp_currency=usd ivp_amount=39.95 repeat_amount=19.95 Initial payment, followed by 11 monthly payments and then a final payment. repeat_period=1m repeat_term=11 repeat_start=next ivp_currency=usd ivp_amount=39.95 repeat_amount=19.95 repeat_final=40.60 Take an immediate payment of $39.95, followed by 11 payments of $19.95 every month, and one final payment of $40.60 one month later. The total term of the agreement would be 12 months (11 months for regular payments, then one month for the final payment). The total amount paid would $ : $ (11 * $19.95) + $40.60

9 Page 9 of 13 Card Filter This module allows you to send details of pre- registered card numbers as part of the transaction request. This could be used, for example, by a service provider who first requires a customer to visit their premises and register in person in order to use their systems. The registration process could include taking details of the card(s) that the customer will use. The registration process should not retain the complete card details, only the first 4 and last 4 digits of any card. The use of the filter data within any transaction depends on the Card Filter options set within the Merchant Administration System: If the Card Filter status is set to Disabled, then any filter data that may be sent as part of the transaction request will be ignored. If the status is set to Optional, then the filter actions will only take place if the filter data is present within the transaction request. If set to Mandatory, then the card filter data must be sent with every transaction request. If a card filter is set as part of a transaction, and the customer uses a card which does not match the details given, then the transaction will be declined. This will generate a transaction response with a status of D and a code of 80. The message normally used is Not authorised but this can be changed to any other message if required.

10 Page 10 of 13 Sending the pre- registered card details The pre- registered card details are sent as part of the transaction request in the filter block, which consists of the following fields: Field Description Notes filter_cards List of permitted cards filter_signature Data security check Uses the same algorithm and key as for the main purchase details. The filter_cards field contains the list of permitted cards. Each card is sent as the first 4 digits and the last 4 digits separated using a dash (hyphen) character, for example: Multiple cards can be sent by separating each entry with a comma, for example: , The signature is calculated in the same way as the main purchase details, using the same algorithm and secret key. The signature calculated for the main purchase details is used as one of the elements for generating this signature, which ensures that the filter details received are known to belong to this purchase request. The fields used in the calculation are: filter_cards ivp_signature You must include filter in the ivp_extra field from the main purchase request for this block to be accepted. If there is no filter data for a given transaction, but the card filter options are set to mandatory, then the value None should be sent in the filter_cards field. If the card filter data contains details of only one card, a note entry will be added to the payment page display to remind the customer of which card to use.

11 Page 11 of 13 Card Discount This module allows you to offer a discount depending upon the card that was used to complete the transactions. Normal discounts (such as vouchers) would be applied by your shopping cart before sending the transaction details to the gateway. However, if the discount to be applied is dependent upon a specific card type being used, then this cannot be done by the shopping cart before the transaction is sent to the gateway as at that point there is no indication of which card is going to be used. The typical type of offers you may see like this are along the line of: 10% discount for using your BankX card. Up to 4 different discounts can be provided as part of each transaction request. Sending the discount details The details are sent as part of the transaction request in the discount block, which consists of the following fields: Field Description Notes disc_card1 List cards eligible for discount 1 disc_amount1 Amount of discount 1 disc_desc1 Description of discount 1 disc_code1 Reference code for discount 1 disc_card2 List cards eligible for discount 2 disc_amount2 Amount of discount 2 disc_desc2 Description of discount 2 disc_code2 Reference code for discount 2 disc_card3 List cards eligible for discount 3 disc_amount3 Amount of discount 3 disc_desc3 Description of discount 3 disc_code3 Reference code for discount 3 disc_card4 List cards eligible for discount 4 disc_amount4 Amount of discount 4 disc_desc4 Description of discount 4 disc_code4 Reference code for discount 4 disc_signature Data security check Uses the same algorithm and key as for the main purchase details. Discount amounts must be priced in the same currency as was used for the main transaction request (as sent in the field). The amounts must be sent as actual amounts and not % amounts, and must be sent in major units (for example, 9 dollars 50 cents must be sent as 9.50 not 950). The availability of potential discounts will not be advertised by the payment pages, that must be done within your shopping site. The payment pages will update the displayed transaction details should a card be used which matches a supplied discount.

12 Page 12 of 13 The disc_card fields must contain a comma separated list of the card ranges that this discount applies to. A card range must be either 4, 5 or 6 digits and represents all cards that start with that range. Each discount can be applied to up to 20 different ranges. For example, given a transaction request that had the following: ivp_currency = AED ivp_amount = disc_card1 = 4111 disc_amount1 = disc_code1 = Offer1 disc_desc1 = 10% discount for using your test card This would generate a normal transaction request for AED , but if the customer happened to pay with a card starting 4111 then a discount of AED would be applied, and only the balance of AED would be charged to the card. disc_card1 = , disc_amount1 = disc_code1 = OfferBankX disc_desc1 = 10% discount for using your Bank/X debit card disc_card2 = disc_amount2 = disc_code2 = OfferBankY disc_desc2 = 5% discount for using your Bank/Y platinum card This would apply the first discount to any card starting or and the second discount to any starting Only 1 discount can be applied at a time, and it will be the first matching one (so if this has listed in card2 as well as card1, it would match the first discount not the second one) The signature is calculated in the same way as the main purchase details, using the same algorithm and secret key. The signature calculated for the main purchase details is used as one of the elements for generating this signature, which ensures that the discount details received are known to belong to this purchase request. The fields used in the calculation are: disc_card1 disc_amount1 disc_code1 disc_desc1 disc_card2 disc_amount2 disc_code2 disc_desc2 disc_card3 disc_amount3 disc_code3 disc_desc3 disc_card4 disc_amount4 disc_code4 disc_desc4 ivp_signature You must include discount in the ivp_extra field from the main purchase request for this block to be accepted. The transaction details shown on the payment page will update as the customer enters their card number, showing details of any discount that will be applied.

13 Page 13 of 13 Document history Release Changes 1.02 Added the card discount module Added the card filter module Initial release repeat billing module.