GPWebPay Core

https://gpwebpay-core.readthedocs.io/en/latest/
Admin
GPWebPay Core is a PHP library for integrating with the GPWebPay payment gateway, supporting secure...
Tokens:5,479
Snippets:87
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install GPWebPay Core via Composer

Source: https://gpwebpay-core.readthedocs.io/en/latest/installation.html

Use this command to add the library as a dependency to your project.

```bash
composer require pixidos/gpwebpay-core
```

--------------------------------

### Add Payment Methods to Operation

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Extend the Operation object by adding supported payment methods using the addParam method. This example adds card and Google Pay options.

```php
$operation->addParam(new PayMethods(PayMethod::CARD(), PayMethod::GOOGLE_PAY()));

```

--------------------------------

### Create OrderNumber Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Instantiate an OrderNumber object. Each API request requires a unique order number. This example uses the current timestamp for uniqueness.

```php
$orderNumber = new OrderNumber(time());

```

--------------------------------

### Configure multiple GPWebPay gateways

Source: https://gpwebpay-core.readthedocs.io/en/latest/configuration.html

Initializes multiple gateway configurations by providing an array of settings keyed by currency, with a specified default gateway.

```php
use Pixidos\GPWebPay\Config\Factory\ConfigFactory;
use Pixidos\GPWebPay\Config\Factory\PaymentConfigFactory;

$configFactory = new ConfigFactory(new PaymentConfigFactory());

$config = $configFactory->create(
        [
                'czk' => [
                        ConfigFactory::PRIVATE_KEY => __DIR__ . '/_certs/test.pem',
                        ConfigFactory::PRIVATE_KEY_PASSPHRASE => '1234567',
                        ConfigFactory::PUBLIC_KEY => __DIR__ . '/_certs/test-pub.pem',
                        ConfigFactory::URL => 'https://test.3dsecure.gpwebpay.com/unicredit/order.do',
                        ConfigFactory::MERCHANT_NUMBER => '123456789',
                        ConfigFactory::DEPOSIT_FLAG => 1,
                ],
                'eur' => [
                        ConfigFactory::PRIVATE_KEY => __DIR__ . '/_certs/test2.pem',
                        ConfigFactory::PRIVATE_KEY_PASSPHRASE => '12345678',
                        ConfigFactory::PUBLIC_KEY => __DIR__ . '/_certs/test-pub2.pem',
                        ConfigFactory::URL => 'https://test.3dsecure.gpwebpay.com/unicredit/order.do',
                        ConfigFactory::MERCHANT_NUMBER => '123456780',
                        ConfigFactory::DEPOSIT_FLAG => 1,
                ],
        ],
        'czk' // what gateway is default
);
```

--------------------------------

### Instantiate SignerProvider

Source: https://gpwebpay-core.readthedocs.io/en/latest/services.html

Instantiate the SignerProvider service, which provides Signer for each gateway. Requires SignerFactory and a SignerConfigProvider.

```php
use Pixidos\GPWebPay\Signer\SignerFactory;
use Pixidos\GPWebPay\Signer\SignerProvider;

$signerProvider = new SignerProvider(new SignerFactory(), $config->getSignerConfigProvider());

```

--------------------------------

### Create Payment Request in PHP

Source: https://gpwebpay-core.readthedocs.io/en/latest/example.html

Initializes the configuration and request factory to generate a payment URL for the client.

```php
<?php

declare(strict_types=1);

use Pixidos\GPWebPay\Config\Factory\ConfigFactory;
use Pixidos\
GPWebPay\Config\Factory\PaymentConfigFactory;
use Pixidos\GPWebPay\Data\Operation;
use Pixidos\GPWebPay\Enum\Currency as CurrencyEnum;
use Pixidos\GPWebPay\Enum\PayMethod;
use Pixidos\GPWebPay\Factory\RequestFactory;
use Pixidos\GPWebPay\Factory\ResponseFactory;
use Pixidos\GPWebPay\Param\AmountInPennies;
use Pixidos\GPWebPay\Param\Currency;
use Pixidos\GPWebPay\Param\MerOrderNum;
use Pixidos\GPWebPay\Param\OrderNumber;
use Pixidos\GPWebPay\Param\PayMethods;
use Pixidos\GPWebPay\Signer\SignerFactory;
use Pixidos\GPWebPay\Signer\SignerProvider;


// setup services
$configFactory = new ConfigFactory(new PaymentConfigFactory());
$config = $configFactory->create(
    [
        ConfigFactory::PRIVATE_KEY => __DIR__ . '/_certs/test.pem',
        ConfigFactory::PRIVATE_KEY_PASSPHRASE => '1234567',
        ConfigFactory::PUBLIC_KEY => __DIR__ . '/_certs/test-pub.pem',
        ConfigFactory::URL => 'https://test.3dsecure.gpwebpay.com/unicredit/order.do',
        ConfigFactory::MERCHANT_NUMBER => '123456789',
        ConfigFactory::DEPOSIT_FLAG => 1,
        ConfigFactory::RESPONSE_URL => 'http://example.com/proccess-gpw-response',
    ],
);

$signerProvider = new SignerProvider(new SignerFactory(), $config->getSignerConfigProvider());
$requestFactory = new RequestFactory($config->getPaymentConfigProvider(), $signerProvider);
$responseFactory = new ResponseFactory($config->getPaymentConfigProvider());

// create Request

$operation = new Operation(
    orderNumber: new OrderNumber(time()),
    amount: new AmountInPennies(10000),
    currency: new Currency(CurrencyEnum::CZK()),
);

$operation->addParam(new PayMethods(PayMethod::CARD(), PayMethod::GOOGLE_PAY())); // allowed payment types
$operation->addParam(new MerOrderNum('12345678')); // Reference number

$request = $requestFactory->create($operation);


// render html button for clinet
echo sprintf('<a href="%s">This is pay link</a>', $request->getRequestUrl());
```

