technical manual Direct Payments handelsbanken.se/e-handel

Transcription

1 Direct Payments handelsbanken.se/e-handel

2 Contents Description of the sevice...3 Direct Payment...4 From the company to Handelsbanken...4 From Handelsbanken to the company...6 Payment check...8 From the company to Handelsbanken...8 From Handelsbanken to the company...10 Recrediting...12 From the company to Handelsbanken...12 From Handelsbanken to the company

3 Description of the service Handelsbanken s Direct Payment is a secure payment solution for e-commerce. This service is for private individuals. The smallest amount that can be transferred at Handelsbanken is SEK This is how it works The buyer visits the company s online store to buy goods or services. When it is time to pay for the goods, the buyer selects payment via Handelsbanken s Direct Payment service. The customer is then linked from the store to Handelsbanken s online service where he or she logs on as usual and selects the account from which the payment should be made. The amount payable and the payment reference accompany the link from the company to the Bank. The buyer cannot change the amount or the payment reference. When the buyer has signed for the purchase and the payment has been executed, information on the direct payment (amount, payment reference and payment status) is sent to the company via the buyer s web browser. The information is encrypted during transmission and is secured with a password that the Bank provides the company with when the service is set up. When the payment has been made, the customer sees the company s name on the account statement and the company sees the order number. 3

