Preauthorization

What is preauthorization? - Prepayment, which ensures that the customer has sufficient funds or credit limit to cover the transaction. It is often used when the final payment amount is uncertain, such as hotel reservations, car rentals, or dining in restaurants.

Description of the process

1. A customer initiates a payment process on the merchant's website or platform by selecting a credit or debit card payment option.
2. The merchant initiates a Preauthorization request by sending the required information.
3. The customer is redirected to a payment page where they must enter their card details.
4. After successfully entering the card details, the amount requested for reauthorization will be blocked. This means that this amount cannot be spent or made available to the customer until a confirmation or cancel request is made within the next 30 days.
   • After the 30-day period expires and no action is taken by the merchant, the request will be automatically cancelled.
5. ePay.bg sends a confirmation (notification) to the merchant, informing him that the preauthorization request has been paid or cancelled.
   • To receive real-time notifications about the status of payments, you need to develop a Payment Notification.
   • With this notification, the merchant will have information if the amount is withheld.
6. For each reauthorization request, it is mandatory to send only one of the requests:
   • Confirmation request
   • Cancel request
7. After each confirmation or cancel request, the merchant must send a check:
   • Preauthorization confirmation check
   • Preauthorization cancel check

Important

You need to have Payment Notification developed to receive real-time information about customer payments.

If you do not have a payment notice developed and the customer for some reason fails to complete the preauthorization request (did not enter his data, refused, no money or time expired), and at the same time you try to take the amount (confirmation) or cancel, then you will receive an error.

Communication scheme

Production environment

Method	WEB_ADDRESS
POST	https://www.epay.bg/v3main/

Demo environment

Entry point for testing purposes.

Method	WEB_ADDRESS
POST	https://demo.epay.bg/xdev/web/

The following cards with a correct validity date (any future date) and any CVC code can be used for test requests:

For successful payment:

Mastercard: 5100770000000022
VISA: 4341792000000044

For VISA cards

Code 111111 may be required for tests with an amount over BGN 30 and the need for password confirmation.

For failed payment:

Mastercard: 5555000000070019

Preauthorization request

Method	Address
POST	WEB_ADDRESS/paylogin

Parameters	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 merchant's secret word.	Mandatory

Parameters in ENCODED

Parameters	Type	Description	Optionality
MIN	int	Customer Identification Number (CIN)	Mandatory
EMAIL	string	Email of the merchant in the system	Optional
INVOICE	int	Invoice number; unique to the 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 the DESCR parameter. Only utf-8 is accepted; can also be passed as an HTTP parameter	Optional
PREAUTH	int	= 1 - requests payment by preauthorization	Mandatory

Note

The protocol formation is the same as in Online payment, the only difference is that PREAUTH=1  is added to ENCODED in this request.

Response

OKProcessingError

STATUS=OK

STATUS=PROCESSING

ERR=Description of the error

For tests you must submit and force_credit_paydirect=1.

Confirmation request

Method	Address
POST	WEB_ADDRESS/preauth/confirm

Information

In the event that a smaller amount is submitted, it is entered in the accounts and the balance is released.

Parameters	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 merchant's secret word.	Mandatory

Parameters in ENCODED

Parameters	Type	Description	Optionality
MIN	int	MIN from the original preauthorization request	Mandatory
INVOICE	int	INVOICE from the original preauthorization request	Mandatory
ORIGINAL_AMOUNT	float	Amount from the preauthorization	Mandatory
CONFIRM_AMOUNT	float	Amount to be actually taken at confirmation; must be less than or equal to ORIGINAL_AMOUNT	Mandatory

Preauthorization confirmation check

Method	Address
POST	WEB_ADDRESS/preauth/confirm/status

Parameters	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 merchant's secret word.	Mandatory

Parameters in ENCODED

Parameters	Type	Description	Optionality
MIN	int	MIN from the original preauthorization request	Mandatory
INVOICE	int	INVOICE from the original preauthorization request	Mandatory
ORIGINAL_AMOUNT	float	Amount from the preauthorization	Mandatory
CONFIRM_AMOUNT	float	The amount submitted for claim at confirmation request	Mandatory

Cancel request

Method	Address
POST	WEB_ADDRESS/preauth/cancel

Parameters	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 merchant's secret word.	Mandatory

Parameters in ENCODED

Parameters	Type	Description	Optionality
MIN	int	MIN from the original preauthorization request	Mandatory
INVOICE	int	INVOICE from the original preauthorization request	Mandatory
ORIGINAL_AMOUNT	float	Amount from the preauthorization	Mandatory
REV_AMOUNT	float	=ORIGINAL AMOUNT (Amount from the preauthorization)	Mandatory

Preauthorization cancel check

Method	Address
POST	WEB_ADDRESS/preauth/cancel/status

Parameters	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 merchant's secret word.	Mandatory

Parameters in ENCODED

Parameters	Type	Description	Optionality
MIN	int	MIN from the original preauthorization request	Mandatory
INVOICE	int	INVOICE from the original preauthorization request	Mandatory
ORIGINAL_AMOUNT	float	Amount from the preauthorization	Mandatory
REV_AMOUNT	float	=ORIGINAL AMOUNT (Amount from the preauthorization)	Mandatory