5.4. Receiving the Payment Receipt

5.4.1. Introduction

After the payment has been successfully completed, the customer is redirected to the URL defined in the previous stage (RETURN_ADDRESS). If the payment was cancelled, the customer is directed to the cancelled payment URL (CANCEL_ADDRESS).

The notification address (NOTIFY_ADDRESS) is called when Paytrail marks the payment as completed. Typically this happens within a few minutes after redirecting the customer to RETURN_ADDRESS. If the customer does not return to Paytrail's service from the bank's service, the information on successful payment will not be immediately available. In this case NOTIFY_ADDRESS will be called immediately when that information has arrived. Usually the information arrives within 24 hours. NOTIFY_ADDRESS call includes same GET-parameters as redirecting to RETURN_ADDRESS does.

The receipt carries unique return information that is used to verify the validity of the receipt and that the payment was actually successful. Return authentication hash is compared to the hash calculated by the webshop and if the values match, the payment receipt was not tampered.

In return authentication hash calculation, fields are joined using the "|" character (pipe, vertical bar) as separator. Merchant hash is appended to the string. When the payment is not successful, only fields 1, 2 and 5 are returned, and only fields 1, 2 and merchant hash are used in hash calculation.

Table 5.12. Receipt contains these fields

FieldVariable name
Order numberORDER_NUMBER
Time stamp of transactionTIMESTAMP
Paid Transcation IDPAID
Payment methodMETHOD
Return authentication hashRETURN_AUTHCODE


Table 5.13. Field explanations

FieldExplanation
Order numberThis is the same order number that was generated in the webshop and sent to the Payment Gateway
Timestamp of transaction Timestamp generated by the Payment Gateway that is used to calculate the return authentication hash. Timestamp is in UNIX format, i.e. seconds from 1/1/1970.
Paid Transaction ID Paid Transcation ID number is generated by the Payment Gateway. It is used to verify the validity of a successful payment. If no Paid Transcation ID is received, the payment has not been completed.
Payment method Used payment method as an integer id. This is not returned if the payment was not succesful. The following payment methods are currently possible:

Table 5.14. Possible values for payment method

1Nordea
2Osuuspankki
3Danske Bank
5Ålandsbanken
6Handelsbanken
9Paypal
10S-Pankki
11Klarna, Invoice
12Klarna, Instalment
18Jousto
30Visa
31MasterCard
34Diners Club
35JCB
36Paytrail account
50Aktia
51POP Pankki
52Säästöpankki
53Visa (Nets)
54MasterCard (Nets)
55Diners Club (Nets)
56American Express (Nets)
60Collector Bank
61Oma Säästöpankki

Return authentication hash Return authentication hash is a checksum value which is compared to one calculated in webshop. If the checksum matches the calculated one, the payment has been completed and the information has not been modified after sending. The hash may be identical in both successful and failed transactions.


5.4.2. Authcode calculation

Table 5.15. Example of calculation

Order number15153
Timestamp of transaction1176557554
Paid Transaction IDF4SDGF23FS
Payment method1
Merchant authentication hash6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ


Combining these fields using the "|" character as separator, the following string is formed: 15153|1176557554|F4SDGF23FS|1|6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ

Calculating the MD5 hash of this string, we get: 191fae904a0b9a57ca30a35c715abaf9

Translating lower case to upper case: 191FAE904A0B9A57CA30A35C715ABAF9

If the calculated hash equals the one received from the Payment Gateway (RETURN_AUTHCODE), the receipt is correct.