Skip to content

Payment of a money transfer from a merchant to a customer via ePay.bg

Process description

  1. The merchant prepares a packet that it sends to a given URL as an HTTP GET request.
  2. Upon submission of a correct request, in the same HTTP session, ePay.bg will return to the merchant "System code for the payment made at 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.

Communication scheme

Production environment

Method URL
GET https://www.epay.bg/send/send.cgi

Demo environment

Method URL
GET https://demo.epay.bg/send/send.cgi

Request for money transfer via ePay.bg

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 Customer Identification Number (CIN)
 Mandatory
MEMAIL string Email of the merchant in the system Mandatory
CIN int Recipient's Customer Identification Number (CIN)
 Mandatory
CEMAIL string Recipient's email in the system Mandatory
INVOICE string Invoice number; 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 supplied defaults to BGN Optional
DESCR string Transfer description up to 100 characters Optional
ENCODING encoding encoding of DESCR Optional

Important

A request with a given INVOICE can enter the system only once.

It is mandatory to submit data about the recipient in the request

The request must contain Personal Identification Number and/or number of a valid Personal Identification Document of the recipient.

If a personal document is submitted, the date of issue is also required.

Example code for making the request

1
2
3
4
5
6
7
{
    # Encoding the request
    $ENCODED = encode_base64('DATA', ''); # '' for EOL (def. is "\n")

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

1
2
3
4
5
6
7
8
{
    # Encoding the request
    $ENCODED = base64_encode('DATA');

    # Generate checksum
    $CHECKSUM = hmac('sha1', $ENCODED, $secret);
    # hmac function code can be seen in demo.php
}

Response

SYS_CODE=1234567890 (digits only, up to 64 in length)

The generated code is a signal to the merchant that the transfer was successfully ordered.

ERR=Error description

Retrying the request will not result in another transfer being ordered

No response or one with an empty value should not be a flag that the request to generate a transfer was not or was successful.

The merchant must repeat the request with the same data until receiving a response according to specification (SYS_CODE=123 or ERR=Error Description). Any repetition of a request with the same data will result in the same system code, meaning that repeating the request will not result in another transfer being ordered.

Errors

No valid recipient client was found

If a transfer is made by two identifiers at the same time, but one of them is not valid, it will return an error: ERR=EMETHOD: No valid recipient client found!

Example scenarios:

  • the email is valid, but the CIN is not
  • The CIN is valid, but the email is not
  • the email is valid and the CIN is valid, but they are associated with different accounts