Paytrail Oyj! Channel interface API! Channel model! Channel model description! Interface description!

Transcription

1 Paytrail Oyj Channel interface API Channel model Channel model description The channel model of Paytrail enables combining multiple products from multiple vendors to be sold in a single payment through Paytrail s payment services. These vendors all have to be customers of Paytrail with an agreement to use the payment channel that is created for the vendors. Every product in the channel has one unambiguous vendor that will sell the product. Payment channel model enables defining a commission for each product in the payment channel. The channel can calculate the commission according to any defined formula. The formula is defined in the contract between Paytrail and the channel. Payment channel has to follow the formula defined in the contract. Paytrail charges a commission for every payment in the payment channel. The commission is defined in the contract between Paytrail and the channel. Payment channel has to ensure that commissions never exceed the sum of the payment packet. Vendors using a payment channel will see payments from the payment channel in Merchant s Panel. Vendors will only see their own products even if a payment packet includes products from several vendors. Interface description Common Channel model uses SSL secured address: Payment packet is sent to the service as a POST query. When a payment is completed, the customer will be redirected back to the address payment channel has defined as the return address. The parameters used to determine that payment has been successful are also sent to the return address. Fields to send The tables below describe the fields that should be sent to Paytrail s payment service. The given lengths for fields are maximum lengths. If the maximum lengths are exceeded payment will not be accepted. The format of the fields is N, F or AN. N stands for numerical value and F for decimal number. Decimal numbers are to be defined maximum with two decimals. Decimal delimiter is a dot. AN stands for alphanumeric value meaning that the value of the field can

2 include any characters. Fields can be sent using character sets UTF-8 or ISO Character sets cannot be mixed. Please notice No value for field should contain pipe character, the vertical bar. Pipe characters should be replaced by another character before data is sent to Paytrail s payment service. If special characters have to be used in the return address, we recommend to encode the return address URL (e.g. function urlencode in PHP). Especially pipe character has to be replaced with a string %C7. Table column Mandatory/Optional tells if field has to be sent or if it is optional. Especially field NOTIFY_ADDRESS is strongly recommended even if it is optional. Field Name Max. length Format Mandatory /optional Channel ID CHANNEL_ID 11 N M Order number ORDER_NUMBER 64 AN M Currency CURRENCY 3 AN M Return address / Successful payment Return address / Cancelled payment RETURN_ADDRESS 255 AN M CANCEL_ADDRESS 255 AN M Notify address NOTIFY_ADDRESS 255 AN M Interface version VERSION 2 N M Culture code CULTURE 5 AN O Preselected payment method METHOD_PRESELECT 2 AN O Authentication code AUTHCODE 32 AN M Payer s telephone number Payer s cellphone number Payer s address CONTACT_TELNO 64 AN O CONTACT_CELLNO 64 AN O CONTACT_ 255 AN M Payer s first name CONTACT_FIRSTNAME 64 AN M Payer s last name CONTACT_LASTNAME 64 AN M Payer s company CONTACT_COMPANY 128 AN O

3 Field Name Max. length Format Mandatory /optional Payer's street address CONTACT_ADDR_STREET 128 AN M Payer s zip code CONTACT_ADDR_ZIP 16 N M Payer s city CONTACT_ADDR_CITY 64 AN M Payer s country CONTACT_ADDR_COUNTRY 2 AN M Is VAT is included in price? INCLUDE_VAT 1 N M Amount of items ITEMS 8 N M Products in payment packet can be sent with recurring fields described below. Field Name Max. length Format Mandatory /optional Product name ITEM_TITLE[X] 255 AN M Product number ITEM_NO[X] 16 AN O Amount of products ITEM_AMOUNT[X] 10 F M Product price ITEM_PRICE[X] 10 F M Tax percent for product Merchant ID of product Product s channel commission class ID ITEM_TAX[X] 10 F M ITEM_MERCHANT_ID[X] 8 N M ITEM_CP[X] 10 F O Product s discount ITEM_DISCOUNT[X] 10 F O Product type ITEM_TYPE[X] 2 N O Description for fields Field Description Channel ID Order number Channel ID is an identifier given to the payment channel by Paytrail. Channel ID contains only numbers. (mandatory) Order number is a unique string for order. (mandatory)

