Deposit slip - payment request

General information

• Client - The end user of the service
• Merchant (WEB merchant) - A legal entity that has concluded a contract with ePay.bg
• The files cited in the documentation can be downloaded from the "Demo package" link under the login button at https://demo.epay.bg/

Each registered merchant in the ePay.bg system has

• Alphanumeric secret word of length 64 (secret)
• Customer Identification Number (CIN)

The merchant can find them in his https://epay.bg/ profile without being able to change them.

Cash payment via EasyPay

Description of the process

The merchant sends an HTTP GET request for the money transfer to the given URL.

1. Request for payment to a budget organization (merchant).
2. On the site of the organization (merchant), the customer selects the desired service and as a payment method - EasyPay.
3. The merchant prepares a package (payment request) that he sends to ePay.bg URL as an HTTP GET request. In the same HTTP session, ePay.bg returns a "Payment code" to the merchant. The merchant displays this code on his site, through which the customer can pay in cash in EasyPay.
4. Upon payment, ePay.bg sends a notification to the customer and generates a bank transfer with the data from the request.
5. ePay.bg monitors the status of registered/recorded pending obligations and upon payment, refusal or expiration of the payment time, sends a notification to the merchant about the status of each payment. System notifications are sent to ports:
   • 80 for HTTP
   • 443 for HTTPS
6. Upon receiving a notification from ePay.bg, the merchant must form a corresponding response.

Communication scheme

Production environment

Method	URL
GET	https://www.epay.bg/ezp/reg_vnbel.cgi

Demo environment

Method	URL
GET	https://demo.epay.bg/ezp/reg_bill.cgi

Payment request

Parameter	Description	Optionality
ENCODED	Base64-encoded (RFC 3548) payment request, EOL=" "	Mandatory
CHECKSUM	Checksum on ENCODED generated as HMAC with SHA-1 algorithm and merchant SECRET word	Mandatory

Parameters in ENCODED

Parameter	Type	Description	Optionality
MIN	int	Merchant ID - Corresponds to the CIN in the merchant's profile in ePay.bg	Mandatory
INVOICE	int	Invoice number; unique to the merchant	Mandatory
AMOUNT	float	Valid amount > 0.01 (eg: 22, 22.8, 22.80)	Mandatory
EXP_TIME	datetime	Final date/time for payment, up to 30 days after the date of the request; format DD.MM.YYYY [hh:mm [:ss]]	Mandatory
DESCR	string	Description up to 100 characters; encoding CP1251	Optional
MERCHANT	string	Recipient of the order	Mandatory
IBAN	string	A valid IBAN of the recipient	Mandatory
BIC	string	BIC of the receiving bank	Mandatory
STATEMENT	string	Payment description	Mandatory
PSTATEMENT	int	Payment code	Mandatory
OBLIG_PERSON	string	Name of the obligee; up to 26 characters	Mandatory
BULSTAT EGN LNC	int	BULSTAT, EGN or LNC Only one of the three parameters is submitted!	Mandatory
DOC_NO	int	Document type and number	Mandatory
DOC_DATE	int	Document date: The parameter is submitted for document type - 2|3|6	Mandatory at: 2|3|6
DATE_BEGIN	int	Start of period: The parameter is submitted for document type - 1|2|4|5	Mandatory at: 1|2|4|5
DATE_END	int	End of period: The parameter is submitted for document type - 1|2|4|5	Mandatory at: 1|2|4|5

When submitting the request

• The parameters do not have to be in this order.
• If the payment is multi-line, the parameter AMOUNT is replaced by TOTAL, and for each separate payment the amount is submitted with the parameter SUM1, SUM2, SUM3, respectively.

Sample request

PerlPHP

{
    # Encoding the request
    $ENCODED = encode_base64('DATA', ''); # '' for EOL (def. е "\n")

    # Generate CHECKSUM
    $CHECKSUM = hmac_hex($ENCODED, $secret, \&sha1);
}

{
    $data = base64_decode($ENCODED);

    # Calculating the checksum
    # $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac('sha1', $ENCODED, $secret);
    # hmac function code can be found in demo.php
}

Sample notification from ePay.bg

PaidExpiredDenied

INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 digits]:BCODE=[6 digits/letters]

INVOICE=123457:STATUS=EXPIRED

INVOICE=123457:STATUS=DENIED

Parameter	Description
STAN	Transaction number, only when paying by card
BCODE	BORICA authorization code, only when paying by card

Payment notification

STAN and BCODE have the value 000000 when the payment is not made by card.

Payment via ePay.bg

Amounts paid by customers are transferred to a bank account specified by the merchant in a Bulgarian bank. Payment is made via ePay.bg.

Description of the process

1. Request for payment to a budget organization (merchant).
2. On the site of the organization (merchant), the customer selects the desired service and as a payment method - online via ePay.bg.
3. The merchant prepares a payment request, which he sends to the ePay.bg URL as an HTTP POST request.
4. The customer is redirected to a payment page on ePay.bg, where he must select a payment method and confirm the payment with his password and other information, if required.
5. Upon payment, ePay.bg sends a notification to the customer and generates a bank transfer with the data from the request.
6. ePay.bg monitors the status of registered/recorded pending obligations and upon payment, refusal or expiration of the payment time, sends a notification to the merchant about the status of each payment. System notifications are sent to ports:
   • 80 for HTTP
   • 443 for HTTPS
7. Upon receiving a notification from ePay.bg, the merchant must form a corresponding response.

Communication scheme

Production environment

Method	URL
POST	https://www.epay.bg/

Payment request

Parameter	Type	Description	Optionality
PAGE	string	paylogin	Mandatory
MERCHANT	string	Recipient of the transfer Accepted: Cyrillic, Latin, numbers, spaces, dashes, commas, periods	Mandatory
IBAN	string	A valid IBAN of the recipient	Mandatory
BIC	string	BIC of the receiving bank	Mandatory
TOTAL	float	Valid amount > 0.01 (eg: 22, 22.8, 22.80)	Mandatory
STATEMENT	string	Reason Accepted: Cyrillic, Latin, numbers, spaces, dashes, commas, periods	Mandatory
PSTATEMENT	int	Valid payment type - 6 digits	Optional
URL_OK	url	URL to which the customer will be forwarded in case they confirm the payment. It does not guarantee that payment has been made.	Optional
URL_CANCEL	url	The URL to which the customer will be redirected in case they decline the payment.	Optional

Sample request

<form action="https://www.epay.bg/" method=post>
<input type=hidden name=PAGE value="paylogin">
<input type=hidden name=MERCHANT value="[MERCHANT]">
<input type=hidden name=IBAN value="[IBAN]">
<input type=hidden name=BIC value="[BIC]">
<input type=hidden name=AMOUNT value="[AMOUNT]">
<input type=hidden name=STATEMENT value="[STATEMENT]">
<input type=hidden name=PSTATEMENT value="[PSTATEMENT]">
<input type=hidden name=URL_OK value="http://...">
<input type=hidden name=URL_CANCEL value="http://...">
<input type=submit>
</form>

Payment notification

To receive real-time notifications about the status of payments, you need to develop a Payment Notification.