Bellow you can find detailed specification of transmissible and receivable data.

If it's available (there is PHP with required version in your server), we strongly advise to use libwebtopay library to generate requests and process callbacks.

Structure of request data

You should send data of the form in GET or POST method. Address: https://www.paysera.com/pay/

There are always 2 fields sent: data and sign.

Generating request fields from parameters

  1. All parameters are joined to URL-encoded string. For example:
    array('param1' => 'abc', 'param2' => 'Some string with symbols %=&')
    'param1=abc&param2=Some+string+with+symbols+%25%3D%26'
    
    In PHP language this is done by function http_build_query
  2. Result string is encoded in base64 encoding. For example:
    'param1=abc&param2=Some+string+with+symbols+%25%3D%26'
    'cGFyYW0xPWFiYyZwYXJhbTI9U29tZStzdHJpbmcrd2l0aCtzeW1ib2xzKyUyNSUzRCUyNg=='
    
    In PHP language this is done by function base64_encode
  3. In the result string symbols "/" are replaced with "_", and symbols "+" with "-". We get similar to base64 encoding, which is safe to send in URL without further processing. For example:
    'MViDYlV7V0iHR2w2OkJjRFFpY11hizJDhk+EZjl/'
    'MViDYlV7V0iHR2w2OkJjRFFpY11hizJDhk-EZjl_'
    
    In PHP language this is done by function str_replace or strtr.
  4. The final result string is signed - the sign parameter is generated. Algorithm to generate sign parameter:
    sign = md5(data + password)
    Here md5 is cryptographic hash function, data - encoded parameters, password - your project password.

Available request parameters

Parameter Length Necessary Description
projectid 11 Yes Unique project number. Only activated projects can accept payments.
orderid 40 Yes Order number from your system.
accepturl 255 Yes Full address (URL), to which the client is directed after a successful payment.
cancelurl 255 Yes Full address (URL), to which the client is directed after an unsuccessful payment or cancellation.
callbackurl 255 Yes Full address (URL), to which a seller will get information about performed payment.

Script must return text "OK". Only then our system will register, that information about the payment has been received.

If there is no answer "OK", the message will be sent 4 times (when we get it, after an hour, after three hours and after 24 hours).
version 9 Yes The version number of Paysera system specification (API).
lang 3 No It is possible to indicate the user language (ISO 639-2/B: LIT, RUS, ENG, etc.). If Paysera does not support the selected language, the system will automatically choose a language according to the IP address or ENG language by default.
amount 11 No Amount in cents the client has to pay
currency 3 No Payment currency (i.e USD, EUR, etc.) you want the client to pay in. If the selected currency cannot be accepted by a specific payment method, the system will convert it automatically to the acceptable currency, according to the currency rate of the day. Payamount and paycurrency answers will be sent to your website.
payment 20 No Payment type. If provided, the payment will be made by the method specified (for example by using the specified bank). If not specified, the payer will be immediately provided with the payment types to choose from. You can get payment types in real time by using WebToPay library.
country 2 No Payer's country (LT, EE, LV, GB, PL, DE). All possible types of payment in that country are immediately indicated to the payer, after selecting a country.
paytext 255* No Payment purpose visible when making the payment. If not specified, default text is used:
Payment for goods and services (for nb. [order_nr]) ([site_name]).

If you specify the payment purpose, it is necessary to include the following variables, which will be replaced with the appropriate values in the final purpose text:

  • [order_nr] - payment number.
  • [site_name] or [owner_name] - website address or company name.

If these variables are not specified, the default purpose text will be used.

Example of a payment purpose:

Payment for goods made to order [order_nr] in website [site_name].
p_firstname 255 No Payer's name. Requested in the majority of payment methods. Necessary for certain payment methods.
p_lastname 255 No Payer's surname. Requested in the majority of payment methods. Necessary for certain payment methods.
p_email 255 No Payer's email address is necessary. If the email address is not received, the client will be requested to enter it. Paysera system will inform the payer about the payment status by this address.
p_street 255 No Payer's address, to which goods will be sent (e.g.: Mėnulio g. 7 - 7). Necessary for certain payment methods.
p_city 255 No Payer's city, to which goods will be sent (e.g.: Vilnius). Necessary for certain payment methods.
p_state 20 No Payer's state code (necessary, when buying in USA). Necessary for certain payment methods.
p_zip 20 No Payer's postal code. Lithuanian postal codes can be found here. Necessary for certain payment methods.
p_countrycode 2 No Payer's country code. The list with country codes can be found here. Necessary for certain payment methods.
only_payments 0 No Show only those payment methods that are separated by commas.
disalow_payments 0 No Hide payment methods separated by comma.
test 1 No The parameter, which allows to test the connection. The payment is not executed, but the result is returned immediately, as if the payment has been made. To test, it is necessary to activate the mode for a particular project by logging in and selecting: "Manage projects" -> "Payment gateway" (for a specific project) -> "Allow test payments" (check).
time_limit 19 No The parameter indicating the final date for payment; the date is given in “yyyy-mm-dd HH:MM:SS” format. The minimum value is 15 minutes from the current moment; the maximum value is 3 days. Note: works only with certain payment methods.
personcode 255 No This parameter can be used for user authentication. If the user’s identification number is transferred, together with callback Paysera will return personcodestatus parameter, which will indicate whether the personal code corresponds to the transferred one.
developerid 11 No In case you are labeled as a developer in our system, you have to transfer this parameter in your installed project (projects). The value of the parameter - your unique user number.

