Интеграция API Альфабанк Эквайринг на сайт для приема платежей

Author Автор: Роман Чернышов    Опубликовано: 28 июня 2021

Альфабанк Эквайринг Доброго времени друзья! На рынке банковских услуг РФ, Альфабанк занимает одно из лидирующих мест(а именно 4 место) по размеру активов, количеству отделений и конечно же клиентской базе. Но, за что клиенты действительно любят этот банк, это — передовые, инновационные решения, дающие им широкие возможности работы с денежными средствами, от мобильного приложения до «личного кабинета» предпринимателя, позволяющего работать с расчетным счетом онлайн. В том числе, одним из таких решений, является услуга интернет эквайринга, позволяющая предпринимателям принимать онлайн-платежи, картами МИР, Visa, MS, от пользователей на своем сайте интернет-магазина(портала, сервиса и т.д.). Далее я расскажу о технической стороне, об API эквайринга, с примерами.

Алгоритм подключения

Для подключение сайта к платежному шлюзу необходимо выполнить следующие шаги:

  1. Получить тестовые данные доступа к шлюзу и личному кабинету, логин и пароль, от сотрудника банка;
  2. Подготовить на сайте страницу, где будет размещаться форма для приема платежей, с вводом данных карты;
  3. Произвести техническую интеграцию сайта по API с платежным шлюзом, с использованием документации и примеров кода на PHP;
  4. Подготовить сайт в соответствии с документацией — требованиями банка к сайтам интернет-магазинам;
  5. Произвести тестирование приема платежей на сайте с использованием тестовых данных, в том числе данных карт оплаты;
  6. По результатам успешного тестирования связаться с поддержкой Альфабанка, прислав им скриншоты и описание тестов;
  7. После проверки и одобрения со стороны банка, получить боевые данные доступа к шлюзу и перевести работу системы в боевой режим.

Список доступных методов

  • Регистрация заказа с предавторизацией
  • Регистрация заказа
  • Расширенный запрос состояния заказа
  • Запрос статистики по платежам за период
  • Запрос списка связок определённой банковской карты
  • Запрос списка связок клиента
  • Запрос состояния заказа
  • Запрос проверки вовлеченности карты в 3DS
  • Запрос проведения платежа по связке
  • Запрос отмены оплаты заказа
  • Запрос оплаты через внешнюю платёжную систему
  • Запрос на регулярный платёж
  • Запрос на оплату через Samsung Pay
  • Запрос на оплату через Apple Pay
  • Запрос на оплату через Google Pay
  • Запрос изменения срока действия связки
  • Запрос завершения оплаты заказа
  • Запрос добавления дополнительных параметров к заказу
  • Запрос деактивации связки
  • Запрос возврата средств оплаты заказа
  • Запрос активации связки
  • Запрос получения QR кода по СБП

Примеры кода

<?php
 
/**
 * ДАННЫЕ ДЛЯ ПОДКЛЮЧЕНИЯ К ПЛАТЕЖНОМУ ШЛЮЗУ
 *
 * USERNAME         Логин магазина, полученный при подключении.
 * PASSWORD         Пароль магазина, полученный при подключении.
 * GATEWAY_URL      Адрес платежного шлюза.
 * RETURN_URL       Адрес, на который надо перенаправить пользователя
 *                  в случае успешной оплаты.
 */
define('USERNAME', 'USERNAME');
define('PASSWORD', 'PASSWORD');
define('GATEWAY_URL', 'https://server/payment/rest/');
define('RETURN_URL', 'http://your.site/rest.php');
 
/**
 * ФУНКЦИЯ ДЛЯ ВЗАИМОДЕЙСТВИЯ С ПЛАТЕЖНЫМ ШЛЮЗОМ
 *
 * Для отправки POST запросов на платежный шлюз используется
 * стандартная библиотека cURL.
 *
 * ПАРАМЕТРЫ
 *      method      Метод из API.
 *      data        Массив данных.
 *
 * ОТВЕТ
 *      response    Ответ.
 */
function gateway($method, $data) {
    $curl = curl_init(); // Инициализируем запрос
    curl_setopt_array($curl, array(
        CURLOPT_URL => GATEWAY_URL.$method, // Полный адрес метода
        CURLOPT_RETURNTRANSFER => true, // Возвращать ответ
        CURLOPT_POST => true, // Метод POST
        CURLOPT_POSTFIELDS => http_build_query($data) // Данные в запросе
    ));
    $response = curl_exec($curl); // Выполняем запрос
 
    $response = json_decode($response, true); // Декодируем из JSON в массив
    curl_close($curl); // Закрываем соединение
    return $response; // Возвращаем ответ
}
 
