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:!
https://payment.paytrail.com/channel-payment!
!
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
include any characters. Fields can be sent using character sets UTF-8 or ISO-8859-1. 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 255 AN M Return address / Cancelled payment 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 CONTACT_TELNO 64 AN O Payer’s cellphone number CONTACT_CELLNO 64 AN O Payer’s email address CONTACT_EMAIL 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
!
Products in payment packet can be sent with recurring fields described below.!
!
!
!
Description for fields!
!
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
Field Name Max.
length
Format Mandatory /optional
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 ITEM_TAX[X] 10 F M Merchant ID of product ITEM_MERCHANT_ID[X] 8 N M Product’s channel commission class ID ITEM_CP[X] 10 F O
Product’s discount ITEM_DISCOUNT[X] 10 F O
Product type ITEM_TYPE[X] 2 N O
Field Description
Channel ID Channel ID is an identifier given to the payment channel by Paytrail. Channel ID contains only numbers. (mandatory) Order number Order number is a unique string for order. (mandatory)
Currency Currency of the payment. The only allowed value is EUR. (mandatory)
Return address / Successful payment
After a successful payment customer will be redirected to return address. (mandatory)
Return address / Cancelled payment
After cancelled or unsuccessful payment customer will be redirected to cancel address. (mandatory)
Notify address 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 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)
Preselected payment method
For now this field is ignored. Nonetheless, this field has to be included as a blank string when calculating AUTHCODE value. Authentication code 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
Payer’s telephone number. (optional)
Payer’s cellphone number
Payer’s cellphone number. (optional)
Payer’s email address
Payer’s email address. (mandatory)
Payer’s first name Payer’s first name. (mandatory) Payer’s last name Payer’s last name. (mandatory) Payer’s company Payer’s company. (optional) Payer’s street
address
Payer’s street address. (mandatory)
Payer’s zip code Payer’s zip code. (mandatory) Payer’s city Payer’s city. (mandatory)
!
Below is listed description for item row fields.!
!
Payer’s country Payer’s country. The value follows the ISO-3166-1 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)
Is VAT is included in price?
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 Amount of item rows. The rows have to be included as described in the table below. (mandatory)
Field Description
Field Description
Product name Free-formatted name for the product. (mandatory)
Product number Optional product number that is displayed in Merchant’s Panel with the product. Using this field may help find the right product. (optional)
Amount of products 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 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)
Tax percent for product
VAT percentage used for products. (mandatory)
Merchant ID of product
One payment can contain products from several vendors. Every item row has to contain merchant ID of the product’s vendor. (mandatory)
Product’s channel commission class ID
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.
!
!
Products discount If product has a discount, this defines the discount percentage. The value can be between 0 and 100. Default value is 0. (optional)
Product type Type can be defined for every item row. Type 1 means normal product, 2 postage, and 3 processing cost. Default value is 1. (optional)
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.!
!
!
Below are described the meanings for the fields.!
!
!
Field Information Name
1. Order number ORDER_NUMBER
2. Timestamp TIMESTAMP
3. Payment signature PAID
4. Authentication RETURN_AUTHCODE
Field Description
Order number This is the same order number that was sent to Paytrail by payment channel. Order number will be used to individualize each payment.
Timestamp Timestamp created by Paytrail. This is used for calculating the checksum. Timestamps are in UNIX format.
Payment signature Signature created by Paytrail. This is returned only with a successful payment.
Authentication 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.
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:! ! 123456! Timestamp:!! ! 1176557554! Payment sign:! ! F4SDGF23FS! Channel certificate:! 123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789 012345678901234567890123456789012345678!
Created string:! 123456 |1176557554|F4SDGF23FS| 123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789 012345678901234567890123456789012345678!!
Calculated checksum: 7c597d787d71efbbec68275b5b9d13ef!
!
Checksum in upper case: 7C597D787D71EFBBEC68275B5B9D13EF!
!
If calculated checksum matches the value of RETURN_AUTHCODE, payment acknowledgment has arrived successfully.!
Testing!
!
Test ID and channel certificate!
!
Channel model can be tested with ID and channel certificates shown below.!
!
Channel ID: 123! Channel certificate: 123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789 012345678901234567890123456789012345678!!
Additionally, all sent products must use merchant ID 13466.!
!
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="https://payment.paytrail.com/channel-payment" method="post">!
<input name="CHANNEL_ID" type="hidden" value="123">!
<input name="ORDER_NUMBER" type="hidden" value="12345678">!
<input name="CURRENCY" type="hidden" value="EUR">!
<input name="RETURN_ADDRESS" type="hidden" value="https://www.example.com/ok">!
<input name="CANCEL_ADDRESS" type="hidden" value="https://www.example.com/ cancel">!
<input name="NOTIFY_ADDRESS" type="hidden" value="https://www.example.com/ notify">!
<input name="VERSION" type="hidden" value="1">!
<input name="CULTURE” type="hidden" value="fi_FI">!
<input name="CONTACT_TELNO" type="hidden" value="+35812345678">!
<input name="CONTACT_EMAIL" 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_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="https://ssl.paytrail.com/logo/payhere_fin.jpg">!
</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-8859-1. 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 12345678901234567890123456789012 34567890123456789012345678901234 56789012345678901234567890123456 78901234567890123456789012345678 Channel ID 123 Order number 12345678 Currency EURReturn address / Successful payment https://www.example.com/ok Return address / Cancelled payment https://www.example.com/cancel Notify address https://www.example.com/notify
Interface version 1
Culture code fi_FI
Payer’s cellphone number +35812345678
Payer’s email address [email protected] Payer’s first name Jane
Payer’s last name Doe Payer’s company Test Ltd Payer’s street address Teststreet 1 Payer’s zip code 43210
Payer’s city Helsinki
Payer’s country FI
Is VAT is included in price? 1
Amount of items 2
Product #1 name Example product 1 Product #1 number 12345
Product #1 amount 1
Product #1 price 10.00 Product #1 tax percent 22.00 Product #1 merchant ID 13466 Product #1 channel commission class ID 1 Product #1 discount 0
Product #1 type 1
Product #2 name Example product 2 Product #2 number 12346
Product #2 amount 2
Product #2 price 5.00 Product #2 tax percent 22.00 Product #2 merchant ID 13466 Product #2 channel commission class ID 1 Product #2 discount 20.00
!
The string used to calculate AUTHCODE is created by combining fields above.!
!
123456789012345678901234567890123456789012345678901234567890123456789012 34567890123456789012345678901234567890123456789012345678|123|12345678| EUR|https://www.example.com/ok| https://www.example.com/cancel|https://
www.example.com/notify|1|fi_FI||+35812345678||[email protected]|Jane|Doe|Test Ltd|Teststreet 1|43210|Helsinki|FI|1|2|Example product 1|12345|1|10.00|22.00|13466|1|0|1| Example product 2|12346|2|5.00|22.00|13466|1|20.00|1!
!
MD5 checksum:!
d82d2738e6b0ce8852e240cf33e94de9!
!
Checksum in upper case:!
D82D2738E6B0CE8852E240CF33E94DE9!
!
Technical support!
!
Feel free to call our technical support on number +358 207 1818 31 or send an email to [email protected].!
