BG | EN

eBG.bg Payment Process Description

Initiating and confirming a payment

In order to make a payment for goods or services, the customer takes the following steps:

  1. Visits the web site of the merchant's store and selects a product
  2. Confirms the order, i.e. by clicking on a "Pay" button

The following communication then takes place:

  1. The merchant generates payment data XML and signs it with his certificate. This is done on the server side and an HTTP POST request is sent to eBG.bg's interface URL. This request is made by the merchant's server, not by the customer's browser.
  2. Upon receipt of a payment initiation request, the message signature is validated by eBG.bg against the merchant store's certificate configured at eBG.bg. If successful, a payment is initiated, set in "unconfirmed" state and a payment ID is sent in the HTTP response.
  3. If the customer has signed the payment data with a certificate and has configured a default payment source, the payment is set in "processing" state and transaction is initiated, for example to Borica for money transfer from a card to a virtual POS / bank account.
  4. There are several ways for the user to confirm the payment:
    • at eBG.bg site with password or digital certificate
    • via SMS
    • at the merchant's site with digital certificate
  5. The merchant store's server informs the customer of the initiated payment - with a confirmation link or by displaying the payment id and confirmation instructions.

If the customer uses a digital certificate to confirm the payment on merchant's site, he/she:

  1. Enters his or her clientId (this step can be avoided if the merchant stores the clientId with the client's profile)
  2. Signs with a digital certificate the payment data generated by the merchant (clientId, merchantId, amount, description, etc., in a specified XML format). The signature is created on the client side and the generated PKCS#7 structure is submitted back to the merchant's web site.

Payment status

The merchant store's server can check the status of all payments it has initiated at any time.

HTTP notifications upon payment status change can be activated from the page Profile - Merchants - Update. A URL address of a script needs to be specified, e.g. http://www.mysite.org/eBG.bg/paymentStatusChangedNotify.php

An HTTP POST request is sent (application/x-www-form-urlencoded) with two parameters - data and signature. The data parameter contains payment description in XML format and if the payment status change has been triggered by response from Borica, information for the transaction authorization request (STAN, date/time and authorization code) is also included. The XML structure is the one of paymentInformationResponse element defined in the XML schema. Description is available in eBG Payment Gateway Merchant API.pdf.

An example php script that logs all notifications is available in http notify example directory. eBG.bg tries to establish a http connection and deliver the notification until a http status code 200 is received or a maximum number of redelivery attempts has been reached. An exponential back-off is used (e.g. 30 sec, 1 min, 5 min, 1 hour, 5 hours, 1 day).

Payment-status-changed notifications can also be sent via e-mail or SMS.

Diagram of the payment process is available at "FAQ" page on the portal. A state diagram describing the lifecycle of a payment is also available (PDF). Descriptions of the transitions are available in Visio format as well.

  1. When a payment is first initiated it is in unconfirmed state.
  2. After a payment source (bank card) has been chosen and confirmed by the client it goes to state accepted.
  3. A transaction authorization request is sent to Borica and status is updated to processing.
  4. Upon approval from Borica, status is set to completed.

If the transaction was rejected by Borica, the client can select a different payment source and confirmed the payment again. A new transaction is created.

If a payment is in unconfirmed state or a negative response has been received from Borica, it can be rejected by the client, the merchant or it can expire. These three statuses are final.

As requested by a few merchants, we have added a flag for automatic rejection of a payment upon a negative response from Borica. This way after a client has confirmed a payment, after 30 seconds the payment will be in a final state.

Server addresses and test accounts

The eBG.bg server for testing purposes is located at http://demo.ebg.bg/.

The following accounts are already present:

You can see sample e-commerce sites integrated with eBG.bg here: http://demo.ebg.bg/catalog/ (osCommerce) and http://demo.ebg.bg/store/ (CubeCart).

Currently integration modules haved been developed for Php, Perl, Python, Java and .Net. The Php module has been extended with support for OpenCart, VirtueMart, osCommerce, Zen Cart and CubeCart.

We hope that the information we provide will help you integrating with eBG.bg. If you have any further questions, please contact us.