4.7. Payment state queries

4.7.1. State query in HTML

The state of an unique payment can be checked with a HTML-form.

Webshop developers can implement a button next to an order to allow checking of the state of the payment for any order directly from Paytrail's service. This way the merchant can be sure whether the payment was successfully completed in case the information has not reached the webshop otherwise. This kind of situation can occur for example when customer closes the browser before returning to the webshop and the payment cannot be confirmed as paid with payment status query services provided by the payment method provider.

Table 4.12. Form field description

Variable nameDescriptionFormatMax lengthRequired/Optional
MERCHANT_IDMerchant ID is sent to the merchant after registration.N11R
ORDER_NUMBERThis is the same order number that was generated in the webshop and sent to the Payment Gateway.AN50R
AUTHCODEThe request AUTHCODE. The calculation of the AUTHCODE is described later.AN32R
VERSIONThe current version value is "2".N1R
CULTUREThe service is available in Finnish, Swedish and English. The valid values for this field are "fi_FI", "sv_SE" and "en_US".AN8O

Example 4.15. The state query HTML form

<form action="https://payment.paytrail.com/check-payment" method="post">
    <input name="MERCHANT_ID" type="hidden" value="..." />
    <input name="ORDER_NUMBER" type="hidden" value="..." />
    <input name="AUTHCODE" type="hidden" value="..." />
    <input name="VERSION" type="hidden" value="..." />
    <input name="CULTURE" type="hidden" value="..." />
    <input name="submit" type="submit" value="Check payment state" />

4.7.2. Calculating the AUTHCODE

AUTHCODE is calculated from a string which combines Merchant secret, Merchant ID and order number. All variables are separated by "&". Hash is calculated from this string using MD5, and the result is then transformed to a 32 character hexadecimal string and converted to upper case letters.

Example 4.16. Example of calculation

Table 4.13. Example of calculation

Field namevalue
Merchant secret6pKF4jkv97zmqBJ3ZL8gUw5DfT2NMQ

Combine previous fields:


Calculate MD5: eea431ef1c0a17d0045ab2ac39d118cf. Lower case letters to upper case: EEA431EF1C0A17D0045AB2AC39D118CF.