4 Direct Payment From the company to Handelsbanken The company links to Handelsbanken by using a form with the following content: <form action= haction=3&handoverdatatype=1&appname=ssse&language=sv&country=se method= post > It is possible to use an English version, but you must first change the language code and country code in the URL: <form action= haction=3&handoverdatatype=1&appname=ssse&language=en&country=gb method= post > The store ID, order amount, return URL, and check sum are in hidden fields and are filled in by the company. Field Type Description Butikid String, 4 numeric characters A code that uniquely identifies a company linked to Direct Payment. (Store ID) Handelsbanken assigns this code to the company. Orderbelopp (Order amount) String, max. 10 alphanumeric characters. String, max. 9 numeric characters. The last two digits always signify öre. The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. The order amount that is transferred from the buyer s account to the company s account. Note that the amount does not contain any demarcation to set off the öre. The last two positions represent öre. For example, SEK 265 is written as Ordernummer (Order number) Senastebokningstid (Latest booking time) Sträng, 14 characters. (YYYYMMDDTTMMSS). A string that contains the date and time. The Bank will not book the payment after this time. Delays may occur so the payment does not immediately arrive at the Bank. The company can use this parameter to set the latest time when the Bank is permitted to book a payment. Retururl (Return URL) String, 150 characters. The URL which Handelsbanken will link the buyer back to (includes the start characters i.e. the page that confirms the order in the company s system. Kontrollsumma (Check sum) String, 32 characters. This string checks that no manipulation of the data has taken place during transmission. The string is constructed by combining the store ID, order number and order amount in that order, to a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. Check that the check sum agrees with the data sent in before payment is executed.the calculation is done with the exact field content. For example, if the order amount is 15000, the calculations are made using the and not

5 Example of a form <HTML> <HEAD><TITLE>HANDELSBANKEN - DIREKTBETALNING</TITLE> <BODY TEXT= BGCOLOR= ffffff > <FONT FACE= Arial,Helvetica SIZE=+2 COLOR= # > <B>Handelsbanken</B><BR><BR> </FONT> <FONT FACE= Arial,Helvetica > You will now be redirected to Handelsbanken s website for Direct Payment.<BR> You log on as normal.<br><br> </FONT> <form action= haction=3&handoverdatatype=1&appname=ssse&language=sv&country=se method= post > <INPUT TYPE= submit VALUE= Klicka här för att genomföra betalningen > <INPUT TYPE= hidden NAME= butikid VALUE= 9999 ><BR> <INPUT TYPE= hidden NAME= ordernummer VALUE= ABCD ><BR> <INPUT TYPE= hidden NAME= orderbelopp VALUE= 1100 ><BR> <INPUT TYPE= hidden NAME= kontrollsumma VALUE= 26efb0517cdfbbacb13a61e91feae16d ><BR> <INPUT TYPE= hidden NAME= senastebokningstid VALUE= ><BR> <INPUT TYPE= hidden NAME= retururl VALUE= ><BR> <BR> </FORM> </BODY> </HTML> Note that the check sum is calculated using the store ID, order number, order amount and secret word. The check sum above is calculated using the secret word = aaaabbbb. 5

6 Direct Payment Fom Handelsbanken to the company Handelsbanken links back to the company using a form with the following content: <FORM ACTION= Den inskickade retururl METHOD= post > The order number, status, time stamp and checksum are in hidden fields and are filled in by Handelsbanken. Field Type Description Butikid String, 4 numeric characters A code that uniquely identifies a company linked to Direct Payment. (Store ID) Handelsbanken assigns this code to the company. Ordernummer (Order number) String, max. 10 alphanumeric characters The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. Orderbelopp (Order amount) String, max. 9 numeric characters. The last two digits always signify öre. The order amount that is transferred from the buyer s account to the company s account. Note that the amount does not contain any demarcation to set off the öre. The last two positions represent öre. For example, SEK 265 is written as Status String, 1 numeric character Contains a zero or a one. The zero denotes that the payment worked and a one that it did not work. Timestamp String, 14 characters (YYYYMMDDTTMMSS). A string containing the time the response was created in Handelsbanken s server. Kontrollsumma (Check sum) String, 32 characters. This string checks that no manipulation of the data has taken place during transmission. The string is constructed by combining the store ID, order number, order amount, status and time stamp in that order, into a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. Check that the check sum agrees with the data sent in before payment is executed. The calculation is done with the exact field content. For example, if the order amount is 15000, the calculations are made using the and not

7 Example of a form Hidden fields in the response form when the transfer is OK <INPUT TYPE= hidden NAME= butikid VALUE= 9999 > <INPUT TYPE= hidden NAME= ordernummer VALUE= ABCD > <INPUT TYPE= hidden NAME= orderbelopp VALUE= 1100 > <INPUT TYPE= hidden NAME= status VALUE= 0 > <INPUT TYPE= hidden NAME= timestamp VALUE= > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= 1f3caf897286c3159b65a705cf > The check sum is calculated using the store ID, order number, order amount, status, time stamp and secret word. Hidden fields in the response form when the transfer is cancelled <INPUT TYPE= hidden NAME= butikid VALUE= 9999 > <INPUT TYPE= hidden NAME= ordernummer VALUE= ABCD > <INPUT TYPE= hidden NAME= orderbelopp VALUE= 1100 > <INPUT TYPE= hidden NAME= status VALUE= 1 > <INPUT TYPE= hidden NAME= timestamp VALUE= > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= b6914cca7702f96983a06c694b00ce34 > The check sum is calculated using the store ID, order number, order amount, status, time stamp and secret word. If an error occurs in the transfer (status=1) at an early stage, we cannot produce any check sum and thus there is no value in this field. <INPUT TYPE= hidden NAME= kontrollsumma VALUE= > Note that the check sum above is calculated using the secret word = aaaabbbb. 7

8 Payment check From the company to Handelsbanken Handelsbanken is sometimes unable to send back an electronic receipt to the company. This may be due to the customer going offline, a disruption or other reason. To find out if an order has been carried out, the company can send an inquiry to us regarding unconfirmed orders. The inquiry may contain one or more orders and be initiated at an interval that the company can select. The technical adaptation required to use the payment control is described below. IP address The company calls up Handelsbanken from the IP address that the Bank has been informed about. The Bank checks that the call comes from the correct IP address. If this is incorrect, the call is rejected. Therefore, it is very important that the correct IP address is entered in the information that is submitted to the Bank when the agreement is signed. Companies that want to use several IP addresses may do so providing they have the same number series. One or more of the final positions in the IP address can then be replaced with?. Encryption The encryption must be 128 bits. Form The company links to Handelsbanken using a form with the following content: <FORM ACTION= betalkontroll METHOD= post > The version no., store ID, number, order number1, order number2, etc. and check sum are in hidden fields and are filled in by the company. Example: can be written ? or ?? or ???. However, an agreement cannot include IP addresses that are totally different. 8

9 Field Type Description Versionsnr String, 4 numeric characters A number that identifies the version of the payment check function (Version no.) that is called up at Handelsbanken. This is set as 1. Butikid (Store ID) String, 4 numeric characters A code that uniquely identifies a company linked to Direct Payment. Handelsbanken assigns this code to the company. Antal (Number) String, 3 numeric characters A number that identifies how many order numbers are to be checked. Max 500. Ordernummer (Order number) String, max. 10 alphanumeric characters. The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. Max 500. Kontrollsumma (Check sum) String, 32 characters. This string checks that no manipulation of the data has taken place during transmission. The string is constructed by joining the version no. store ID, number, order number 1, order number 2 in that order to a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. Check that the check sum agrees with the data sent in before payment is executed. The calculation is done with the exact field content. For example, if the order amount is 10, the calculations are made using the 10 and not 010. Example <INPUT TYPE= hidden NAME= versionsnr VALUE= 1 > <INPUT TYPE= hidden NAME= butikid VALUE= 1234 > <INPUT TYPE= hidden NAME= antal VALUE= 3 > <INPUT TYPE= hidden NAME= ordernummer1 VALUE= A > <INPUT TYPE= hidden NAME= ordernummer2 VALUE= A > <INPUT TYPE= hidden NAME= ordernummer3 VALUE= A > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= 26ad3af832f376ed43243f408350d837 > Note that the check sum above is calculated using a secret word = aaaabbbb. 9

10 Payment check From Handelsbanken to the company Form Handelsbanken replies to the company s Http request by using a page with the following content:store ID, number, order number 1, status1, remain_order amount1, order number 2, status2, remain_order amount2, etc. and check sum. These are located in hidden fields and are filled in by Handelsbanken. Field Type Description Butikid String, 4 numeric characters A code that uniquely identifies a company linked to Direct Payment. (Store ID) Handelsbanken assigns this code to the company. Antal (Number) String, 3 numeric characters A number that identifies how many order numbers are to be checked. Orderbelopp (Order amount) String, max. 10 alphanumeric characters. The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. Status String, 1 numeric character 0 = Order OK. 1 = Order not OK. kvarv_orderbelopp (remaining order amount) The order amount remaining after any credits. Note that the amount does not contain any demarcation to set off the öre. The last two positions represent öre. For example, SEK 265 is written as Kontrollsumma (Check sum) String, 32 characters. This string checks that no manipulation of the data has taken place during transmission. The string is constructed by joining the store ID, number, order number1, status 1, remaining amount1, order number2, status2, remaining amount2 in that order to a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. 10

11 Example <INPUT TYPE= hidden NAME= butikid VALUE= 1234 > <INPUT TYPE= hidden NAME= antal VALUE= 3 > <INPUT TYPE= hidden NAME= ordernummer1 VALUE= A > <INPUT TYPE= hidden NAME= status1 VALUE= 0 > <INPUT TYPE= hidden NAME= kvarv_orderbelopp1 VALUE= > <INPUT TYPE= hidden NAME= ordernummer2 VALUE= A > <INPUT TYPE= hidden NAME= status2 VALUE= 1 > <INPUT TYPE= hidden NAME= kvarv_orderbelopp2 VALUE= 0 > <INPUT TYPE= hidden NAME= ordernummer3 VALUE= A > <INPUT TYPE= hidden NAME= status3 VALUE= 0 > <INPUT TYPE= hidden NAME= kvarv_orderbelopp3 VALUE= > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= 1a3dfaf2233f0ac5ed3eec66eb47b16e > Note that if the order is not OK, there will be a zero in kvarv_orderbelopp. The check sum above is calculated using a secret word = aaaabbbb. Error management If a technical error occurs, for example, the check sum from the company is not correct or there is some other error at the Bank, then the session is cancelled and the Bank ends the call. 11

12 Recrediting From the company to Handelsbanken When a customer has made a purchase and made payment using Handelsbanken s Direct Payment, the company sometimes may not be able to deliver all or part of the order. The customer can also ask for a refund of a product or service. The company can refund a customer using the Recredíting service. To make a recredit, the order must have been paid using Handelsbanken s Direct Payment. The recredit must NOT exceed the original order amount. Recredits can be done several times for the same order but each recredit must NOT exceed the remaining order amount after deduction. The technical adaptation required for recrediting is described below. IP-adress The company calls up Handelsbanken from the IP address that the Bank has been informed about. The Bank checks that the call comes from the correct IP address. If this is incorrect, the call is rejected. Encryption The encryption must be 128 bits. Form The company links to Handelsbanken using a form with the following content: <FORM ACTION= kreditering METHOD= post > The version no., store ID, number, order number and check sum are in hidden fields and are filled in by the company. 12

13 Field Type Description Versionsnr (Version no.) String, 4 numeric characters. A number that identifies the version of the payment check function that is called up at Handelsbanken. This is set as 1. Butikid (Store ID) Ordernummer (Order number) String, 4 numeric characters. String, max. 10 alphanumeric characters A code that uniquely identifies the company connected to Direct Payment. Handelsbanken assigns this code to the company. The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. kvarv_orderbelopp (remaining order amount) krediteringsbelopp (credit amount) kontrollsumma (check sum) String, max. 9 numeric characters. The last two digits always signify öre. String, max. 9 numeric characters. The last two digits always signify öre. String, 32 characters. The remaining amount of the order before crediting. Amount to recredit This string checks that no manipulation of the data has taken place during transmission. The string is constructed by combining the version number, store ID, order number, remaining order amount and credit amount in that order, to a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. Check that the check sum agrees with the data sent in before the recredit is executed. The calculation is done with the exact field content. For example, if the version is 1, the calculations are made using the 1 and not Exemple <INPUT TYPE= hidden NAME= versionsnr VALUE= 1 > <INPUT TYPE= hidden NAME= butikid VALUE= 1234 > <INPUT TYPE= hidden NAME= ordernummer VALUE= A > <INPUT TYPE= hidden NAME= kvarv_orderbelopp VALUE= > <INPUT TYPE= hidden NAME= krediteringsbelopp VALUE= > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= b8e6faaf3cca294814d0e06a8d4dac49 > Note that the check sum above is calculated using a secret word = aaaabbbb. 13

14 Recrediting From Handelsbanken to the company Form Handelsbanken replies to the company s Http request by using a page with the following content: store ID, order number, status, remaining order amount, order number and check sum. These are located in hidden fields and are filled in by Handelsbanken. Field Type Description Butikid (Store ID) String, 4 numeric characters A code that uniquely identifies a company linked to Direct Payment. Handelsbanken assigns this code to the company. Ordernummer (Order number) String, max. 10 alphanumeric characters The code that uniquely identifies an order with the company. The order number may be shorter if the company prefers this, but not longer. Status String, 1 numeric character 0 = Order OK. 1 = Order not OK. kvarv_orderbelopp (remaining order amount) String, max. 9 numeric characters. The last two digits always signify öre. The order amount remaining after any credits. Note that the amount does not contain any demarcation to set off the öre. The last two positions represent öre. For example, SEK 265 is written as Kontrollsumma (Check sum) String, 32 characters. This string checks that no manipulation of the data has taken place during transmission. The string is constructed by joining the store ID, number, order number1, status 1, remaining amount1, order number2, status2, remaining amount2 in that order to a string without field demarcations. A pre-agreed secret word is added to the string. This string is then subjected to an MD5 hashing, which after transformation into a readable format produces a string of 32 characters. 14

15 Example <INPUT TYPE= hidden NAME= butikid VALUE= 1234 > <INPUT TYPE= hidden NAME= ordernummer VALUE= A > <INPUT TYPE= hidden NAME= status VALUE= 0 > <INPUT TYPE= hidden NAME= kvarv_orderbelopp VALUE= > <INPUT TYPE= hidden NAME= kontrollsumma VALUE= 5f4fe282d1f360b880d a0a1a8 > Note that if the order is not OK, there will be a zero in remaining order amount (kvarv-orderbelopp). This is done if we have been unable to retrieve it from the Bank s databases. The check sum above is calculated using a secret word = aaaabbbb. Error management If a technical error occurs, for example, the check sum from the company is not correct or there is some other error at the Bank, then the session is cancelled and the Bank ends the call. Help & Support For help and support for technical questions, for example in connection with set-up, send an to kundsupporten.backoffice@handelsbanken.se 15