WEB api

Terms used

Customer redirection and Inter-Server Messaging

The data that travels between the OPAY system and the Merchant's website can follow two routes:

1. As the Customer travels from the Merchant's website to OPAY and then from OPAY back to the Merchant's website, specific data meant for the destination website also travels alongside. This method of data transfer is termed as Customer Redirection, since the Customer is redirected from one page to another (with data transmitted using the HTTP POST or GET method).
2. The two servers communicate information directly with each other, wherein one server sends a distinct message containing data, and the other server receives it (using the HTTP POST method). This approach will be termed as Inter-Server Messaging.

Names of Systematic Payment Methods

When providing payment method names in programming examples or any other technical specifications, please be aware that we kindly request you to provide the systematic payment method name.

Payment methods are categorized into groups. The group name is reflected in the systematic payment method name. If the specification allows for the indication of more than one payment method, instead of listing all the individual payment methods within the group, you can specify only the systematic name of the group. When the group name is provided, the system identifies it as if all the payment methods specified within the group were listed.

Below is a list of payment method groups along with the corresponding payment methods they include. The systematic payment method names are provided in parentheses next to the name.

1. Payment by online banking, Lithuania (banklink)
   1. Swedbank bank (banklink_swedbank)
   2. SEB bank (banklink_seb)
   3. Luminor bank (banklink_dnb)
   4. Citadele bank (banklink_citadele)
   5. Šiaulių bank (banklink_sb)
   6. Medicinos bank (banklink_medbank)
2. Payment by Payment initiation, Lithuania (pis)
   1. Swedbank bank (pis_swedbank)
   2. SEB bank (pis_seb)
   3. Luminor bank (pis_dnb)
   4. Citadele bank (pis_citadele)
   5. Šiaulių bank (pis_sb)
   6. Medicinos bank (pis_medbank)
   7. Revolut (pis_revolut)
   8. Paysera (pis_paysera)
   9. LKU (pis_lku)
   10. N26 (pis_n26)
   11. Wise (pis_wise)
3. Payment by Payment initiation, Latvia (pis)
   1. Swedbank bank (pis_swedbank.lv)
   2. SEB bank (pis_seb.lv)
   3. Luminor bank (pis_luminor.lv)
   4. Citadele bank (pis_citadele.lv)
   5. Rietumu bank (pis_rietumu.lv)
   6. Revolut (pis_revolut)
   7. Paysera (pis_paysera)
   8. LPB (pis_lpb.lv)
   9. N26 (pis_n26.lv)
   10. Wise (pis_wise.lv)
4. Payment by Payment initiation, Estonia (pis)
   1. Swedbank bank (pis_swedbank.ee)
   2. SEB bank (pis_seb.ee)
   3. Luminor bank (pis_luminor.ee)
   4. Citadele bank (pis_citadele.ee)
   5. LHV bank (pis_lhv.ee)
   6. Revolut (pis_revolut)
   7. Paysera (pis_paysera)
   8. Coop (pis_coop.ee)
   9. LHV (pis_lhv.ee)
   10. N26 (pis_n26.ee)
   11. Wise (pis_wise.ee)
5. Card payment (card)
6. Payment by bank transfer (banktransfer)
7. Cash payment, Lithuania (cash)
   1. Perlas terminals (cash_perlas)
8. Installment payment, Lithuania (financing)
   1. General Financing (financing_gf)

General Guideline for Non-Mandatory Parameters

In cases where an optional parameter is either omitted or submitted with an empty value:

• If the parameter has a predefined standard value indicated in the table, it will be treated as if the parameter has been provided with the standard value.

When an optional parameter is submitted with a value (non-empty):

• The values of non-mandatory parameters must adhere to possible values (if such values are specified in the table), value types, and maximum value length requirements. Otherwise, an error will be assumed, and the parameter value will default to the standard value.
• In situations where optional parameters encounter errors, their values will be automatically reset to defaults, ensuring an uninterrupted payment process. The Customer will not receive error notifications, whereas the Merchant will be alerted about these issues via email.

General Guideline for Mandatory Parameters

• Values of mandatory parameters must correspond to potential values (if specified in the table), value types, and maximum value length requirements. Otherwise, an error will be triggered.
• Errors in mandatory parameters deactivate the display of the payment method(s) that necessitate this parameter.
• If there is an absence of any mandatory parameters to fulfill the requirements of at least one payment method, the further execution is suspended. The Customer will encounter a page presenting error detail, and the Merchant will be notified through email.

