PHP Library

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

The library's minimum supported PHP version is 5.0.1.

Download (.zip)

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.

require_once 'opay_8.1.gateway.inc.php';

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.

require_once('opay_8.1.gateway.inc.php');
$opay = new OpayGateway();

// We are setting the signing password.
// Here, a sample signing password is used,
// which will be provided to you by OPAY.
$opay->setSignaturePassword("05be076d3f9c0b6f6f2c26542e9b66a6");

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.

// Here, a sample private key is used.
// please generate yours manually
$opay->setMerchantRsaPrivateKey("
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA2koP8ib2OmCfyH18a229DOH8456J4wKsksEtBiMNdeuMdqaW
r946tqelc8/urcfhrDysfA/+Z4RmmIadBMUMiyL1tl2MJAlY8klj9dhNpGFM4t2k
WY5msp6hUI1WFFdfFKLSndJsTjVcTYJ8+zJQD2Zssx8zNC8EZqotH0JUotXHKMA3
qKPp+wlTcXV4vSf4fIK9OmzO4T9fbyf1wwRdDt3JoRzjpfC33DZ5I/QwpmlQ4ktN
POLeklbrR3VDb2jOkI+FHvHjDcMcp9aGKNrIAt3WnybFBAhJ+yx4NxNSThdH6I/e
OA/op4E9AYciu6nVzRUwYczrGAunqcy1ZBv4ewIDAQABAoIBAHLa80bzby1KN+hy
9mtEI2vK4JgXi++xMYJKOFl5ShTYqmCnyLOil3wR+8FTD//KIxjQF+VzOOXYyW7J
rYab87yl2WlqEVnIvU9GhF0PwdKTC7R28InannivdKuAomEzk6i0/2LhG/GOrBFw
bjhxwaRIvTsGWJfFgWhPdEx1Rzkhj43039ISmv3M4qxmtsduuYdUruOn+pYBlTpd
2LFUUdH55J6dyta1U6vln7gmjsqwxI1DMUqhZK8Pf86C6eZFm+p6fIe5q7+yjN5y
7fudEBA2cMJad/G7leXVOKZCjudCq9uB67AGzPeOJptCWXGQqY88Uf3Ro6+ldvIR
fuAYD4kCgYEA97wPF1DhUA8aFpdalhHqSMRwyEP7CCs2FegwlFq5NziPL+5RAspQ
PROjJMSEhZImO0CJGkpIBinh6k093A6oAfyd7tF3aPIdddt5CFql/KNqqbO3c6g+
KuJFqSuYG9gqicM4VQt7RIwIqHe2PwFniL2nLvk3B3ybX9irDIH3xO8CgYEA4ZKB
nV6yyatgdPH4WvVC66rAAJYH1a2I28039gLh4AcOB6aWn3yAqkmlZRfcIAqmu/6x
hzQQbGp5maiCsceE4Qmj1gc7Rf04tVWbFbAhqGs6XDY1B7nxi54QZs03ES3N5Td+
wU6X8dsNc5KuNQNVBfY9u7nwmyHqNQITBSTQ/TUCgYBG0sy9rbG8YZTjwIF1Rcnk
48QafNTXkQL1YFwDDazFzLWizk76rTwjOen6KPR5+z5S0jBgA7xzhqW/hjWZI9eE
OeQs0lWA+zbQ6t2/NaseftmPioF33zFmsSmZI41o6HPAzr7cEVw8TIxtHUxM1uny
fcW9+CFzUnxY+mhsOvvKoQKBgFqRIRtXLz+LYHHzyPx0JsdKSkax9jlTsHRX5BUR
OTFig76Mo0MrkNlOMmrxdn8i56jpbMvVGpb89Q+9uaO5cN+NqEtBognKzp733QmL
KyhczRTC6u3MOXAOKZWs5WQvWNCkRG9Gp/kCM1do2CsOyG9ZW5Xo5PLUXh2kVJCn
JIXVAoGBAIkieYMAFZXxpELlGM3hBcuY+6ooNjT8ALUoPghJsXVfU1vOZva0lV6W
icph3FT8lsCPhMm5pSfRKCrveq/qTHYRi+r8q7m0siE2fzBmz8BnsIqqMtQKON+o
wrtPvaNdQh9lIOWWwY3NI/7Gf+UHXZHavcuSOy3/kWRvaQJ5OzPP
-----END RSA PRIVATE KEY-----
");

// We are configuring the certificate provided by OPAY to you.
// A sample certificate is used here.
// OPAY issues a specifically generated certificate for each website.
$opay->setOpayCertificate("
-----BEGIN CERTIFICATE-----
MIIDEzCCAfugAwIBAgIJAKyrfrqvHyLyMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV
BAMMFXBhdnl6ZGluaXNwdXNsYXBpcy5sdDAeFw0xNTA5MjUxMzE5MzFaFw0yNTA5
MjIxMzE5MzFaMCAxHjAcBgNVBAMMFXBhdnl6ZGluaXNwdXNsYXBpcy5sdDCCASIw
DQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANpKD/Im9jpgn8h9fGttvQzh/OOe
ieMCrJLBLQYjDXXrjHamlq/eOranpXPP7q3H4aw8rHwP/meEZpiGnQTFDIsi9bZd
jCQJWPJJY/XYTaRhTOLdpFmOZrKeoVCNVhRXXxSi0p3SbE41XE2CfPsyUA9mbLMf
MzQvBGaqLR9CVKLVxyjAN6ij6fsJU3F1eL0n+HyCvTpszuE/X28n9cMEXQ7dyaEc
46Xwt9w2eSP0MKZpUOJLTTzi3pJW60d1Q29ozpCPhR7x4w3DHKfWhijayALd1p8m
xQQISfsseDcTUk4XR+iP3jgP6KeBPQGHIrup1c0VMGHM6xgLp6nMtWQb+HsCAwEA
AaNQME4wHQYDVR0OBBYEFAzT0uGzL0gckDno42TiUF0/M9lTMB8GA1UdIwQYMBaA
FAzT0uGzL0gckDno42TiUF0/M9lTMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEF
BQADggEBADEC5/qo00tK7tmXiqFS29Dbob+2HFItZJtL2wdg9DM0IIhqRnp37gPs
vUfJ+JVZgiBeNNw9PdVP+G3MCBU1u2qUiGBU1iMS/UV8yl5sDa/fyerclNc6bppE
7YxqjV5Khe/QgILKMttU9eSX175vBBJ/RUKE+I4mvBMwBD/5+PGBYBtT0FhYDimR
0jO96XvZt9VWq9GpNm+F9fIK/Qx78C/iwFmpao/OxqVYHuq6CxLchhBL2ej/3gHx
focG9NjTAJsM3Ld3xz06uhCoD0tJ814exjb8IWsHf2e55Ktl9V4TQiJrveIxHP6w
i0dFumPRZjPmM/iJwpOkjyWMqe8fLA8=
-----END 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.

$opay = new OpayGateway();
$opay->setSignaturePassword("...enter_your_signing_password_here...");

$paramsArray = array(
  'website_id'            => '8W11U8Y8JF', // id provided to you by OPAY
  'order_nr'              => '300', // order number in your system
  'redirect_url'          => 'http://your-website.com/sssss', // OPAY will redirect user here after payment
  'web_service_url'       => 'http://your-website.com/aaaaa', // OPAY will send here payment status
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000, // sum in cents
  'currency'              => 'EUR', // currency
  'test'                  => '8U11Z8SK8H', // provide parametr 'test' to enable testing regime - as value use your user id in OPAY system
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);
echo $opay->generatetAutoSubmitForm('https://gateway.opay.lt/pay/', $paramsArray);

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.

$opay = new OpayGateway();
$opay->setSignaturePassword("...");
$paramsArray = array(
  'website_id'            => '8W11U8Y8JF',
  'order_nr'              => '300',
  'redirect_url'          => 'http://your-website.com/sssss',
  'web_service_url'       => 'http://your-website.com/aaaaa',
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000,
  'currency'              => 'EUR',

  'pass_through_channel_name' => 'banklink_swedbank', // The system payment method name is provided to direct the buyer to it.
  'c_email'               => '[email protected]'
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);
echo $opay->generatetAutoSubmitForm('https://gateway.opay.lt/pay/', $paramsArray)

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.

$opay = new OpayGateway();
$opay->setSignaturePassword("...");
$paramsArray = array(
  'website_id'            => '8W11U8Y8JF',
  'order_nr'              => '300',
  'redirect_url'          => 'http://your-website.com/sssss',
  'web_service_url'       => 'http://your-website.com/aaaaa',
  'standard'              => 'opay_8.1',
  'country'               => 'LT',
  'language'              => 'LIT',
  'amount'                => 25000,
  'currency'              => 'EUR',
  'pass_through_channel_name' => 'banklink_swedbank',
  'c_email'               => '[email protected]'
);
$paramsArray = $opay->signArrayOfParameters($paramsArray);

$array = $opay->webServiceRequest('https://gateway.opay.lt/api/listchannels/', $paramsArray);

echo '<pre>';
print_r($array);
echo '</pre>';

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.

$opay = new OpayGateway();
$opay->setSignaturePassword("...add-your-password-signature-here...");

if (isset($_POST['encoded'])) {

    $parametersArray = $opay->convertEncodedStringToArrayOfParameters($_POST['encoded']);

} elseif (isset($_GET['encoded'])) {

    $parametersArray = $opay->convertEncodedStringToArrayOfParameters($_GET['encoded']);

}

if (isset($parametersArray)) {

    if ($opay->verifySignature($parametersArray)) {

        echo '<pre>';
        print_r($parametersArray); // response array
        echo '</pre>';

    } else {

        echo 'Error'; // Either an incorrect signing password was used, or the data was altered after their signing.

    }
}

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.