/**
 * ВЫВОД ФОРМЫ НА ЭКРАН
 */
if ($_SERVER['REQUEST_METHOD'] == 'GET' && !isset($_GET['orderId'])) {
    echo '
        <form method="post" action="/rest.php">
            <label>Order number</label><br />
            <input type="text" name="orderNumber" /><br />
            <label>Amount</label><br />
            <input type="text" name="amount" /><br />
            <button type="submit">Submit</button>
        </form>
    ';
}
 
/**
 * ОБРАБОТКА ДАННЫХ ИЗ ФОРМЫ
 */
else if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    $data = array(
        'userName' => USERNAME,
        'password' => PASSWORD,
        'orderNumber' => urlencode($_POST['orderNumber']),
        'amount' => urlencode($_POST['amount']),
        'returnUrl' => RETURN_URL
    );
 
    /**
     * ЗАПРОС РЕГИСТРАЦИИ ОДНОСТАДИЙНОГО ПЛАТЕЖА В ПЛАТЕЖНОМ ШЛЮЗЕ
     *      register.do
     *
     * ПАРАМЕТРЫ
     *      userName        Логин магазина.
     *      password        Пароль магазина.
     *      orderNumber     Уникальный идентификатор заказа в магазине.
     *      amount          Сумма заказа в копейках.
     *      returnUrl       Адрес, на который надо перенаправить пользователя в случае успешной оплаты.
     *
     * ОТВЕТ
     *      В случае ошибки:
     *          errorCode       Код ошибки. Список возможных значений приведен в таблице ниже.
     *          errorMessage    Описание ошибки.
     *
     *      В случае успешной регистрации:
     *          orderId         Номер заказа в платежной системе. Уникален в пределах системы.
     *          formUrl         URL платежной формы, на который надо перенаправить браузер клиента.
     *
     *  Код ошибки      Описание
     *      0           Обработка запроса прошла без системных ошибок.
     *      1           Заказ с таким номером уже зарегистрирован в системе.
     *      3           Неизвестная (запрещенная) валюта.
     *      4           Отсутствует обязательный параметр запроса.
     *      5           Ошибка значения параметра запроса.
     *      7           Системная ошибка.
     */
    $response = gateway('register.do', $data);
 
    /**
     * ЗАПРОС РЕГИСТРАЦИИ ДВУХСТАДИЙНОГО ПЛАТЕЖА В ПЛАТЕЖНОМ ШЛЮЗЕ
     *      registerPreAuth.do
     *
     * Параметры и ответ точно такие же, как и в предыдущем методе.
     * Необходимо вызывать либо register.do, либо registerPreAuth.do.
     */
//    $response = gateway('registerPreAuth.do', $data);
 
    if (isset($response['errorCode'])) { // В случае ошибки вывести ее
        echo 'Ошибка #' . $response['errorCode'] . ': ' . $response['errorMessage'];
    } else { // В случае успеха перенаправить пользователя на платежную форму
        header('Location: ' . $response['formUrl']);
        die();
    }
}
 
/**
 * ОБРАБОТКА ДАННЫХ ПОСЛЕ ПЛАТЕЖНОЙ ФОРМЫ
 */
else if ($_SERVER['REQUEST_METHOD'] == 'GET' && isset($_GET['orderId'])){
    $data = array(
        'userName' => USERNAME,
        'password' => PASSWORD,
        'orderId' => $_GET['orderId']
    );
 
    /**
     * ЗАПРОС СОСТОЯНИЯ ЗАКАЗА
     *      getOrderStatus.do
     *
     * ПАРАМЕТРЫ
     *      userName        Логин магазина.
     *      password        Пароль магазина.
     *      orderId         Номер заказа в платежной системе. Уникален в пределах системы.
     *
     * ОТВЕТ
     *      ErrorCode       Код ошибки. Список возможных значений приведен в таблице ниже.
     *      OrderStatus     По значению этого параметра определяется состояние заказа в платежной системе.
     *                      Список возможных значений приведен в таблице ниже. Отсутствует, если заказ не был найден.
     *
     *  Код ошибки      Описание
     *      0           Обработка запроса прошла без системных ошибок.
     *      2           Заказ отклонен по причине ошибки в реквизитах платежа.
     *      5           Доступ запрещён;
     *                  Пользователь должен сменить свой пароль;
     *                  Номер заказа не указан.
     *      6           Неизвестный номер заказа.
     *      7           Системная ошибка.
     *
     *  Статус заказа   Описание
     *      0           Заказ зарегистрирован, но не оплачен.
     *      1           Предавторизованная сумма захолдирована (для двухстадийных платежей).
     *      2           Проведена полная авторизация суммы заказа.
     *      3           Авторизация отменена.
     *      4           По транзакции была проведена операция возврата.
     *      5           Инициирована авторизация через ACS банка-эмитента.
     *      6           Авторизация отклонена.
     */
    $response = gateway('getOrderStatus.do', $data);
 
    // Вывод кода ошибки и статус заказа
    echo '
        <b>Error code:</b> ' . $response['ErrorCode'] . '<br />
        <b>Order status:</b> ' . $response['OrderStatus'] . '<br />
    ';
}
?>