--------------------------------

### Instantiate ResponseProvider

Source: https://gpwebpay-core.readthedocs.io/en/latest/services.html

Instantiate the ResponseProvider service, which validates and processes Response objects. Requires a PaymentConfigProvider and the SignerProvider.

```php
use Pixidos\GPWebPay\ResponseProvider;

$provider = new ResponseProvider(
        $config->getPaymentConfigProvider(), $signerProvider
);

```

--------------------------------

### Instantiate ResponseFactory

Source: https://gpwebpay-core.readthedocs.io/en/latest/services.html

Instantiate the ResponseFactory service, responsible for creating Response objects from received parameters. Requires a PaymentConfigProvider.

```php
use Pixidos\GPWebPay\Factory\ResponseFactory;
$responseFactory = new ResponseFactory($config->getPaymentConfigProvider());

```

--------------------------------

### Create Response Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

Initialize a response object using the ResponseFactory with request parameters.

```php
$params = $_GET; // or $_POST depends on how you send request
$response = $responseFactory->create($params);
```

--------------------------------

### Configure a single GPWebPay gateway

Source: https://gpwebpay-core.readthedocs.io/en/latest/configuration.html

Initializes a single gateway configuration using the ConfigFactory and PaymentConfigFactory.

```php
use Pixidos\GPWebPay\Config\Factory\ConfigFactory;
use Pixidos\GPWebPay\Config\Factory\PaymentConfigFactory;

$configFactory = new ConfigFactory(new PaymentConfigFactory());

$config = $configFactory->create(
        [
                ConfigFactory::PRIVATE_KEY => __DIR__ . '/_certs/test.pem',
                ConfigFactory::PRIVATE_KEY_PASSPHRASE => '1234567',
                ConfigFactory::PUBLIC_KEY => __DIR__ . '/_certs/test-pub.pem',
                ConfigFactory::URL => 'https://test.3dsecure.gpwebpay.com/unicredit/order.do',
                ConfigFactory::MERCHANT_NUMBER => '123456789',
                ConfigFactory::DEPOSIT_FLAG => 1,
                ConfigFactory::RESPONSE_URL => 'http://example.com/proccess-gpw-response'
        ]
);
```

--------------------------------

### Create Currency Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Instantiate a Currency object using constants from the Pixidos\GPWebPay\Enum\Currency class, which follow ISO 4217 standards.

```php
use Pixidos\GPWebPay\Enum\Currency as CurrencyEnum;

$currency = new Currency(CurrencyEnum::CZK())

```

--------------------------------

### Instantiate RequestFactory

Source: https://gpwebpay-core.readthedocs.io/en/latest/services.html

Instantiate the RequestFactory helper, used for creating Request objects from The Operation. Requires a PaymentConfigProvider and the SignerProvider.

```php
use Pixidos\GPWebPay\Factory\RequestFactory;
$requestFactory = new RequestFactory($config->getPaymentConfigProvider(), $signerProvider);

```

--------------------------------

### Handle GPWebPay Response in PHP

Source: https://gpwebpay-core.readthedocs.io/en/latest/example.html

Configures response providers and callback functions to process incoming payment results.

