andrew-svirin/ebics-client-php

PHP library to communicate with bank through EBICS protocol.

v2.1.2 2023-08-16 18:19 UTC

README

CI Latest Stable Version Total Downloads License

68747470733a2f2f7777772e65626963732e6f72672f7479706f33636f6e662f6578742f73697a5f65626963736f72675f626173652f5265736f75726365732f5075626c69632f496d616765732f65626963732d6c6f676f2e706e67

PHP library to communicate with a bank through EBICS protocol.
Supported PHP versions - PHP 7.2 - PHP 8.3
Support Ebics server versions: 2.4 (partially), 2.5 (default), 3.0

License

andrew-svirin/ebics-client-php is licensed under the MIT License, see the LICENSE file for details

Development and integration Ebics for your project

👉👍 Contact Andrew Svirin https://www.linkedin.com/in/andriy-svirin-0138a177/

Installation

$ composer require andrew-svirin/ebics-client-php

Initialize client

You will need to have this information from your Bank: HostID, HostURL, PartnerID, UserID

<?php

use AndrewSvirin\Ebics\Services\FileKeyringManager;
use AndrewSvirin\Ebics\Models\Bank;
use AndrewSvirin\Ebics\Models\User;
use AndrewSvirin\Ebics\EbicsClient;

// Prepare `workspace` dir in the __PATH_TO_WORKSPACES_DIR__ manually.
$keyringRealPath = __PATH_TO_WORKSPACES_DIR__ . '/workspace/keyring.json';
// Use __IS_CERTIFIED__ true for French banks, otherwise use false.
$keyringManager = new FileKeyRingManager();
$keyring = $keyringManager->loadKeyRing($keyringRealPath, __PASSWORD__);
$bank = new Bank(__HOST_ID__, __HOST_URL__, __EBICS_SERVER_VERSION___);
$bank->setIsCertified(__IS_CERTIFIED__);
$user = new User(__PARTNER_ID__, __USER_ID__);
$client = new EbicsClient($bank, $user, $keyring);

Note for French Bank and for Ebics 3.0

If you are dealing with a French bank or with Ebics 3.0, you will need to create a X509 self-signed certificate. You can achieve this by creating a class which extends the AbstractX509Generator and use __IS_CERTIFIED__ = true

<?php

namespace App\Factories\X509;

use AndrewSvirin\Ebics\Models\X509\AbstractX509Generator;

class MyCompanyX509Generator extends AbstractX509Generator
{
    protected function getCertificateOptions() : array {
        return [
             'subject' => [
                'DN' => [
                    'id-at-countryName' => 'FR',
                    'id-at-stateOrProvinceName' => 'State',
                    'id-at-localityName' => 'City',
                    'id-at-organizationName' => 'Your company',
                    'id-at-commonName' => 'yourwebsite.tld',
                    ]
                ],
                'extensions' => [
                    'id-ce-subjectAltName' => [
                    'value' => [
                        'dNSName' => '*.yourwebsite.tld',
                    ]
                ],
            ],
        ];
    }
}

$client->setX509Generator(new MyCompanyX509Generator);

Global process and interaction with Bank Department

1. Create and store your 3 keys

<?php

use AndrewSvirin\Ebics\Contracts\EbicsResponseExceptionInterface;

/* @var \AndrewSvirin\Ebics\EbicsClient $client */

try {
    $client->INI();
    /* @var \AndrewSvirin\Ebics\Services\FileKeyringManager $keyringManager */
    /* @var \AndrewSvirin\Ebics\Models\KeyRing $keyring */
    $keyringManager->saveKeyRing($keyring, $keyringRealPath);
} catch (EbicsResponseExceptionInterface $exception) {
    echo sprintf(
        "INI request failed. EBICS Error code : %s\nMessage : %s\nMeaning : %s",
        $exception->getResponseCode(),
        $exception->getMessage(),
        $exception->getMeaning()
    );
}

try {
    $client->HIA();
    $keyringManager->saveKeyRing($keyring, $keyringRealPath);
} catch (EbicsResponseExceptionInterface $exception) {
    echo sprintf(
        "HIA request failed. EBICS Error code : %s\nMessage : %s\nMeaning : %s",
        $exception->getResponseCode(),
        $exception->getMessage(),
        $exception->getMeaning()
    );
}

2. Generate a EBICS letter

/* @var \AndrewSvirin\Ebics\EbicsClient $client */
$ebicsBankLetter = new \AndrewSvirin\Ebics\EbicsBankLetter();

$bankLetter = $ebicsBankLetter->prepareBankLetter(
    $client->getBank(),
    $client->getUser(),
    $client->getKeyRing()
);

$pdf = $ebicsBankLetter->formatBankLetter($bankLetter, $ebicsBankLetter->createPdfBankLetterFormatter());

3. Wait for the bank validation and access activation.

4. Fetch the bank keys.

try {
    /* @var \AndrewSvirin\Ebics\EbicsClient $client */
    $client->HPB();
    /* @var \AndrewSvirin\Ebics\Services\FileKeyringManager $keyringManager */
    /* @var \AndrewSvirin\Ebics\Models\KeyRing $keyring */
    $keyringManager->saveKeyRing($keyring, $keyringRealPath);
} catch (EbicsResponseExceptionInterface $exception) {
    echo sprintf(
        "HPB request failed. EBICS Error code : %s\nMessage : %s\nMeaning : %s",
        $exception->getResponseCode(),
        $exception->getMessage(),
        $exception->getMeaning()
    );
}

5. Play with other transactions!

Transaction Description
HEV Download supported protocol versions for the Bank.
INI Send to the bank public signature of signature A005.
HIA Send to the bank public signatures of authentication (X002) and encryption (E002).
H3K Send to the bank public signatures of signature (A005), authentication (X002) and encryption (E002).
HPB Download the Bank public signatures authentication (X002) and encryption (E002).
HPD Download the bank server parameters.
HKD Download customer's customer and subscriber information.
HTD Download subscriber's customer and subscriber information.
PTK Download transaction status.
FDL Download the files from the bank.
FUL Upload the files to the bank.
HAA Download Bank available order types.
VMK Download the interim transaction report in SWIFT format (MT942).
STA Download the bank account statement.
C52 Download the bank account report in Camt.052 format.
C53 Download the bank account statement in Camt.053 format.
C54 Download Debit Credit Notification (DTI).
Z52 Download the bank account report in Camt.052 format (i.e Switzerland financial services).
Z53 Download the bank account statement in Camt.053 format (i.e Switzerland financial services).
Z54 Download the bank account statement in Camt.054 format (i.e available in Switzerland).
ZSR Download Order/Payment Status report.
CCT Upload initiation of the credit transfer per Single Euro Payments Area.
CIP Upload initiation of the instant credit transfer per Single Euro Payments Area.
XE2 Upload initiation of the Swiss credit transfer (i.e available in Switzerland).
XE3 Upload SEPA Direct Debit Initiation, CH definitions, CORE (i.e available in Switzerland).
YCT Upload Credit transfer CGI (SEPA & non SEPA).
CDD Upload initiation of the direct debit transaction.
BTD Download request files of any BTF structure.
BTU Upload the files to the bank.
HVU Download List the orders for which the user is authorized as a signatory.
HVZ Download VEU overview with additional information.
HVE Upload VEU signature for order.
HVD Download the state of a VEU order.
HVT Download detailed information about an order from VEU processing for which the user is authorized as a signatory.

If you need to parse Cfonb 120, 240, 360 use andrew-svirin/cfonb-php
If you need to parse MT942 use andrew-svirin/mt942-php