ePay.bg <office@epay.bg>, <epay2_demo@epay.bg> ______________________________________________________________________
The package consists of the following files:
- sample payment request written in Perl
- sample payment request written in PHP
- example for receiving a notification concerning a registered payment order (Paid or Rejected) written in Perl
- example for receiving a notification concerning a registered payment order (Paid or Rejected) written in PHP
- simple payment request by user/merchant, ``Free transfer''
______________________________________________________________________
Scheme:
A customer of the WEB merchant makes an order in his electronic shop
After being ready with the order, the customer forms a request to pay
The merchant makes a package - payment request and refers the customer to the ePay.bg system, by applying the payment request in the way described below
After a customer enters successfully in the ePay.bg system, the payment request (if it is correctly applied) is registered/recorded as a pending bill to the given merchant. If the customer refuses without making login or makes an unsuccessful tries to login, the payment request is NOT recorded in the system
The customer can pay the bill immediately or delay it
The ePay.bg system keeps track the status of the registered/recorded pending bills and in case of payment, rejection or expiry, a notification about them is sent to the merchant
When receives a notification from ePay.bg, the merchant should form a corresponding answer
Merchant --[PAYMENT REQUEST]--> ePay.bg Customer --[ENTRY]--[REQUEST RECORDING]--> ePay.bg ePay.bg --[NOTIFICATION]--> Merchant Merchant --[NOTIFICATION REPLY]--> ePay.bg
Each merchant registered in the system has generated alpha-numeric secret word with length 64 and an identification number (CIN). The merchant can see them in his personal data without being able to change them.
A. The payment request is sent as HTTP POST request to https://www.epay.bg/
Example:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="paylogin"> <input type=hidden name=ENCODED value="[ENCODED]"> <input type=hidden name=CHECKSUM value="[CHECKSUM]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
(*) If the ePay.bg DEMO system is used at address: https://demo.epay.bg/, the TEST payment requests will be sent to it!!!
The following fields are compulsory: PAGE, ENCODED and CHECKSUM, the value of PAGE obligatorily being ``paylogin''.
Fields URL_OK and URL_CANCEL are optional:
URL_OK - URL to which the customer will be referred in case
he confirms the payment (does not guarantee the payment
has been done)
URL_CANCEL - URL to which the customer will be referred in case
he denies the payment for the moment (he can pay it
or reject it later but not after the date, indicated by
the merchant)
Signing of the payment request
ENCODED - encoded with base64 (RFC 3548) payment request, EOL=''
CHECKSUM - checksum on ENCODED, generated as HMAC with
an algorithm SHA-1 and the secret word of the merchant.
Perl example code: {
# Encode the payment request
$ENCODED = encode_base64('DATA', ''); # '' çà EOL (def. å "\n")
# Generate checksum $CHECKSUM = hmac_hex($ENCODED, $secret, \&sha1);
}
PHP example code: {
# Encode the payment request
$ENCODED = base64_encode('DATA');
# Generate checksum
$CHECKSUM = hmac('sha1', $ENCODED, $secret);
# the code of hmac function can be seen in demo.php
}
Example of payment request data:
MIN=1000000000 (obl. MIN or EMAIL Identification number of the merchant) EMAIL=a@merch.bg (obl. MIN or EMAIL E-mail of the merchant in the system) INVOICE=123456 (obligatory Invoice number) AMOUNT=22.80 (obligatory Amount) CURRENCY=BGN (optional Currency - BGN, USD or EUR) EXP_TIME=01.08.2020 (obligatory Final date/hour for payment) DESCR=Test (optional Description up to 100 characters) ENCODING=utf-8 (optional encoding of the DESCR parameter)
(*) in the request MIN or EMAIL is applied for identification of the merchant
They don't obligatorily have to be in this order.
MIN - corresponds to CIN in personal data of the merchant EMAIL - e-mail of the merchant with which he is registered INVOICE - only digits AMOUNT - valid amount > 0.01 ( for example: 22, 22.8, 22.80 ) CURRENCY - accepted currencies are BGN, USD or EUR; if not present then BGN by default DESCR - CP1251 characters if not passed another ENCODING ENCODING - accepted is only utf-8; can be passed and as an HTTP parameter
The following format is valid for field EXP_TIME:
EXP_TIME=DD.MM.YYYY[ hh:mm[:ss]]
EXP_TIME=01.08.2020 EXP_TIME=01.08.2020 23:15 (can also be applied with hour:min) EXP_TIME=01.08.2020 23:15:30 (can also be applied with hour:min:sec)
After the payment request is registered for the customer, the system will notify the merchant about the payment state: 'Paid', 'Rejected' or 'Expired'.If the customer does not confirm or rejects the order before the applied final date, it will be marked as expired.
Request with certain INVOICE can enter in the system only ONE time and waits for 'confirmation' or 'rejection' of the customer.
B. The notification of the system is sent to given by the merchant URL as HTTP POST request, to which the merchant returns a reply in the same HTTP session.
Signing of the payment notification
ENCODED - encoded with base64 (RFC 3548) notification, EOL=''
CHECKSUM - checksum on ENCODED, generated as HMAC with
an algorithm SHA-1 and the secret word of the merchant.
Perl example code: {
$data = decode_base64($ENCODED); # Calculate checksum # Must $CHECKSUM_CALC == $CHECKSUM $CHECKSUM_CALC = hmac_hex($ENCODED, $secret, \&sha1);
}
PHP example code: {
$data = base64_decode($ENCODED);
# Calculate checksum
# Must $CHECKSUM_CALC == $CHECKSUM
$CHECKSUM_CALC = hmac('sha1', $ENCODED, $secret);
# the code of hmac function can be seen in demo.php
}
Sample notification from ePay.bg:
INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 digits]:BCODE=[6 digits/letters] INVOICE=123457:STATUS=DENIED INVOICE=123457:STATUS=EXPIRED
STATUS=[PAID | DENIED | EXPIRED] - Paid | Rejected | Expired PAY_TIME - Date/hour/sec of the payment STAN - Transaction number BCODE - Authorization code
For each invoice number in the notification the merchant should send back status: OK - if everything is all right ERR - for error NO - if he does not know about this invoice At the sending back of OK or NO the system stops sending notification about the given invoice.
Sample reply of the merchant:
INVOICE=123456:STATUS=OK INVOICE=123457:STATUS=ERR INVOICE=123458:STATUS=NO
If there is something incorrect in the notification sent by the ePay.bg system the merchant sends back ERR=description.
Example:
ERR=description of the global error (for example incorrect CHECKSUM)
If the merchant has not announced URL, at which he can receive notifications about the payments, does not want or does not have the possibility to process these notifications, the merchant can see the status of his payment orders in the ePay.bg system.
If ePay.bg does not mark certain invoice as received by the merchant (for example returned status ERR or failed communication) the system will make an attempt to send the failed notifications again.
Scheme for sending notifications to a given invoice:
1) 5 attempts at an interval of < 1 minute 2) 4 attempts at an interval of 15 minutes 3) 5 attempts at an interval of 1 hour 4) 6 attempts at an interval of 3 hours 5) 4 attempts at an interval of 6 hours 6) 1 attempt a day
The system stops sending notification for a given invoice, if it is not received by the merchant in the course of 30 days.
______________________________________________________________________
The scheme is the same as ``(I) Payment request by WEB merchant, with the difference that PAGE=credit_paydirect.
Example:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="credit_paydirect"> <input type=hidden name=LANG value="[LANG]"> <input type=hidden name=ENCODED value="[ENCODED]"> <input type=hidden name=CHECKSUM value="[CHECKSUM]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
LANG = bg | en
(*) If the ePay.bg DEMO system is used at address: https://demo.epay.bg/, the TEST payment requests will be sent to it!!!
______________________________________________________________________
The amount paid by customer is received at a Microaccount of the receiver. Both customer and receiver must be registered in ePay.bg
The request for ``Free transfer'' is sent as HTTP POST request to https://www.epay.bg/
Example:
<form action="https://www.epay.bg/" method=post> <input type=hidden name=PAGE value="paylogin"> <input type=hidden name=MIN value="[MIN]"> <input type=hidden name=INVOICE value="[INVOICE]"> <input type=hidden name=TOTAL value="[TOTAL]"> <input type=hidden name=DESCR value="[DESCR]"> <input type=hidden name=ENCODING value="[ENCODING]"> <input type=hidden name=URL_OK value="http://..."> <input type=hidden name=URL_CANCEL value="http://..."> <input type=submit> </form>
The value of field PAGE is obligatorily ``paylogin''.
MIN (obligatory Identification number in ePay.bg) INVOICE (optional Invoice number) TOTAL (obligatory Amount) DESCR (optional Description up to 100 characters) ENCODING (optional encoding of the DESCR parameter)
MIN - only digits ( corresponds to CIN in personal data of the receiver ) INVOICE - only digits TOTAL - valid amount > 0.01 ( for example: 22, 22.8, 22.80 ) DESCR - CP1251 characters if not passed another ENCODING ENCODING - accepted is only utf-8
AMOUNT is acceptable equivalently to TOTAL.
Scheme:
Receiver --[REQUEST FOR FREE TRANSFER]--> ePay.bg Customer --[ENTRY]--[REQUEST RECORD]--> ePay.bg
Fields URL_OK and URL_CANCEL are optional:
URL_OK - URL to which the customer will be referred in case he
confirms the payment (does not guarantee the payment will be done)
URL_CANCEL - URL to which the customer will be referred in case he
rejects the payment
In this scheme of payment there is neither signing of the requests nor notifications sending to the merchant about the payment status.
______________________________________________________________________
END