Тестовые карты

В качестве Cardholder name (Имя владельца карты) указывайте от 2 слов в английской раскладке (например, IVANOV IVAN).
Для всех карт, вовлечённых в 3-D Secure (veres=y, pares=y или a) пароль на ACS: 12345678.

Карты с успешным результатом оплаты:

Номер карты Срок действияCVV2/CVC2 Вовлеченность карт в 3-D Secure
4111 1111 1111 11112024/12123veres=y, pares=y
5100 0000 0000 00082024/12123veres=y, pares=y
6011 0000 0000 00042024/12123veres=y, pares=y
6390 0200 0000 0000032024/12123 (необязательный параметр)veres=y, pares=a
5555 5555 5555 55992024/12123veres=n
4444 0000 0000 11112024/12123veres=n
2200 0000 0000 00042024/12123veres=n
2200 0000 0000 00122024/12123veres=y pares=n
2200 0000 0000 00202024/12123veres=u
2200 0000 0000 00382024/12123veres=y pares=u
2200 0000 0000 00462024/12123veres=y pares=a
2200 0000 0000 00532024/12123veres=y pares=y

Карты, возвращающие ошибки

PAN Exp dateCVV23-D SecureError message
5555 5555 5555 55572024/12123veres=y, pares=uDeclined. PaRes status is U (-2011)
4444 3333 2222 11112024/12123veres=y, pares=uDeclined. PaRes status is U (-2011)
4000 0000 0000 00022024/12123veres=uDeclined. VeRes status is U (-2016)
5555 5555 4444 44422024/12123veres=uDeclined. VeRes status is U (-2016)
4444 4444 4444 44222024/12123N/AInvalid message format (913)
4444 4444 4444 44552024/12123N/ACard limitations exceeded (902)
4444 4444 4444 33332024/12123N/ALimit exceeded (123)
4444 4444 4444 66662024/12123N/ABLOCKEDBYLIMIT (-20010)
4444 4444 1111 11112024/12123N/ANetwork refused transaction (5)
4444 4444 9999 99992024/12123N/ATDSECCOMMERROR (151017)
5432 5432 5432 54302022/12123N/AINSUFFICIENT_FUNDS (116)

Заключение

Из описанного выше примера, вы можете видеть, что базовый функционал по интеграции приема платежей на сайте с использованием API эквайринга Альфабанка, реализуется достаточно просто, остается только произвести соответствующую доработку функционала на стороне сайта интернет-магазина. По работе со всеми доступными методами Альфабанк предоставляет достаточно обширную документацию, в случае возникновения сложностей всегда можно обратиться в их техническую поддержку по емаил. Также если вам нужна помощь или вы хотите заказать работу по интеграции, я всегда рад помочь вам, обращайтесь!

Оставить комментарий

Автор блога
Роман Чернышов
Веб-разработчик,
Full Stack
Senior, Architect
PHP, JavaScript, Node.JS, Python, HTML 5, CSS 3, MySQL, Bash, Linux Admin
Заказать работу
предложить оффер

Моя книга
Книга. Веб-разработчик. Легкий вход в профессию
Печатная книга
Веб-разработчик.
Легкий вход в профессию
Оформить предзаказ
Последние вопросы
Список вопросов
Последние комментарии
Меню

Archive

Мои проекты
Insurance CMS Love Crm CMS Совместные покупки Мой PHP Framework Хостинг для моих клиентов Лицензии на мой софт и поддержка