```php
<?php

declare(strict_types=1);

use Pixidos\GPWebPay\Config\Factory\ConfigFactory;
use Pixidos\GPWebPay\Config\Factory\PaymentConfigFactory;
use Pixidos\GPWebPay\Factory\ResponseFactory;
use Pixidos\GPWebPay\ResponseProvider;
use Pixidos\GPWebPay\Signer\SignerFactory;
use Pixidos\GPWebPay\Signer\SignerProvider;

// setup services
$configFactory = new ConfigFactory(new PaymentConfigFactory());
$config = $configFactory->create(
    [
        ConfigFactory::PRIVATE_KEY => __DIR__ . '/_certs/test.pem',
        ConfigFactory::PRIVATE_KEY_PASSPHRASE => '1234567',
        ConfigFactory::PUBLIC_KEY => __DIR__ . '/_certs/test-pub.pem',
        ConfigFactory::URL => 'https://test.3dsecure.gpwebpay.com/unicredit/order.do',
        ConfigFactory::MERCHANT_NUMBER => '123456789',
        ConfigFactory::DEPOSIT_FLAG => 1,
        ConfigFactory::RESPONSE_URL => 'http://example.com/proccess-gpw-response',
    ],
);

$signerProvider = new SignerProvider(new SignerFactory(), $config->getSignerConfigProvider());
$responseFactory = new ResponseFactory($config->getPaymentConfigProvider());
$responseProvider = new ResponseProvider(
    $config->getPaymentConfigProvider(),
    $signerProvider
);


// setup callbacks

$responseProvider->addOnSuccess(function (\Pixidos\GPWebPay\Data\Response $response) {
    // do anything you need after payment is success
    echo 'Success';
});
// you can add more callbacks
$responseProvider->addOnSuccess(function (\Pixidos\GPWebPay\Data\Response $response) {
    // do anything you need
    echo 'Success';
});

$responseProvider->addOnError(function (\Pixidos\GPWebPay\Exceptions\GPWebPayResultException $exception, \Pixidos\GPWebPay\Data\Response $response) {
    // do anything you need
    echo 'Success';
});


// process response from GPWebPay
$response = $responseFactory->create($_GET);
$responseProvider->provide($response);
```

--------------------------------

### Create AmountInPennies Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Instantiate an AmountInPennies object to represent the order amount in the smallest currency unit (e.g., cents for EUR, hellers for CZK).

```php
$amount = new AmountInPennies(100000); // represent 1000.00 Kč|Euro

```

--------------------------------

### Process Response with Callbacks

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

Register success and error callbacks with the ResponseProvider before triggering the provide method.

```php
// success callbacks
$provider
        ->addOnSuccess(
                static function (ResponseInterface $response) {
                        // here is your code for processing response
                }
        )
        ->addOnSuccess(
                static function (ResponseInterface $response) {
                        // here is your another code for processing response
                }
        );

// error callback
$provider->addOnError(
        static function (GPWebPayException $exception, ResponseInterface $response) {
                // here is you code for processing error
        }
);

// and next step is call
$provider->provide($response);
```

--------------------------------

### Create Operation Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Instantiate an Operation object with essential payment details like order number, amount, and currency. The gateway, response URL, and operation type are optional parameters.

```php
use Pixidos\GPWebPay\Data\Operation;
use Pixidos\GPWebPay\Enum\Operation as OperationEnum;
use Pixidos\GPWebPay\Param\Currency;
use Pixidos\GPWebPay\Enum\Currency as CurrencyEnum;
use Pixidos\GPWebPay\Param\AmountInPennies;
use Pixidos\GPWebPay\Param\OrderNumber;

$operation = new Operation(
    orderNumber: new OrderNumber(self::ORDER_NUMBER),
    amount: new AmountInPennies(10000),
    currency: new Currency(CurrencyEnum::CZK()),
    gateway: 'czk', // optional, if you leave it blank, the default settings will be used (only since version ^2.4.0) for lower versions you have to set it.
    responseUrl: new ResponseUrl('http://example.com/proccess-gpw-response'), // optional when you setup in config
    operation: OperationEnum::CREATE_ORDER() // optional CREATE_ORDER() is default, other options are CARD_VERIFICATION() or FINALIZE_ORDER()
);

```

--------------------------------

### Response Parameters

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

This section details the available parameters within the GPWebPay response object and how to retrieve them.