Data Sent by the Merchant

The amount of data (parameters) transmitted by the Merchant during Customer redirection to OPAY differs depending on the Payment Services utilized by the Merchant, as defined by the Agreement between OPAY and the Merchant. With each request, the Merchant can specify the preferred payment methods (desired Payment Services) for that specific transaction, within the limits outlined by the Agreement's Payment Services. Certain parameters remain uniform across all payment methods. Please pay attention to the parameters necessary and marked as mandatory for each payment method (Payment Service).

The data sent to the system must be encoded in UTF-8. The data is transmitted using the HTTP POST or GET method to the address https://gateway.opay.lt/pay/.

Explanation of Columns in Table No. 1:

• Parameter: Refers to the name of the parameter.
• Max Length: pecifies the maximum character length allowed for the parameter's assigned value. The character count of the assigned value cannot exceed the value provided in this column.
• Value Type: str – for text (including letters, numbers, and other UTF-8 encoded symbols, unless specific possible values are explicitly defined in the parameter description), int – for integer (accepting only numbers, without decimals or commas).
• Default Value: In cases where the parameter is either not supplied or submitted with incorrect data, the system will consider the default value specified in this column (if provided).
• Banklink, Card, Financing, Mobilewallet: Pertains to parameters required for payment methods belonging to these groups.
• Banktransfer, Cash. Refers to parameters needed for payment methods under these groups.
• Mandatory: Indicating a parameter as mandatory means that if it's provided with incorrect data or omitted, the associated payment method won't be displayed to the Customer. Note the correlation or absence of correlation (e.g., Banklink and Banktransfer) in the columns marked as mandatory. It's worth noting that due to an error, there might be insufficient mandatory parameters for the Banklink payment method, yet there might be an adequate number for the Banktransfer payment method.
• Description: This column offers a detailed explanation or commentary about the parameter.

Data can be transmitted as a single parameter. When sending data in this manner, the information must be concatenated into a single line, then converted into base64 encoding and transmitted as the sole parameter named encoded. For more comprehensive details, refer to the section on Data Encoding to mitigate potential distortions.

Table No. 1

Description of Data Sent by the Merchant (HTTP POST or GET parameters).

Data Received by the Merchant

Parameter data is encoded in UTF-8.

The parameters sent to the Merchant must be combined into a single parameter named encoded. These parameters should be joined into a single line and then encoded using base64. For a more comprehensive understanding, please refer to the section Data Encoding to Prevent Potential Distortions, which helps prevent any potential data distortion.

The OPAY server may resend the same message, so the Merchant must verify whether they have already received such a message before processing it.

In the case of a successful payment (status = 1), the parameter p_token will reflect this status.

If the Merchant receives a duplicate message indicating a successful payment (status = 1), and the order_nr parameter value matches previously received messages, but the p_token parameter value differs, this indicates distinct payments for the same cart of items. The order_nr parameter corresponds to the order/cart number assigned by the Merchant's system.

The Merchant must carefully inspect the value of the status parameter. As new message types (status values) may emerge in the future, the Merchant's server should exclusively respond to messages with known status parameter values.

It is of utmost importance for the Merchant to confirm whether the payment amount and currency match those specified in the request to OPAY. This step is essential due to instances where the Customer might incorrectly input values when using certain payment methods (e.g., Bank Transfer).

The successful payment message sent to the Merchant includes the currency (parameter currency) and amount (parameter amount) that the Merchant sent to OPAY, as well as the currency (parameter p_currency) and amount (parameter p_amount) that the Customer paid. These parameters should be aligned otherwise OPAY will also notify the Merchant via email about it. However, it is crucial for the Merchant's system to independently identify discrepancies and execute appropriate actions.

Once OPAY forwards a response to the Merchant's provided inter-server communication URL (parameter web_service_url), the Merchant's server should respond by acknowledging the receipt. Specifically, the Merchant's system must return the text OK. OPAY does not take into consideration HTTP headers (e.g., Status or Content-Type), but exclusively validates the content to ascertain an OK response. The OPAY server will await this response for a duration of 3 seconds after dispatching the message.

If OPAY does not receive a response or does not receive an OK response after multiple attempts, it will cease sending the message again. This occurs after four consecutive attempts, with the second attempt taking place after 1 minute, the third after 5 minutes, and the fourth after 1 hour.

In the event that OPAY fails to receive the correct response after the fourth attempt, the automated retransmission of the message will cease.

Table No. 2

