Преавторизация¶
Какво е преавторизация? - Предварително плащане, което гарантира, че клиентът разполага с достатъчно средства или кредитен лимит за покриване на транзакцията. Често се използва, когато крайната сума на плащането е несигурна, като хотелски резервации, коли под наем или хранене в ресторанти.
Описание на процеса¶
- Клиент започва процес на плащане уебсайт или платформа на търговеца, като избира опция за плащане с кредитна или дебитна карта.
- Търговецът инициира заявка за преавторизация, като изпраща необходимата информация.
- Клиента се пренасочва към страница за плащане, където трябва да въведе данните за картата си.
- След успешно въвеждане на данните за картата ще бъде блокирана сумата, която е поискана за преавторизация. Това означава, че тази сума не може да бъде изразходвана или достъпна на клиента до извършване на заявка за потвърждение или отказ в рамките на следващите 30 дни.
- След изтичане на периода от 30 дни, ако не бъдат предприети действия от страна на търговеца, заявката ще бъде отказана автоматично.
- ePay.bg изпраща потвърждение на търговеца (нотификация), като го информира, че заявката за преавторизация е заплатена или отказана.
- За да получавате в реално време нотификации за статуса на плащанията, трябва да разработите Известие за плащане.
- С тази нотификация, търговецът ще има яснота дали сумата е задържана.
- За всяка заявка за преавторизация, е задължително да се изпрати само една от заявките:
- След всяка заявка за потвърждение или отказ, е задължително търговецът да пусне проверка:
Важно
Необходимо е да имате разработено Известие за плащане, за да получавате информация в реално време за плащанията на клиенти.
Ако нямате разработено известие за плащане и клиентът по някаква причина не успее да завърши заявката за преавторизация (не си въведе данните, откаже, няма пари или изтече времето), а в същото време направите опит за взимане на сумата (потвърждение) или отказ, то Вие ще получите грешка.
Комуникационна схема¶
Продукционна среда¶
| Метод | WEB_ADDRESS |
|---|---|
| POST | https://www.epay.bg/v3main/ |
Демо среда¶
Входна точка за тестови цели.
| Метод | WEB_ADDRESS |
|---|---|
| POST | https://demo.epay.bg/xdev/web/ |
За тестови заявки може да се ползват следните карти с коректна дата на валидност (всяка бъдеща дата) и произволен CVC код:
За успешно плащане:
Mastercard: 5100770000000022
VISA: 4341792000000044
За карти VISA
Може да се изисква код 111111 за тестове със сума над 30лв и необходимост от потвърждение с парола.
За неуспешнo плащане:
Mastercard: 5555000000070019
Заявка за преавторизация¶
| Метод | Адрес |
|---|---|
| POST | WEB_ADDRESS/paylogin |
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| ENCODED | string | Кодирана с base64 (RFC 3548) заявка за плащане, EOL='' |
Задължителен |
| CHECKSUM | string | Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца | Задължителен |
Параметри в ENCODED
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| MIN | int | Съответства на КИН в личните данни на търговеца | Задължителен |
| string | Електронна поща на търговеца в системата | Опционален | |
| INVOICE | int | Номер на фактура; уникален за търговеца | Задължителен |
| AMOUNT | float | Валидна сума > 0.01 (например: 22, 22.8, 22.80) | Задължителен |
| CURRENCY | string | Приемани валути са BGN, USD или EUR; ако не се подаде е BGN по подразбиране |
Опционален |
| EXP_TIME | datetime | време на валидност на заявката; формат DD.MM.YYYY[hh:mm[:ss]] |
Задължителен |
| DESCR | string | Описание до 100 символа; CP1251 символи, ако не е подаден друг ENCODING |
Опционален |
| ENCODING | encoding | CP1251 (по подразбиране) или utf-8 | Опционален |
| PREAUTH | int | = 1 - заявява се плащане чрез преавторизация на сумата |
Задължителен |
Бележка
Формирането на протокола е същото както в Онлайн плащане, единствената разлика е, че в тази заявка се добавя PREAUTH=1 в ENCODED.
Oтговор
STATUS=OK
STATUS=PROCESSING
ERR=Описание на грешка
За тестове трябва да се подаде и force_credit_paydirect=1.
Заявка за потвърждение¶
| Метод | Адрес |
|---|---|
| POST | WEB_ADDRESS/preauth/confirm |
Информация
В случай, че се подаде по-малка сума, тя се осчетоводява и остатъкът се освобождава.
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| ENCODED | string | Кодирана с base64 (RFC 3548) заявка за плащане, EOL='' |
Задължителен |
| CHECKSUM | string | Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца | Задължителен |
Параметри в ENCODED
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| MIN | int | MIN от оригиналната заявка за преавторизация |
Задължителен |
| INVOICE | int | INVOICE от оригиналната заявка за преавторизация |
Задължителен |
| ORIGINAL_AMOUNT | float | Сума от преавторизацията | Задължителен |
| CONFIRM_AMOUNT | float | Сума, която ще се вземе реално при потвърждението; трябва да е по-малка или равна на ORIGINAL_AMOUNT |
Задължителен |
Проверка на потвърждение на преавторизация¶
| Метод | Адрес |
|---|---|
| POST | WEB_ADDRESS/preauth/confirm/status |
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| ENCODED | string | Кодирана с base64 (RFC 3548) заявка за плащане, EOL='' |
Задължителен |
| CHECKSUM | string | Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца | Задължителен |
Параметри в ENCODED
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| MIN | int | MIN от оригиналната заявка за преавторизация |
Задължителен |
| INVOICE | int | INVOICE от оригиналната заявка за преавторизация |
Задължителен |
| ORIGINAL_AMOUNT | float | Сума от преавторизацията | Задължителен |
| CONFIRM_AMOUNT | float | Сумата, която се е подала за вземане при заявката за потвърждение | Задължителен |
Заявка за отказ¶
| Метод | Адрес |
|---|---|
| POST | WEB_ADDRESS/preauth/cancel |
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| ENCODED | string | Кодирана с base64 (RFC 3548) заявка за плащане, EOL='' |
Задължителен |
| CHECKSUM | string | Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца | Задължителен |
Параметри в ENCODED
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| MIN | int | MIN от оригиналната заявка за преавторизация |
Задължителен |
| INVOICE | int | INVOICE от оригиналната заявка за преавторизация |
Задължителен |
| ORIGINAL_AMOUNT | float | Сума от преавторизацията | Задължителен |
| REV_AMOUNT | float | =ORIGINAL AMOUNT (сума от преавторизацията) |
Задължителен |
Проверка на отказ на преавторизация¶
| Метод | Адрес |
|---|---|
| POST | WEB_ADDRESS/preauth/cancel/status |
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| ENCODED | string | Кодирана с base64 (RFC 3548) заявка за плащане, EOL='' |
Задължителен |
| CHECKSUM | string | Контролна сума върху ENCODED, генерирана като HMAC с алгоритъм SHA-1 и секретната дума на търговеца | Задължителен |
Параметри в ENCODED
| Параметър | Тип | Описание | Опционалност |
|---|---|---|---|
| MIN | int | MIN от оригиналната заявка за преавторизация |
Задължителен |
| INVOICE | int | INVOICE от оригиналната заявка за преавторизация |
Задължителен |
| ORIGINAL_AMOUNT | float | Сума от преавторизацията | Задължителен |
| REV_AMOUNT | float | =ORIGINAL AMOUNT (сума от преавторизацията) |
Задължителен |