Payment via EasyPay

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/

Description of the payment process

1. A client of a WEB merchant places an order in his electronic store.
2. After finishing the order, the customer selects "Pay at an EasyPay office".
3. The merchant sends an HTTP GET payment request to ePay.bg URL (hidden from the client)
4. In the case of a correctly submitted request, ePay.bg returns to the merchant a 10-digit payment code in EasyPay in the same HTTP session.
5. The merchant displays this code on his site. This is the code for the customer to go to the EasyPay checkout and make the payment.
6. ePay.bg monitors the status of the registered/recorded pending obligations and upon payment/rejection of the payment, a notification is sent to the merchant regarding the status of the respective request. 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. If the notification is received again, the first response returned is repeated.

Info

Payments with a 10-digit code can also be made at an EasyPay ATM.

Communication scheme

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.

Production environment

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

Demo environment

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

Simulate a payment made with a 10-digit code at an EasyPay office

https://demo.epay.bg/ezp/pay_bill.cgi?ACTION=PAY&IDN=1234567890

Parameter	Type	Description	Optionality
ACTION	PAY	Simulate Payment	Mandatory
IDN	int	The resulting payment code	Mandatory

You should get STATUS=PAID on the notification URL you specified.

Payment request

Parameter	Type	Description	Optionality
ENCODED	string	Base64-encoded (RFC 3548) payment request, EOL=''.	Mandatory
CHECKSUM	string	Checksum on ENCODED generated as HMAC with SHA-1 algorithm and the merchant's secret word.	Mandatory

Parameters in ENCODED

Parameter	Type	Description	Optionality
MIN	int	Customer Identification Number (CIN)	Mandatory
EMAIL	string	Email of the merchant in the system	Optional
INVOICE	int	InvoiceNumber; unique to merchant	Mandatory
AMOUNT	float	Valid Amount > 0.01 (eg: 22, 22.8, 22.80)	Mandatory
CURRENCY	string	Accepted currencies are BGN, USD or EUR; if not provided it defaults to BGN	Optional
EXP_TIME	datetime	Payment End Date/Time; format DD.MM.YYYY[hh:mm[:ss]]	Mandatory
DESCR	string	Description up to 100 characters; CP1251 characters if no other ENCODING	Optional
ENCODING	encoding	encoding of DESCR parameter; only utf-8 is accepted, it can also be passed as an HTTP parameter	Optional

Important

Allow enough time for the EXP_TIME request to be valid for the customer to go to an EasyPay checkout.

Sample request

# '' for EOL (def. is "\n")
DATA =
    MIN=1000000000
    EMAIL=a@merch.bg
    INVOICE=123456
    AMOUNT=22.80
    CURRENCY=BGN
    EXP_TIME=01.08.2020
    DESCR=Test
    ENCODING=utf-8

$ENCODED = encode_base64('DATA');

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

<form action="https://www.epay.bg/" method=post>
    <input type=hidden name=LANG value="[LANG]">
    <input type=hidden name=ENCODED value="[$ENCODED]">
    <input type=hidden name=CHECKSUM value="[$CHECKSUM]">
</form>

Change timeout to 10-digit code

Each 10-digit code is valid until expiration_time. Change expiration time to a 10-digit code serves to extend the duration or disable it.

Payment notification

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