4 Currency Field Return address / Successful payment Return address / Cancelled payment Notify address Description Currency of the payment. The only allowed value is EUR. (mandatory) After a successful payment customer will be redirected to return address. (mandatory) After cancelled or unsuccessful payment customer will be redirected to cancel address. (mandatory) After payment is marked as successful Paytrail will call notify address and send the same GET parameters as when directing customer to RETURN_ADDRESS after a successful payment. (mandatory) Interface version Version of payment interface. Channel interface is 1. (mandatory) Culture code Preselected payment method Authentication code Payer s telephone number Payer s cellphone number Payer s address Payer s first name Payer s last name Payer s company Payer s street address Payer s zip code Payer s city Culture affects the default language of Paytrail s payment service page as well as the format of the displayed sum. Possible values are fi_fi, sv_se and en_us. Default is fi_fi. (optional) For now this field is ignored. Nonetheless, this field has to be included as a blank string when calculating AUTHCODE value. Authentication code is a checksum calculated with MD5 algorithm. With authentication code we prevent the abuse of payments. Checksum is calculated from a string that contains all the information from the order and channel s certificate. See example below. (mandatory) Payer s telephone number. (optional) Payer s cellphone number. (optional) Payer s address. (mandatory) Payer s first name. (mandatory) Payer s last name. (mandatory) Payer s company. (optional) Payer s street address. (mandatory) Payer s zip code. (mandatory) Payer s city. (mandatory)

5 Field Payer s country Is VAT is included in price? Description Payer s country. The value follows the ISO standard and it contains two letters. For example, Finland is FI and Sweden is SE. It does not matter if the value is in lower or upper case. (mandatory) Do the prices in item rows include VAT or not. Value 1 means that VAT is included in given prices, value 0 means that given VAT has to be added to price. If your products are saved including VAT in your web shop, use value 1. If products are saved without VAT, use value 0. (mandatory) Amount of items Below is listed description for item row fields. Field Amount of item rows. The rows have to be included as described in the table below. (mandatory) Description Product name Product number Amount of products Free-formatted name for the product. (mandatory) Optional product number that is displayed in Merchant s Panel with the product. Using this field may help find the right product. (optional) If the order includes several same products this field can be used to determine amount of them. This means that same products do not need their own rows. (mandatory) Product price Tax percent for product Merchant ID of product Product s channel commission class ID Price for the product. If field INCLUDE_VAT has value 0, value for this field is price without VAT. If INCLUDE_VAT has value 1, value of this field is price including VAT. Price has to be always positive. Discounts for products can be sent with ITEM_DISCOUNT[X] field. (mandatory) VAT percentage used for products. (mandatory) One payment can contain products from several vendors. Every item row has to contain merchant ID of the product s vendor. (mandatory) Payment channel may have several commission classes. Every product can have their own commission class. This allows different prices for premium vendors or smaller commission class for more expensive products. Paytrail will deliver commission class IDs to payment channel. Commission class IDs are defined in the contract between Paytrail and payment channel. (mandatory)

6 Field Products discount Product type Description If product has a discount, this defines the discount percentage. The value can be between 0 and 100. Default value is 0. (optional) Type can be defined for every item row. Type 1 means normal product, 2 postage, and 3 processing cost. Default value is 1. (optional)

7 Handling of payment information After customer has paid the order he/she will be redirected to the address defined in the field RETURN_ADDRESS. If payment was cancelled or unsuccessful, customer will be directed to the address defined in the field CANCEL_ADDRESS. Field NOTIFY_ADDRESS can also be used. This address is called automatically when Paytrail confirms the payment. Typically notify address is called right before directing to the return address. It is, however, possible that customer will not come back to Paytrail after the payment. In these cases the payment will be confirmed with a delay of one bank day when the notify address will be called by Paytrail. The call for notify address contains the same GET parameters that are used when redirecting to return address. GET parameters used when redirecting to return and cancel addresses and when calling notify addresses are described below. Payment s validity has to be checked using GET parameters. Field Information Name 1. Order number ORDER_NUMBER 2. Timestamp TIMESTAMP 3. Payment signature PAID 4. Authentication RETURN_AUTHCODE Below are described the meanings for the fields. Field Description Order number Timestamp Payment signature Authentication This is the same order number that was sent to Paytrail by payment channel. Order number will be used to individualize each payment. Timestamp created by Paytrail. This is used for calculating the checksum. Timestamps are in UNIX format. Signature created by Paytrail. This is returned only with a successful payment. The checksum calculated by Paytrail. Payment channel can compare this against the checksum they have calculated. If the checksums match, payment information has been transferred correctly. The checksums may match even if the payment is cancelled or unsuccessful.

8 Calculating checksum The checksum is calculated as described below. 1. Create a string by combining the fields order number, timestamp, payment signature and merchant certificate in this order. Insert a pipe character between the fields. In case of an unsuccessful payment, the field payment signature will not be returned and it is not to be included in the string. 2. Calculate the checksum using an MD5 hash function on the created string. 3. The checksum is a 32-bit hexadecimal string. Replace lower case letters with upper case letters. Example of calculating the checksum Order number: Timestamp: Payment sign: F4SDGF23FS Channel certificate: Created string: F4SDGF23FS Calculated checksum: 7c597d787d71efbbec68275b5b9d13ef Checksum in upper case: 7C597D787D71EFBBEC68275B5B9D13EF If calculated checksum matches the value of RETURN_AUTHCODE, payment acknowledgment has arrived successfully.

