Skip to content

Payment of money transfer from merchant to the customer via EasyPay

Process description

  1. The merchant prepares a packet (money transfer request) 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".
  3. The money transfer is paid to the submitted recipient at any of the EasyPay cash desks.
  4. The ePay.bg system monitors the status of the registered/recorded money transfers and when they are paid out, a notification is sent from ePay.bg to the merchant about them.
  5. Upon receiving a notification from ePay.bg, the merchant must form a corresponding response.

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

moneysend-process

Production environment

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

Demo environment

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

Money transfer request via EasyPay

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 Customer Identification Number (CIN) Mandatory
INVOICE int Invoice ID; numbers only Mandatory
AMOUNT float Valid amount > 0.01 (eg: 22, 22.8, 22.80) Mandatory
RCPT_NAME string Recipient name up to 100 characters;
CP1251 characters if no other ENCODING is supplied		 Mandatory
RCPT_PID int PID of recipient Mandatory
RCPT_ID_NO int Recipient's personal document number
(identity card/driver's license/passport)		 Mandatory
RCPT_ID_DATE date Issue date of recipient's personal document (identity card/driver's license/passport);
format DD.MM.YYYY		 Mandatory
RCPT_ADDRESS string Recipient address up to 256 characters; CP1251 characters if no other ENCODING is supplied Optional
RCPT_PHONE int Recipient phone up to 16 characters Optional
CURRENCY float Accepted currencies are BGN, USD, or EUR; if not supplied defaults to BGN Optional
DESCR string Transfer description up to 100 characters;
CP1251 characters if no other ENCODING is supplied		 Optional
ENCODING encoding utf-8 or CP1251; if not supplied, defaults to CP1251 Optional

Additional parameter information:

INVOICE:

It serves to differentiate the different requests of the merchant. This ID must be unique for each new request

ENCODING:

If this parameter is not passed, the system defaults to expecting CP1251 characters in all description fields (DESCR, RCPT_NAME, RCPT_ADDRESS). For UTF-8 characters, ENCODING=utf-8 is supplied in the description fields.

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.

Response

If everything with the request is in order, ePay.bg will return to the merchant a system code for the completed transfer in the same HTTP session. The generated code is a signal to the merchant that the transfer was successfully ordered.

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

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.

Notification from ePay.bg

When the transfer is paid out, the notification from the system is sent to a specified URL as an HTTP POST request, to which the merchant returns a response in the same HTTP session.

The merchant must have a specified URL for notification from ePay.bg if he wants to be notified of successful payments. If no URL address is set, the merchant will only be able to see the status of money transfers on his Microaccount - deposits from customers by 10-digit codes.

Only standard ports are allowed in the notification address:

  • 80 for HTTP
  • 443 for HTTPS

The address might look like this:

Response from the merchant after notification from ePay.bg

If the ePay.bg system does not receive a correct response from the merchant or does not receive one at all, it will continue to send the same notification until receiving a correct status for 14 days.

Scheme for sending notifications on a given INVOICE

  • 5 attempts in < 1 minute
  • 4 attempts in 15 minutes
  • 5 attempts in 1 hour
  • 6 attempts in 3 hours
  • 4 attempts in 6 hours
  • 1 attempt per day

Notification parameters from ePay.bg

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

Parameters in ENCODED

Parameter Description
INVOICE Request ID
STATUS PAID
PAY_TIME Payout date in YYYYMMDDhhmmss format
STAN Transaction number - always 000000
BCODE BORICA authorization code - always 000000

Sample notice from ePay.bg 

encoded=SU5WT0lDRT0xMjM0NTY6U1RBVFVTPVBBSUQ6UEFZX1RJTUU9MjAxNzA3MTUxMzUxMjM6U1RBTj0wMDAwMDA6QkN
PREU9MDAwMDAw&checksum=a2468791e7a999d616f1d92f266346801ed8e82a

An example of a decoded value of encoded 

INVOICE=123456:STATUS=PAID:PAY_TIME=20170715135123:STAN=000000:BCODE=000000

Response to notification

In the usual situation, the merchant is expected to return a STATUS=OK response, in which case the system stops the subsequent sending of the corresponding notification. By sending this status, the merchant confirms to ePay.bg that the notification has been successfully processed.

Output parameters

Parameter Description
INVOICE Request ID
STATUS OK, NO or ERR

Possible values ​​of the STATUS field