Description of Received Parameters.

The parameters show_channels and hide_channels

By default (without using these parameters), the OPAY system will present all the payment methods agreed upon in the OPAY and Merchant Agreement.

Using the show_channels parameter, you can specify the precise payment methods that should be shown to the Customer on the OPAY payment page (payment method names are separated by commas).

With the hide_channels parameter, you can indicate which payment methods should not be displayed to the Customer on the OPAY payment page (payment method names are separated by commas).

The available payment methods in the OPAY system are detailed in the section Names of Systematic Payment Methods. Payment methods are organized into groups, each representing a specific payment method.

For instance, in the case of the payment method group banklink, it can be further divided into individual banks with abbreviations like banklink_swedbank, banklink_seb, banklink_dnb, banklink_danske, banklink_citadele, banklink_sb, banklink_medbank. In the case of banklink payments, you can specify not only the payment method as a group but also individual banks. Each bank within the banklink category is treated as a distinct payment method, so the system distinguishes between banklink and banklink_seb.

To avoid listing all individual banks, you can use banklink as shorthand. However, if needed, you can explicitly list specific individual payment methods like this: banklink_<bank_system_name>, banklink_<bank_system_name>...

Order of Parameter Value Processing

The OPAY system follows a specific sequence when processing the parameters show_channels and hide_channels. Firstly, the system examines the value of show_channels to determine the payment methods that should be presented to the Customer. In case no specific values are provided within the show_channels parameter, the system defaults to displaying all the payment methods agreed upon in both the OPAY and Merchant Agreement.

Examples when the payment methods of Online Banking (banklink) and Bank Transfer (banktransfer) are agreed upon in the Agreement between OPAY and the Merchant:

• In hide_channels, specific values are set: banklink_swedbank, banklink_seb

  In such a case, the OPAY system will exhibit the banktransfer payment method alongside the banklink payment method, excluding SWEDBANK and SEB.

• In show_channels, certain values are specified: banklink_swedbank, banklink_seb

  Here, only the banklink payment method will be displayed, providing the option to transact using the services of SWEDBANK and SEB banks.

• Within hide_channels, the value is defined as: banklink

  In this instance, solely the banktransfer payment method will be showcased.

• For hide_channels, values are assigned: banklink, banktransfer

  This scenario leads to an error since the Merchant requests the system not to display any payment methods. The Merchant will be notified of this situation via email, while all the payment methods agreed upon in both the OPAY and Merchant Agreement will be visible to the Customer.

Parameter time_limit

The parameter time_limit is designed to set a time limit within which a payment must be completed. If the payment is not finalized within this specified time frame, the Merchant's website will automatically receive a notification indicating the unsuccessful payment (status = 0).

In the section titled Minimum Time Required for Payment the table provides the minimum time intervals that can be assigned to specific payment methods.

Taking the Merchant's provided time into consideration, the OPAY system will display to the Customer only those payment methods for which the minimum permissible time in minutes is equal to or less than the time specified by the Merchant.

If a time value smaller than the minimum allowable duration for a specific payment method is provided, the Merchant will be notified of the error via email, while the Customer will be presented with the payment method that has the minimum allowable time (or multiple payment methods with the same minimum time). The time_limit parameter is closely intertwined with the show_channels and hide_channels parameters. Therefore, in this scenario, the system, in its quest for the payment method with the shortest time, will initially verify whether the Merchant has specified preferred payment methods for this transaction using the show_channels and/or hide_channels parameters. If the Merchant has done so, the system will prioritize seeking the payment method with the shortest time from the Merchant's designated options. If the Merchant has not defined such preferences, the system will seek out the payment method from all the stipulated payment methods in both the OPAY and Merchant Agreement.

Table of Minimum Time Required for Payment

This table provides the time limits in minutes set for each payment method. These time limits, as specified in the time_limit parameter, ensure that the corresponding payment method is displayed to the Customer.

Data Encoding to Prevent Potential Distortions

As the transmitted data contains not only Latin characters but also other characters, it's vital to use the correct character encoding to ensure that the message reaches the recipient without any distortions. The success of delivering the message accurately relies on the Customer‘s internet browser correctly interpreting all symbols. There's a potential risk of data distortion, which could lead to the entire data packet being perceived as incorrect (not matching the digital signature). The level of browser sophistication directly correlates with the probability of errors occurring.

We handle this situation in the following manner:

We encode the data to be sent using the base64 encoding method.

