andrew-svirin/ebics-client-php

PHP library to communicate with bank through EBICS protocol.

v2.2.1 2024-10-25 11:23 UTC

README

CI Latest Stable Version Total Downloads License

PHP library to communicate with a bank through EBICS protocol.
PHP EBICS Client - https://andrew-svirin.github.io/ebics-client-php/
Supported PHP versions - PHP 7.2 - PHP 8.3
Support EBICS versions: 2.4, 2.5, 3.0; Encryption versions: E002, X002, A005, A006; Switching EBICS T/TS

💥 EBICS API Client for web-server (V1.0.8)

EBICS API Client - https://sites.google.com/view/ebics-api-client
EBICS Client can be deployed as a standalone service on a webserver or within a Docker container and provides:

  • 💯 Support for EBICS Integration
  • ✅ REST API to operate with orders, connections, keyrings, access logs
  • ✅ UI to execute orders directly from the App
  • ✅ Logging orders activity
  • ✅ Manage Connections and Monitor access logs
  • ☑️ Soon! Scheduled Jobs, Files secure storage and Searching with API

License

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

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;
use AndrewSvirin\Ebics\Models\X509\BankX509Generator;

// Prepare `workspace` dir in the __PATH_TO_WORKSPACES_DIR__ manually.
// "__EBICS_VERSION__" should have value "VERSION_30" for EBICS 3.0
$keyringPath = __PATH_TO_WORKSPACES_DIR__ . '/workspace/keyring.json';
$keyringManager = new FileKeyringManager();
if (is_file($keyringPath)) {
    $keyring = $keyringManager->loadKeyring($keyringPath, __PASSWORD__, __EBICS_VERSION__);
} else {
    $keyring = $keyringManager->createKeyring(__EBICS_VERSION__);
    $keyring->setPassword(__PASSWORD__);
}
$bank = new Bank(__HOST_ID__, __HOST_URL__);
// Use __IS_CERTIFIED__ true for EBICS 3.0 and/or French banks, otherwise use false.
if(__IS_CERTIFIED__) {
    $certificateGenerator = (new BankX509Generator());
    $certificateGenerator->setCertificateOptionsByBank($bank);
    $keyring->setCertificateGenerator($certificateGenerator);
}
$user = new User(__PARTNER_ID__, __USER_ID__);
$client = new EbicsClient($bank, $user, $keyring);
if (!is_file($keyringPath)) {
    $client->createUserSignatures();
    $keyringManager->saveKeyring($client->getKeyring(), $keyringPath);
}

Global process and interaction with Bank Department

1. Create and store your 3 keys and send initialization request.

<?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!

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

Keyring schema

{
    "VERSION": "VERSION_24|VERSION_25|VERSION_30",
    "USER": {
        "A": {
            "VERSION": "A005|A006",
            "CERTIFICATE": "null|string",
            "PUBLIC_KEY": "string",
            "PRIVATE_KEY": "string"
        },
        "E": {
            "CERTIFICATE": "null|string",
            "PUBLIC_KEY": "string",
            "PRIVATE_KEY": "string"
        },
        "X": {
            "CERTIFICATE": "null|string",
            "PUBLIC_KEY": "string",
            "PRIVATE_KEY": "string"
        }
    },
    "BANK": {
        "E": {
            "CERTIFICATE": "null|string",
            "PUBLIC_KEY": "null|string",
            "PRIVATE_KEY": null
        },
        "X": {
            "CERTIFICATE": null,
            "PUBLIC_KEY": "null|string",
            "PRIVATE_KEY": null
        }
    }
}

Backlog

  • Format validators for all available ISO 20022 formats:
    • upload: PAIN.001, PAIN.008, MT101, TA875, CFONB320, CFONB160 with different versions.
    • download: PAIN.002, CAMT.052, CAMT.053, CAMT.054, MT199, MT900, MT910, MT940, MT942, CFONB240,CFONB245, CFONB120
  • Support import 3SKey certificates
  • Country's Bank specific order types
  • Refactor by abstraction Download and Upload Order types