Parameter Description
OK The message has been processed correctly
ERR May be returned in the event of an error on the part of the merchant, due to which it could not save the notification
NO If there is no such request (INVOICE) generated by the merchant

Additional information about STATUS values

ERR:

If something is incorrect in the notification sent by ePay.bg, the merchant's system returns ERR=description. For example, it may return an invalid checksum - ERR=INVALID CHECKSUM. Upon receiving ERR, ePay.bg will continue to repeat the notification according to the described scheme.

NO:

Upon receiving this status, the ePay.bg system stops sending notifications for this INVOICE.

Examples

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
{
    # Encoding the request
    $ENCODED = base64_encode('DATA');

    # Generate checksum
    $CHECKSUM = hmac('sha1', $ENCODED, $secret);
}

The contents of ENCODED before being encoded

MIN=1000000000
INVOICE=123456
AMOUNT=22.80
DESCR=Money Order
ENCODING=utf-8
RCPT_NAME=Ivan Ivanov
RCPT_PID=1111111110
RCPT_ID_NO=1111111111
RCPT_ID_DATE=14.02.2024
RCPT_ADDRESS=Sofia, 16 Ivan Vazov St
RCPT_PHONE=029210850

Notice from ePay.bg about paid transfer

encoded=SU5WT0lDRT0xMjM0NTY6U1RBVFVTPVBBSUQ6UEFZX1RJTUU9MjAxNzA3MTUxMzUxMjM6U1RBTj0wMDAwMDA6QkN
PREU9MDAwMDAw&checksum=a2468791e7a999d616f1d92f266346801ed8e82a

Response to the notice from ePay.bg

INVOICE=123456:STATUS=OK

Cancellation of ordered money transfer

Production environment

Method URL
GET https://www.epay.bg/v3main

Demo environment

Method URL
GET https://demo.epay.bg/xdev/web

moneysend_reverse

GET /payment/cancel

Request to cancel an ordered money transfer. The request does NOT answer whether it was reversed successfully, only that it will attempt a reversal. To find out if the process was successful, you need to send a /payment/cancel/state request (cancel status check).

The cancellation request is sent with ENCODED and CHECKSUM parameters:

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 Mandatory

Parameters in ENCODED

Parameter Type Description Optionality
MIN int Customer Identification Number (CIN) Mandatory
INVOICE string Invoice number; unique to merchant Mandatory
AMOUNT float Valid amount > 0.01 (eg: 22, 22.8, 22.80) Mandatory
REV_ID int Arbitrary unique value serving as identifier Mandatory

Responses

STATUS=OK

STATUS=PROCESSING

STATUS=ERR
ERR=error message

Until when do I have to repeat the request?

  • Receiving a correct PROCESSING/OK status means that the request has been accepted and the system will try to reverse the payment.
  • Receiving an ERR status means that there is a problem with the request and it was not accepted by the system, making it necessary to repeat it again.

The request must be repeated until you receive a PROCESSING or OK response.

GET /payment/cancel/state

The request to check the cancellation status is sent with ENCODED and CHECKSUM parameters

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 Mandatory

Parameters in ENCODED

Parameter Type Description Optionality
MIN int Customer Identification Number (CIN) Mandatory
INVOICE string Invoice number; unique to merchant Mandatory
AMOUNT float Valid amount > 0.01 (eg: 22, 22.8, 22.80) Mandatory
REV_ID int Arbitrary unique value serving as identifier Mandatory

Responses

STATUS=OK

STATUS=PROCESSING

STATUS=DENIED

STATUS=ERR
ERR=error message

Important

If a reversal request has already been sent once that was successful and the transfer was reversed, and then a new reversal request is sent for the same transfer, you will get DENIED on the status check.

Possible scenarios

  • On a request to reverse a transfer already paid in a production environment, you will get PROCESSING/OK and then on checking the result of the reversal you will get DENIED.

Cancellation of payments

Cancellation of payments is automatic. When concluding the contract, a specific period is specified in which the transfers, which were ordered from the merchant's micro-account and have not been paid, are automatically reversed by our system and the funds are returned to the micro-account.

Info

In this case, the system does not send notifications when the transfer is canceled and the funds are returned.

Regardless of the submitted request expiration period, any successfully ordered transfer is ready for checkout until it is canceled.

The automatic cancellation periods are:

  • 7 days
  • 14 days
  • 30 days

Demo environment

To simulate requests in the test environment, you need to send an email to
Application Support - msupport@datamax.bg.