9 Testing Test ID and channel certificate Channel model can be tested with ID and channel certificates shown below. Channel ID: 123 Channel certificate: Additionally, all sent products must use merchant ID Channel commission class ID is always 1 in testing. Example Below is an example of a form submit that sends payment order to Paytrail s payment service. <form action=" method="post"> <input name="channel_id" type="hidden" value="123"> <input name="order_number" type="hidden" value=" "> <input name="currency" type="hidden" value="eur"> <input name="return_address" type="hidden" value=" <input name="cancel_address" type="hidden" value=" cancel"> <input name="notify_address" type="hidden" value=" notify"> <input name="version" type="hidden" value="1"> <input name="culture type="hidden" value="fi_fi"> <input name="contact_telno" type="hidden" value=" "> <input name="contact_ " type="hidden" value="[email protected]"> <input name="contact_firstname" type="hidden" value="jane"> <input name="contact_lastname" type="hidden" value="doe"> <input name="contact_company" type="hidden" value="test Ltd"> <input name="contact_addr_street" type="hidden" value= Teststreet 1"> <input name="contact_addr_zip" type="hidden" value="43210"> <input name="contact_addr_city" type="hidden" value="helsinki"> <input name="contact_addr_country" type="hidden" value="fi"> <input name="include_vat" type="hidden" value="1" /> <input name="items" type="hidden" value="2"> <input name="item_title[0]" type="hidden" value="example product 1"> <input name="item_no[0]" type="hidden" value="12345"> <input name="item_amount[0]" type="hidden" value="1"> <input name="item_price[0]" type="hidden" value="10.00"> <input name="item_tax[0]" type="hidden" value="22.00"> <input name="item_merchant_id[0]" type="hidden" value="13466"> <input name="item_cp[0]" type="hidden" value="1"> <input name="item_discount[0]" type="hidden" value="0">

10 <input name="item_type[0]" type="hidden" value="1"> <input name="item_title[1]" type="hidden" value="example product 2"> <input name="item_no[1]" type="hidden" value="12346"> <input name="item_amount[1]" type="hidden" value="2"> <input name="item_price[1]" type="hidden" value="5.00"> <input name="item_tax[1]" type="hidden" value="22.00"> <input name="item_merchant_id[1]" type="hidden" value="13466"> <input name="item_cp[1]" type="hidden" value="1"> <input name="item_discount[1]" type="hidden" value="20.00"> <input name="item_type[1]" type="hidden" value="1"> <input name="authcode" type="hidden" value="62bd2cdba8ecdad9f290502c423eb16a"> <input type="image" src=" </form> The last field AUTHCODE is calculated as described below. Combine all the fields in the same order they appear at the form. Insert pipe character between the fields. If some field is not sent, insert a blank string in its value s place. This will result in two two or more pipe characters next to each other. The first field of the string has to be the channel certificate. AUTHCODE will be created from this string with MD5 function. The checksum will be a 32-bit hexadecimal string. Replace lower case letters with upper case letters. Please notice In this example character set UTF-8 is used. Paytrail supports character sets UTF-8 and ISO Calculation for AUTHCODE has to be done using same character set that is used when sending the form to Paytrail. Paytrail s service will detect the used character set and use the same character set when calculating the checksum. In the example above the values of fields are as described below. Channel certificate Channel ID 123 Order number Currency Return address / Successful payment Return address / Cancelled payment Notify address EUR Interface version 1 Culture code fi_fi Payer s telephone number

11 Payer s cellphone number Payer s address Payer s first name Payer s last name Payer s company [email protected] Jane Doe Test Ltd Payer s street address Teststreet 1 Payer s zip code Payer s city Payer s country Helsinki FI Is VAT is included in price? 1 Amount of items 2 Product #1 name Example product 1 Product #1 number Product #1 amount 1 Product #1 price Product #1 tax percent Product #1 merchant ID Product #1 channel commission class ID 1 Product #1 discount 0 Product #1 type 1 Product #2 name Example product 2 Product #2 number Product #2 amount 2 Product #2 price 5.00 Product #2 tax percent Product #2 merchant ID Product #2 channel commission class ID 1 Product #2 discount Product #2 type 1

12 The string used to calculate AUTHCODE is created by combining fields above EUR fi_fi [email protected] Jane Doe Test Ltd Teststreet Helsinki FI 1 2 Example product Example product MD5 checksum: d82d2738e6b0ce8852e240cf33e94de9 Checksum in upper case: D82D2738E6B0CE8852E240CF33E94DE9

13 Technical support Feel free to call our technical support on number or send an to