PHP Library


puzzle icon

Download the most recent version of the library (v1.3.0).

The library's minimum supported PHP version is 5.3.0.


Library API

Methods for Setting the Signature Mode When Sending and Receiving Data to/from OPAY

First and foremost, the existence of a private key with a certificate is verified. If not available, then the presence of a signature password is checked. Therefore, if you configure both options, the process will employ asymmetric signing/verification using a private key and certificate.

void setMerchantRsaPrivateKey(string $merchantRsaPrivateKey)

Method for setting the Merchant's Private Key. Used in conjunction with the setOpayCertificate method.

void setOpayCertificate(string $opayCertificate)

Method for setting the OPAY Certificate. Used in conjunction with the setMerchantRsaPrivateKey method.

void setSignaturePassword(string $signaturePassword)

Method for setting the OPAY provided signature password. Used in place of setMerchantRsaPrivateKey and setOpayCertificate.

int getTypeOfSignatureIsUsed()

The method returns the signature algorithm that will be used when sending data to OPAY.

Possible return values:

  • OpayGateway::SIGNATURE_TYPE_PASSWORD
  • OpayGateway::SIGNATURE_TYPE_RSA

Methods used for sending a payment request

array signArrayOfParameters(array $parametersArray)

The method adds an additional array element to the associative $parametersArray , using the index name rsa_signature or password_signature (depending on the chosen signature method). The value of this element is a digital signature that authenticates the structure of this array.

string generateAutoSubmitForm(string $url, array $parametersArray[, boolean $sendEncoded = true])

This method is used to generate an HTML document containing a form (<form>), along with its parameters. The form is constructed with the parameters that are prepared to be sent via the POST method to the address provided in the $url parameter. The HTML document also includes a JavaScript fragment that automatically submits the form. When this HTML document is displayed in a browser, it triggers a redirection to the specified address along with the data sent using the POST method.
  • $url - the full HTTPS address along with the specified protocol.
    For example: https://gateway.opay.lt/pay/
  • $parametersArray - an array of parameters to be sent.
    The associative index of the array represents the parameter name, and the value represents the parameter value.
  • $sendEncoded - if the valueTRUE is specified, then all parameters will be compressed and sent as a single parameter named encoded.

string convertArrayOfParametersToEncodedString(code $parametersArray)

This method converts an array of parameters into an encoded string, which can be sent to OPAY as a POST/GET parameter named encoded. If you are using the generateAutoSubmitForm function with the $sendEncoded parameter set to TRUE, then you no longer need to use the convertArrayOfParametersToEncodedString function additionally.

Methods used for handling incoming requests (notifications) from OPAY about payments

array convertEncodedStringToArrayOfParameters(string $encodedString)

The method converts an encoded string (provided as the encoded parameter) into an array of parameters.

boolean verifySignature(array $parametersArray)

The function verifies whether the information of the signed $parametersArray array is authentic and whether the correct key has been used to sign this information. The $parametersArray array is considered signed when it contains a member with an index named rsa_signature or password_signature.

Methods used for communication with OPAY web services

array webServiceRequest(string $url, array $parametersArray[, boolean $sendEncoded = true])

Method for communicating with OPAY web services and returning web service responses:
  • $url - full HTTPS address along with the specified protocol.
    Example: https://gateway.opay.lt/pay/
  • $parametersArray - an array of parameters to be sent.
    The associative index of the array represents the parameter name, and the value represents the parameter value.
  • $sendEncoded - If the value TRUE is specified, then all parameters will be compressed and sent as a single parameter named encoded.

Library File Structure

The library consists of several files that always need to be kept together. You should include the file opay_8.1.gateway.inc.php, in your code, which will make the OpayGateway class accessible.

The file opay_8.1.gateway.class.<version_number>.php is the controlling class OpayGateway for communication with OPAY according to the OPAY_8.1 standard.

When OPAY updates this file, the version number of the file changes. This allows OPAY to make improvements to certain algorithms or fix possible errors in the future.

Files with names ending in .interface.php describe the main methods (functions) for your use.

Interfaces are used to ensure that when you update the OPAY library file (opay_8.1.gateway.class.v<class_version>.php) to a newer version, the methods you use in your scripts, as described in the interfaces, remain unchanged.


