PHPackages                             veneliniliev/borica-3ds - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. veneliniliev/borica-3ds

ActiveLibrary

veneliniliev/borica-3ds
=======================

Borica 3DS payments gateway

3.0.0(1y ago)2515.7k↓25%5[1 PRs](https://github.com/veneliniliev/borica-3ds/pulls)MITPHPPHP >=5.6CI failing

Since Oct 5Pushed 5mo ago5 watchersCompare

[ Source](https://github.com/veneliniliev/borica-3ds)[ Packagist](https://packagist.org/packages/veneliniliev/borica-3ds)[ Docs](https://veneliniliev.com)[ RSS](/packages/veneliniliev-borica-3ds/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (18)Used By (0)

PHP Borica EMV 3DS
==================

[](#php-borica-emv-3ds)

Requirements
------------

[](#requirements)

- PHP >= 5.6 (including 8.5)
- ext-mbstring
- ext-openssl
- ext-curl
- ext-json

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require veneliniliev/borica-3ds
```

### Version Compatibility

[](#version-compatibility)

Library VersionSupported Signing SchemasDefault Signing SchemaPHP Support^2.0MAC\_EXTENDED, MAC\_ADVANCED, MAC\_GENERALMAC\_GENERALPHP 5.6 - 8.5^1.0MAC\_EXTENDED, MAC\_ADVANCEDMAC\_ADVANCEDPHP 5.6 - 8.5### Signing Schema Information

[](#signing-schema-information)

- **MAC\_GENERAL**: The latest schema with enhanced security (default in v2.0+)
- **MAC\_EXTENDED**: Extended schema with additional fields
- **MAC\_ADVANCED**: Advanced schema with specific field requirements

You can switch between signing schemas using the following methods:

- `setSigningSchemaMacGeneral()` - Use MAC\_GENERAL schema
- `setSigningSchemaMacExtended()` - Use MAC\_EXTENDED schema
- `setSigningSchemaMacAdvanced()` - Use MAC\_ADVANCED schema

For more methods, read [api documentation](API.md).

For official Borica resources like their API documentation, public keys for validation and more visit

Certificates
------------

[](#certificates)

### Generate private key

[](#generate-private-key)

```
# Production key
openssl genrsa -out production.key -aes256 2048
# Development key
openssl genrsa -out development.key -aes256 2048
```

### Generate CSR

[](#generate-csr)

**IMPORTANT**: in `Organizational Unit Name (eg, section)` enter your terminal ID and in `Common Name (eg, fully qualified host name)` enter your domain name.

```
# Production csr
openssl req -new -key production.key -out VNNNNNNN_YYYYMMDD_P.csr
# Development csr
openssl req -new -key development.key -out VNNNNNNN_YYYYMMDD_D.csr
```

Имената на файловете се създават по следната конвенция: **VNNNNNNN\_YYYYMMDD\_T**, където:

- **VNNNNNNN** – TID на терминала, предоставен от Финансовата Институция
- **YYYYMMDD** – дата на заявка
- **T** – тип на искания сертификат, значения – **D** – за development среда, **Р** – за продукционна среда

Usage
-----

[](#usage)

**IMPORTANT**: Switch signing schema MAC\_EXTENDED / MAC\_ADVANCED / MAC\_GENERAL with methods:

```
$saleRequest->setSigningSchemaMacGeneral(); // use MAC_GENERAL
$saleRequest->setSigningSchemaMacExtended(); // use MAC_EXTENDED
$saleRequest->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED
```

Default signing schema is **MAC\_GENERAL**!

### Sale request

[](#sale-request)

```
use VenelinIliev\Borica3ds\SaleRequest;
// ...
$saleRequest = (new SaleRequest())
    ->setAmount(123.32)
    ->setOrder(123456)
    ->setDescription('test')
    ->setMerchantUrl('https://test.com') // optional
    ->setTerminalID('')
    ->setMerchantId('')
    ->setPrivateKey('\', '')
    ->setMInfo(array( // Mandatory cardholderName and ( email or MobilePhone )
        'email'=>'user@sample.com',
        'cardholderName'=>'CARDHOLDER NAME', // Max 45 chars
        'mobilePhone'=> array(
            'cc'=>'359', // Country code
            'subscriber'=>'8939999888', // Subscriber number
        ),
        'threeDSRequestorChallengeInd'=>'04', //  Optional for Additional Authentication
    ))
    //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
    //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
    //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED
    ->setPrivateKeyPassword('test');

$formHtml = $saleRequest->generateForm(); // only generate hidden html form with filled inputs
// OR
$saleRequest->send(); // generate and send form with js
```

### Sale response

[](#sale-response)

Catch response from borica on `BACKREF` url

`->setPublicKey` is the Borica public key and not the one you've generated. You can download borica key for DEV and PROD environment from here:

```
use VenelinIliev\Borica3ds\SaleResponse;
// ....
$isSuccessfulPayment = (new SaleResponse())
            ->setPublicKey('') # Borica public key for the specific env
            ->setResponseData($_POST) //Set POST data from borica response
            //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
            //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
            //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED
            ->isSuccessful();
```

#### Get response code

[](#get-response-code)

```
use VenelinIliev\Borica3ds\SaleResponse;
// ...
$saleResponse= (new SaleResponse())
               ->setPublicKey('')  # Borica public key for the specific env
               //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
               //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
               //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED

// ...
// automatic fill data from $_POST or can be set by ->setResponseData()
// ...

$saleResponse->getResponseCode(); // return RC from response
$saleResponse->getVerifiedData(''); // return verified data from post by key
$saleResponse->isSuccessful(); // RC === 00 and data is verified
```

Response codes table

Response Code (RC)RC DESCRIPTION00Sucessfull=> Timeout"01"Refer to card issuer"04"Pick Up"05"Do not Honour"13"Invalid amount"30"Format error"65"Soft Decline"91"Issuer or switch is inoperative"96"System Malfunction### Transaction status check

[](#transaction-status-check)

```
 use VenelinIliev\Borica3ds\Enums\TransactionType;
 use VenelinIliev\Borica3ds\StatusCheckRequest;
 // ...
 $statusCheckRequest = (new StatusCheckRequest())
    //->inDevelopment()
    ->setPrivateKey('\', '')
    ->setPublicKey('')
    ->setTerminalID('')
    ->setOrder('')
    ->setOriginalTransactionType(TransactionType::SALE()) // transaction type
    //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
    //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
    //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED

//send to borica
$statusCheckResponse = $statusCheckRequest->send();

// get data from borica response
$verifiedResponseData = $statusCheckResponse->getResponseData();

// get field from borica response
$statusCheckResponse->getVerifiedData('setCountryCode('BG'); // Set the country code (2-letter ISO code)
```

#### Set merchant GMT timezone

[](#set-merchant-gmt-timezone)

```
$saleRequest->setMerchantGMT('+02'); // Set the merchant's timezone offset
```

#### Set merchant name

[](#set-merchant-name)

```
$saleRequest->setMerchantName('My Company Ltd.'); // Set the merchant's name
```

#### Set notification email

[](#set-notification-email)

```
$saleRequest->setEmailAddress('notification@mycompany.com'); // Set notification email address
```

#### Set 'AD.CUST\_BOR\_ORDER\_ID' field

[](#set-adcust_bor_order_id-field)

```
$saleRequest->setAdCustBorOrderId('ORDER123456'); // Set identifier for the bank's financial files
```

### Advanced Transaction Types

[](#advanced-transaction-types)

#### Pre-authorisation

[](#pre-authorisation-1)

You can send pre-authorisation requests:

```
use VenelinIliev\Borica3ds\PreAuthorisationRequest;

$preAuthorisationRequest = (new PreAuthorisationRequest())
    ->setAmount(123.32)
    ->setOrder(123456)
    ->setDescription('test pre-authorisation')
    ->setMerchantUrl('https://test.com') // optional
    ->setTerminalID('')
    ->setMerchantId('')
    ->setPrivateKey('\', '')
    ->setMInfo(array( // Mandatory cardholderName and ( email or MobilePhone )
        'email'=>'user@sample.com',
        'cardholderName'=>'CARDHOLDER NAME', // Max 45 chars
        'mobilePhone'=> array(
            'cc'=>'359', // Country code
            'subscriber'=>'8939999888', // Subscriber number
        ),
    ))
    ->setPrivateKeyPassword('test');

$formHtml = $preAuthorisationRequest->generateForm(); // only generate hidden html form with filled inputs
// OR
$preAuthorisationRequest->send(); // generate and send form with js
```

#### Pre-authorisation completion

[](#pre-authorisation-completion-1)

After successful pre-authorisation, you can complete the transaction within 30 days:

```
use VenelinIliev\Borica3ds\PreAuthorisationCompletionRequest;

$response = (new PreAuthorisationCompletionRequest())
    //->inDevelopment()
    ->setPrivateKey('\', '')
    ->setPublicKey('')
    ->setTerminalID('')
    ->setAmount(123.32)
    ->setOrder(123456)
    ->setDescription('pre-authorisation completion')
    ->setMerchantId('')
    ->setRrn('')
    ->setIntRef('')
    //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
    //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
    //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED
    ->send();

$isSuccessful = $response->getVerifiedData('ACTION') === \VenelinIliev\Borica3ds\Enums\Action::SUCCESS &&
    $response->isSuccessful();
```

#### Pre-authorisation reversal

[](#pre-authorisation-reversal-1)

You can reverse a pre-authorisation:

```
use VenelinIliev\Borica3ds\PreAuthorisationReversalRequest;

$response = (new PreAuthorisationReversalRequest())
    //->inDevelopment()
    ->setPrivateKey('\', '')
    ->setPublicKey('')
    ->setTerminalID('')
    ->setAmount(123.32)
    ->setOrder(123456)
    ->setDescription('pre-authorisation reversal')
    ->setMerchantId('')
    ->setRrn('')
    ->setIntRef('')
    //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
    //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
    //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED
    ->send();

$isSuccessful = $response->getVerifiedData('ACTION') === \VenelinIliev\Borica3ds\Enums\Action::SUCCESS &&
    $response->isSuccessful();
```

#### Transaction status check

[](#transaction-status-check-1)

Check the status of a transaction:

```
use VenelinIliev\Borica3ds\Enums\TransactionType;
use VenelinIliev\Borica3ds\StatusCheckRequest;

$statusCheckRequest = (new StatusCheckRequest())
    //->inDevelopment()
    ->setPrivateKey('\', '')
    ->setPublicKey('')
    ->setTerminalID('')
    ->setOrder('')
    ->setOriginalTransactionType(TransactionType::SALE()) // transaction type
    //->setSigningSchemaMacGeneral(); // use MAC_GENERAL
    //->setSigningSchemaMacExtended(); // use MAC_EXTENDED
    //->setSigningSchemaMacAdvanced(); // use MAC_ADVANCED

//send to borica
$statusCheckResponse = $statusCheckRequest->send();

// get data from borica response
$verifiedResponseData = $statusCheckResponse->getResponseData();

// get field from borica response
$statusCheckResponse->getVerifiedData('