```APIDOC
## Parameters

### ResultText
A text description of the error identified by a combination of PRCODE and SRCODE. The contents are coded using the Windows Central European (Code Page 1250).

return:
    
`string`

```php
$response->getResultText();
```

### PrCode
Primary code. For details, see “List of return codes in GPWebPay doc”. 

return:
    
`int`

```php
$response->getPrcode();
```

### SrCode
Secondary code. For details, see “List of return codes in GPWebPay doc”. 

return:
    
`int`

```php
$response->getSrcode();
```

### OrderNumber
Contents of the field from the request. 

return:
    
`string`

```php
$response->getOrderNumber();
```

### MerOrderNumber
Contents of the field from the request, if included. 

return:
    
`string` | `null`

```php
$response->getMerOrderNumber();
```

### UserParam1
Hash numbers of the payment card. Hash is a unique value for each and every card and merchant – that is if the payment is made by the same card at the same merchant, the resulting hash is identical, if the same card is used at another merchant, there is another hash. 

return:
    
`string` | `null`
Note
Only if the merchant has this functionality enabled

```php
$response->getUserParam1();
```

### Md
Any merchant’s data returned to the merchant in the response in the unchanged form – only “whitespace” characters are removed from both sides. The field is used to satisfy various demands of the e-shops. The field may only contain ASCII characters ranging from 0x20 to 0x7E.
Note
GPWebPay core use this field to store information about used gateway.
So method `$response->getParam(string $paramName)` return value contain gateway info. 

return:
    
`string` | `null`

```php
$response->getMd();
```

### Digest and Digest1
_Digest_ is a check signature of the string generated as a concatenation of all the fields sent in the given order
_Digest1_ is same as _Digest_ but (without the DIGEST field) and on the top of that also the MERCHANTNUMBER field (the field is not sent, the merchant has to know it, the field is added to the end of the string). 

return:
    
`string`

```php
$response->getDigest();
$response->getDigest1();
```
```

--------------------------------

### Render Payment Form

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Generate an HTML form for POST requests to initiate payment. It includes hidden input fields for all necessary payment parameters.

```html
<form action="<?= $request->getRequestUrl(true) ?>">
    <?php
    /** @var IParam $param */
    foreach ($request->getParams() as $param) {
        echo sprintf('<input type=hidden value="%s" name="%s">%s', $param->getValue(), $param->getParamName(), "\n\r");
    }
    ?>
    <input type="submit" value="Pay">
</form>

```

--------------------------------

### Render Payment Link

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Display a payment link by retrieving the request URL from the Request object. This is typically used for direct payment button links.

```php
echo sprintf('<a href="%s">This is pay link</a>', $request->getRequestUrl());

```

--------------------------------

### Response Processing

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

This section covers the creation and processing of responses from GPWebPay. You can either process the response manually by verifying signatures and checking for errors, or use the ResponseProvider with callbacks for success and error handling.

```APIDOC
## Response Processing

### Description
This section covers the creation and processing of responses from GPWebPay. You can either process the response manually by verifying signatures and checking for errors, or use the ResponseProvider with callbacks for success and error handling.

### Create Response

```php
$params = $_GET; // or $_POST depends on how you send request
$response = $responseFactory->create($params);
```

### Processing by Your Code

```php
// verify response signatures
if (!$provider->verifyPaymentResponse($response)) {
        // invalid verification
}
// success verification
if ($response->hasError()) {
        // here is you code for processing response error
}
// here is you code for processing response
```

### Using ResponseProvider and Callbacks

```php
// success callbacks
$provider
        ->addOnSuccess(
                static function (ResponseInterface $response) {
                        // here is your code for processing response
                }
        )
        ->addOnSuccess(
                static function (ResponseInterface $response) {
                        // here is your another code for processing response
                }
        );

// error callback
$provider->addOnError(
        static function (GPWebPayException $exception, ResponseInterface $response) {
                // here is you code for processing error
        }
);

// and next step is call
$provider->provide($response);
```
```

--------------------------------

### Retrieve Response Parameters

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

Methods to access specific fields from the response object.

```php
$response->getResultText();
```

```php
$response->getPrcode();
```

```php
$response->getSrcode();
```

```php
$response->getOrderNumber();
```

```php
$response->getMerOrderNumber();
```

```php
$response->getUserParam1();
```

```php
$response->getMd();
```

```php
$response->getDigest();
$response->getDigest1();
```

--------------------------------

### Create Request Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Generate a Request object from an Operation object using the RequestFactory. This object is used to obtain payment URLs and form parameters.

```php
$request = $requestFactory->create($operation);

```

--------------------------------

### Process Response Manually

Source: https://gpwebpay-core.readthedocs.io/en/latest/response.html

Verify response signatures and check for errors using the provider and response object.

```php
// verify response signatures
if (!$provider->verifyPaymentResponse($response)) {
        // invalid verification
}
// success verification
if ($response->hasError()) {
        // here is you code for processing response error
}
// here is you code for processing response
```

--------------------------------

### Create MerOrderNum Object

Source: https://gpwebpay-core.readthedocs.io/en/latest/request.html

Instantiate a MerOrderNum object to specify a merchant-defined order identification. If not provided, the OrderNumber value is used.

```php
use Pixidos\GPWebPay\Param\MerOrderNum;

$merOrderNum = new MerOrderNum(123455);

```
Tokens:
Raw