General Principles of Using the Library

Before you begin using the methods of the OpayGateway class designed for communication with OPAY, you need to establish the method by which all your requests will be signed.

Two signing principles are possible (either one or the other):

  • Symmetric signing. When both parties use the same OPAY-provided signature password for both signing and signature verification.
  • Asymmetric signing. When parties generate private keys, use them to create SSL certificates, and exchange these certificates. Both parties use their private keys for data signing, while for signature verification (upon receiving data from the partner), they use the partner's certificate.

 


Redirecting the Buyer to the OPAY Payment Page

This example demonstrates how to redirect the Customer to the OPAY payment page with the minimum required parameters. You need to fill in the example with your own data.

If you have the Customer’s email address, provide it using the parameter c_email, and the Customer won't need to enter it again on the OPAY payment page.

If you have the Customer's mobile phone number, provide it using the parameter c_mobile_nr. Then, for a Customer making a mobile wallet payment, they won't need to enter it again.


Redirecting the Customer directly to the bank

Directing the Customer directly to the bank or another payment method is exactly the same as redirecting the Customer to the OPAY payment page, with the only difference being that you need to provide an additional parameter pass_through_channel_name and also provide the Customer’s email address using the parameter c_email.

 


Obtaining available payment methods before redirecting to the bank

When redirecting Customer directly to a bank or another payment method, you need to display the payment method options so that the Customer can choose one of them. Depending on the purchase amount or the activated payment methods on your end, certain payment methods might be restricted for use, and they should not be visible to the Customer. Therefore, it's recommended to always use the OPAY web service, which will provide information about the allowed payment methods for this specific purchase. This way, you won't need to worry about activating new payment methods manually. They will automatically appear on your website after being activated on the OPAY side.

For the web service, you need to provide the same array of parameters that you will later use for the generatetAutoSubmitForm method, as described in the section Redirecting the Customer directly to the bank.

Below is a fragment of the $array result.

Highlighted are the values of specific fields:

  • # - Systematic payment method group name
  • # - Systematic payment method name
  • # - Payment method group name
  • # - Payment method name

Fragment of the response

Within the array, there are URLs of images provided for each payment method. We kindly request you to utilize these URLs for loading images from our servers. This is important to enable us to manage the dynamic exchange of bank logos, as required by banks and other payment institutions. While the URLs of images might undergo changes, the indices color_33px and color_49px will remain consistent (unless additional indices are introduced). Hence, when referencing these indices, you can consistently retrieve the image URLs accessible at that specific time.


Receiving Response from OPAY Regarding Payment

OPAY sends the payment response to the address you specified (provided as the web_service_url parameter) using the HTTP POST method. Additionally, when redirecting the Customer after payment to another address you specified (provided as the redirect_url parameter), OPAY sends the same data package using the HTTP GET method. In both cases, you need to extract the received data and verify its authenticity. The process is the same for both scenarios.

 


Sending Metadata

In order to ensure the quality of the software, utilize the latest and most secure technologies, and provide quality partner support, metadata is sent along with the payment notification. This metadata includes:

  • The version of the Gateway PHP library in use (e.g., 1.3.0);
  • The version of the PHP software on the partner's side (e.g., 8.1.10);
  • Additional plugin information when using a plugin:
    • Platform (e.g., OpenCart).
    • Platform version (e.g., 4.0.1.1).
    • OPAY plugin version (e.g., 1.2.0).

This information is necessary to ensure timely updates of the software. For instance, if the minimum PHP version used by partners is 7.1, we will update the OPAY library and plugins to match this version to ensure higher levels of quality, speed, and security.

Metadata is automatically sent in all versions of the Gateway library starting from version 1.3.0. If you wish to exclude this information from being sent in your version of the software, when calling the signArrayOfParameters() method, you can add the value false as the second parameter. For example $opay➝signArrayOfParameters($data, false);.

Please note that if you choose not to send metadata, we recommend using PHP and platform versions that are not older than 2 years. Based on available statistical data, we prepare and update software versions. Without statistical data about the versions of software you are using, there is a possibility of releasing software that may not be compatible with your application.