* Final length may vary depending on payment type specification

Structure of the payment notification

Paysera sends the answer to your specified callbackurl. 3 additional GET parameters are added to the callbackurl:

  • data - encoded parameters from Paysera system. Same data coding algorithm is used as in generating a request for macro payments. To parse the parameters, 3 actions must be performed:
    1. Change the symbols "-" to "+", "_" to "/";
    2. Decode the string, using base64 encoding;
    3. Retrieve the array of parameters from the decoded string, which is an URL-encoded parameter string.
    Example in PHP language:
    $params = array();
    parse_str(base64_decode(strtr($_GET['data'], array('-' => '+', '_' => '/'))), $params);
    //use $params
  • ss1 - sign of data parameter, without using private-public key scheme. Sign algorithm:
    ss1 = md5(data + password)
  • ss2 - sign of data parameter, using RSA private-public key scheme with SHA-1 hashing function. Public Paysera key, which should be used to verify the signature, can be found at https://www.paysera.com/download/public.key

When you get the callback, you must check at least one signature before confirming the order. If there is a possibility, always (also) check the higher security ss2 signature.

Encoded response parameters

Parameter Description
projectid Unique project number. Only activated projects can accept payments.
orderid Order number from your system.
lang It is possible to indicate the user language (ISO 639-2/B: LIT, RUS, ENG, etc.). If Paysera does not support the selected language, the system will automatically choose a language according to the IP address or ENG language by default.
amount Amount in cents the client has to pay.
currency Payment currency (i.e USD, EUR, etc.) you want the client to pay in. If the selected currency cannot be accepted by a specific payment method, the system will convert it automatically to the acceptable currency, according to the currency rate of the day. Payamount and paycurrency answers will be sent to your website.
payment Payment type. If provided, the payment will be made by the specified method (for example by using the specified bank). If not specified, the payer will be immediately provided with the payment types to choose from. You can get payment types in real time by using WebToPay library.
country Payer's country (LT, EE, LV, GB, PL, DE). All possible types of payment in that country are immediately indicated to the payer, after selecting a country.
paytext Payment purpose visible when making the payment.
name Payer's name received from the payment system. Sent only if the payment system provides such.
surename Payer's surname received from the payment system. Sent only if the payment system provides such.
status Payment status:
  • 0 - payment has not been executed
  • 1 - payment successful
  • 2 - payment order accepted, but not yet executed (this status does not guarantee execution of the payment)
  • 3 - additional payment information
test The parameter, which allows to test the connection. The payment is not executed, but the result is returned immediately, as if the payment has been made. To test, it is necessary to activate the mode for a particular project by logging in and selecting: "Manage projects" -> "Payment gateway" (for a specific project) -> "Allow test payments" (check).
payment_country Country of the payment method. If the payment method is available in more than one country (international) – the parameter is not sent. The country is provided in the two-character (ISO 3166-1 alpha-2) format, e.g.: LT, PL, RU, EE.
payer_ip_country Country of the payer established by the IP address of the payer. The country is provided in two-character (ISO 3166-1 alpha-2) format, e.g.: LT, PL, RU, EE.
payer_country Country of the payer established by the country of the payment method, and if the payment method is international – by the IP address of the payer. The country is provided in the two-character (ISO 3166-1 alpha-2) format, e.g.: LT, PL, RU, EE.
p_email Payer's email address is necessary. If the email address is not received, the client will be requested to enter it. Paysera system will inform the payer about the payment status by this address.
requestid It is a request number, which we receive when the user presses on the logo of the bank. We transfer this request number to the link provided in the "callbackurl" field.
payamount Amount of the transfer in cents. It can differ, if it was converted to another currency.
paycurrency The transferred payment currency (i.e USD, EUR, etc.). It can differ from the one you requested, if the currency could not be accepted by the selected payment method.
version A version number of Paysera system specification (API).
account Account number from which payment has been made.
personcodestatus If you have provided personcode parameter when making the request, this parameter indicates whether the given personal code matches the real one. Possible values:
  • 0 - personal code is yet unknown
  • 1 - personal code matches
  • 2 - personal code does not match
  • 3 - personal code is unknown
If the personal code is unknown at the moment callback is made, another callback will be made with status parameter set to 3, as soon as the personal code will be known

Always check payment status - only status 1 means successful payment.
Also check whether the service for this payment has not yet been provided (by orderid parameter), whether the payment is not made for testing purposes (by status parameter), whether the amount and currency match the ones saved in the order.

Payment information in accepturl

Exactly the same parameters as in callback are transmitted to the provided accepturl when redirecting the user. Almost always, at that moment, payment is not yet made, so status will probably be 2. Always check, whether the service is provided only once for the same payment - if the user refreshes the accepturl page, your system will receive the payment information again.