We are compiling a complete data package intended to be sent to OPAY. Let's consider this as an associative array where the index denotes the parameter name and the value represents the parameter value. We convert this array into a URL-encoded string following the RFC 1738 standard. Subsequently, we transform the URL-encoded string into a base64-encoded string. Lastly, we manipulate the characters within the resulting string:

• + to -
• / to _
• = to ,

We decode the obtained data.

When decoding the value of the encoded parameter, we carry out the reverse steps compared to the encoding process.

Digital Data Signing

When exchanging data, we use two methods of signing, either:

• Symmetric signing, where both parties use the same password for signing and verification.

  Example of the signing password:
  33cec89hjab1d77b10d21fba67528g5h

• Asymmetric signing, where parties generate private keys, use them to generate SSL certificates, and exchange these certificates. They use private keys for data signing and the Partner's certificate for signature verification (after receiving data from the Partner).

  Example of an SSL certificate:

  

Order of Combining Parameters into a Unified String (Signing / Verification Line)

The parameters (data) that you send to or receive from OPAY will be arranged in the order determined by the sending party. Here's an example in PHP language if you were to prepare to send a request with three parameters:

When sending these parameters using the HTTP POST method, they could be combined into a string like this (the order of parameter arrangement is not important):

When signing parameters or verifying their signature, the parameters should also be concatenated into a single string, but in a different way than in an HTTP POST parameter string. There is no equal sign (=) between the parameter name and its value, and the parameters are not separated by an ampersand (&) symbol. Parameter names are combined with their values into a single long word - string. Special and non-ASCII characters in this string are not replaced with their equivalents (as done in URL encoding), unlike in an HTTP POST string.

Example of the string:

Symmetric Signing and Signature Verification

Signing

When signing parameters, a signing string must be generated from all the prepared parameters for transmission (excluding the parameters password_signature and rsa_signature).

For symmetric signing, the signing process involves combining the signing string and the signing password into a single line, which is then hashed using the md5 algorithm.

The acquired symmetric signature is included as the password_signature parameter among the prepared parameters intended for transmission to OPAY. It is recommended that before sending the prepared parameters to OPAY, the parameters should also be encoded and sent as a single encoded parameter (refer to the section Data Encoding to Prevent Potential Distortions).

Signature Verification

The signature is verified by forming a signature verification line from all received parameters (excluding the parameters password_signature and rsa_signature). OPAY sends the parameters encoded into a single parameter called encoded, so to obtain the desired parameters, the value of the encoded parameter needs to be decoded (Refer to the section Data Encoding to Prevent Potential Distortions).

We sign the signature verification line, and then compare the obtained result with the value of the received parameter password_signature. If the values match, authentication is successful.

Asymmetric Signature and Signature Verification

Generation of Private Key and SSL Certificate

To generate these keys, OPAY suggests using OpenSSL software (https://www.openssl.org/).

The private key is generated using the command line by entering the command:

openssl genrsa -out privkey.pem 2048

In the current directory, a text file named privkey.pem will be generated, containing the private key. The number 2048 in the command signifies the length of the key in bits. According to security requirements in effect today, this is the shortest recommended key length.

An SSL certificate is generated by executing the following command at the command line:

In the command, the filename of the private key file privkey.pem is specified. Also, the name of the text file where the SSL certificate should be created and written to cacert.pem is indicated. The number 3650 signifies the number of days the certificate should be valid from its generation. After this period, a new certificate should be generated and provided to OPAY. Once the certificate expires, the OPAY system will continue to validate the requests sent by the Merchant with the expired certificate. The expiration of the certificate does not have any technical impact. The decision of setting the certificate's validity period and when to renew the certificate is made by the Merchant.

When entering the command for SSL certificate generation, you will be prompted to provide your company's details. For example:

Signing

When signing parameters, a signing string needs to be formed by taking all the prepared sending parameters (excluding the parameters password_signature and rsa_signature) and signing it.

Received asymmetric signature is added as the rsa_signature parameter to the prepared sending parameters that are sent to OPAY. It is preferable that before sending the prepared parameters to OPAY, the parameters are encoded and sent as a single encoded parameter (refer to the section Data Encoding to Prevent Potential Distortions).

Signature Verification

The signature is verified from all received parameters (excluding parameters password_signature and rsa_signature) by forming a line intended for signature verification. OPAY sends the parameters encoded into a single parameter called encoded, therefore, to retrieve the desired parameters, the encoded parameter value needs to be decoded (Refer to the section Data Encoding to Prevent Potential Distortions).