Skip to content

Payment Notification

The payment notice should be implemented as a final step to:

After the payment request has been registered for the customer, the system will notify the Merchant about the status of the payment: "Paid" or "Expired". If the Customer does not confirm the request before the submitted cut-off date, it will be marked as expired.

A request with a given INVOICE can enter the system only once and is waiting for "Confirm" from the customer.

The system notification is sent to a URL specified by the Merchant as an HTTP POST request, to which a response is returned by the Merchant in the same HTTP session.

Notifications are sent to addresses with port 80 (HTTP) or 443 (HTTPS).

Info

If the Merchant has not declared a URL on which to receive payment notifications, does not want or is unable to process these notifications, then the Merchant can view the status of payment requests in the ePay.bg system.

Production environment

To request a notification URL, send an email to Commercial Department - merchant@epay.bg containing your CIN and notification URL.

Demo environment

In the Demo environment, the Merchant himself can set a notification address.

Payment notification

Method URL
POST [Notification URL]
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

Parameter ENCODED

Parameter Type Description Optionality
INVOICE string Invoice number from the payment request Mandatory
STATUS string Payment Status
PAID, DENIED, EXPIRED		 Mandatory
PAY_TIME datetime YYYYMMDDhhmmss Date/Hour/Sec of Payment Mandatory (when paid)
STAN int [6 digits]Transaction Number Mandatory (when paid)
BCODE string [6 digits/letters]BORICA Authorization Code Mandatory (when paid) 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    $data = decode_base64($ENCODED);

    # Calculation of the checksum
    # Must $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac_hex($ENCODED, $secret, \&sha1);

    # Digital signature verification
    use Crypt::OpenSSL::RSA;
    $rsa_pub = Crypt::OpenSSL::RSA->new_public_key(EPAY_PUBLIC_KEY_DATA);
    $rsa_pub->verify($ENCODED, $SIGNATURE);
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    $data = base64_decode($ENCODED);

    # Calculation of the checksum
    # Must $CHECKSUM_CALC == $CHECKSUM
    $CHECKSUM_CALC = hmac('sha1', $ENCODED, $secret);

    # hmac function code can be seen in demo.php

    # Digital signature verification
    $pkey_obj = openssl_get_publickey($EPAY_CERT_DATA);
    openssl_verify($ENCODED, $SIGNATURE, $pkey_obj);
}

Examples

Notification of payment made

Encoded data:

  • encoded=SU5WT0lDRT0xNDAyOlNUQVRVUz1QQUlEOlBBWV9USU1FPTIwMjIwNjI5MTQ1MjU3OlNUQU49MDAwMDAwOkJDT0RFPTAwMDAwMAo%3D&checksum=46703be53c26149b0f28bcb1a38d1f8fdbb096de

After decoding the data, the text is obtained from which the parameters we send can be seen:

  • INVOICE=1402:STATUS=PAID:PAY_TIME=20220629145257:STAN=000000:BCODE=000000

Notification with more than one INVOICE in one request

There are cases where the system sends more than one INVOICE in the same request:

  • INVOICE=162319945:STATUS=PAID:PAY_TIME=20230626002551:STAN=036221:BCODE=036221 INVOICE=162322355:STATUS=PAID:PAY_TIME=20230626002551:STAN=036227:BCODE=036227

Notification for expired time

encoded=SU5WT0lDRT02MTY1NjQyOTc2MzpTVEFUVVM9RVhQSVJFRAo%3D&checksum=2cf0b859969c55c1ed2d16fcc4446d7455305010

After decoding the encoded parameter, the text that contains this notification is visible:

INVOICE=61656429763:STATUS=EXPIRED

Other decoded values ​​of encoded

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

INVOICE=123457:STATUS=DENIED

INVOICE=123457:STATUS=EXPIRED

Response to payment notification

For each invoice number in the notification, the merchant must return a status.

Parameter Type Description Optional
INVOICE string Invoice number from the payment request Mandatory
STATUS string OK - successfully received notification
ERR - description of the error
NO - non-existent invoice number		 Mandatory

Info

When STATUS = OK or STATUS = NO is returned, the system stops sending notifications for the respective invoice.

The system sends notifications for 14 days.

Examples

INVOICE=123456:STATUS=OK

INVOICE=123457:STATUS=ERR

INVOICE=123458:STATUS=NO

In response to the notification, the merchant may return a STATUS=ERR response if it wishes to cause the same notification to be repeated.

ERR=a description of the global error (e.g. invalid CHECKSUM)

Time-out for notifications

If ePay.bg does not mark an invoice as received by the merchant (for example ERR status returned or failed communication), the system will try to send the failed notifications again.

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