ČSOB Business Connector – PHP implementation

A few months ago I was asked to implement the connector in PHP 7.3 for new ČSOB API called Business Connector (CEB). If you have business bank account in ČSOB bank, you can activate the Business Connector in the internet banking. Afterwards this API will be available for you.

PHP implementation of CEB allows you to perform following tasks:

  • account information
  • list incoming/outgoing payments
  • generate import of payment batches

As mentioned the CEB connector is written in PHP 7.3 and you can find the source files on https://github.com/AsisTeam/csob-bc or you can install it into your project via composer require asisteam/csob-bc.

During the implementation I followed the implementation guide provided by ČSOB itself. Unfortunately there was no other open-source implementation of CEB even in different languages so I had no choice of inspiring myself in others code and I had to struggle with ČSOB certificates for a while. Anyway in the end there is a functional program that you can use for your own purpose as you wish and modify the code as you wish.

The CEB API is divided into 2 parts. The first one is based on SOAP and is used for listing existing files in CEB (payments reports, payment batches, protocols etc.), starting and stopping the process of uploading new files. The second one is based on HTTP and is used for downloading and uploading the real files.

The diagrams below describe the required process of downloading/uploading files from CEB. There are many file formats that the files can have. They all or text based files containing the desired information about payments, but with different structure (ABO, DUZ, Multicash, TXT, XLSX. csv, xml, another proprietary formats etc). You can list all the available file formats at CEB support page. In the library I implemented 1 file format for each file types (payments batch file, payments reports, reports) respectively, but it is easy to implement and hook any custom class for different format that fulfils the given interface and use it instead.

Downloading files

Downloading files. Get files list via SOAP and then download concrete file by its url.

Uploading files

CEB required certificates

In order to communicate with CEB server, you must generate your own keys and accept them in CEB. There is quite long and very well described process how to generate the keys and accept them in the CEB so You can do it yourself manually. Or you can use my makefile that eases this process. See the Makefile.

To generate the certificate using Makefile you should enter the cert directory where Makefile and bccert.cnf.dist files are present.

  1. In some text editor open bccert.cnf.dist file, change the line ‘CN = ‘. Replace by your local machine name and save the file as bccert.cnf.
  2. run make generate-request. It creates bccert.csr certificate request file.
  3. Upload bccert.csr file to CSOB CEB application and in it’s UI generate and download certificate file (name it bccert.crt)
  4. run make generate-cert and set some passphrase if you wish so. New files bccert.p12 and bccert.pem files should appear in cert folder.
  5. use path to bccert.pem file and the passphrase you typed before as parameters for creation of Options object.

Now it should be possible to communicate with the CEB server properly authorised.

Example usage

<?php

// use factory to create CEB instance
// factory creates and registers file readers and generators so you don't have to do it manually
$options = new Options('path/to/bccert.pem', 'certPassPhrase', 'contractId', 'appGuid');
$factory = new CEBFactory($options, '/tmp/');
$ceb = $factory->create();

// returns files from CEB API
$list = $ceb->listFiles();
Assert::count(2, $list->getFiles());

// You can read and parse files content

// first one is VYPIS type
$as = $ceb->downloadAndRead($list->getFiles()[0]);
Assert::true($as instanceof IReport);
Assert::count(11, $as->getEntries());

// second one is AVIZO type
$adv = $ceb->downloadAndRead($list->getFiles()[1]);
Assert::true($adv instanceof IAdvice);
Assert::count(3, $adv->getTransactions());

// generate and upload payment batch file to CEB
$payments = []; // create list of IPaymentOrder entities eg by: new InlandPayment(...)
$file = $ceb->generatePaymentFile($payments);
$ceb->upload([$file]);

// search for import protocol files only and read the first one
$filter = new Filter();
$filter->setFileTypes([FileTypeEnum::IMPPROT]);
$files = $this->ceb->listFiles(null, $filter);
$protocol = $this->ceb->downloadAndRead($files->getFiles[0]);
Assert::true($protocol->isOk());

Summary

In this article I wanted to present you that there is already the existing implementation of CSOB CEB in PHP and you are very welcome to use it. I’d very appreciate any pull request to this open source project or just the info that you use it and it works/doesn’t work as expected.

Close Menu