Регистрация в системе

  • При регистрации выберите тип аккаунта "Merchant"
  • Для активации аккаунта обратитесь в службу поддержки support@billline.net
  • После активации аккаунта выполните вход в личный кабинет, создайте мерчанта. Для этого заполните следующие поля:
    • Название
    • URL Вашего сайта
    • Секретный ключ (обратите внимание, данный ключ будет использоваться при подписи запроса)
    • URL обработчика платажей (Process URL)
    • URL страницы удачного платежа (Success URL)
    • URL страницы неудачного платежа (Fail URL)
    • URL для отправки callback
  • Для активации мерчанта обратитесь в службу поддержки support@billline.net
  • На странице списка мерчантов в графе Action нажмите кнопку настроек и перейдите на форму генератора (HTML Form generator)
  • В поля слева введите начальные данные (наименование товара, номер заказа, стоимость) и нажмите на кнопку "Generate"
  • В поле справа появится пример формы для приема оплаты
  • Поле currency может принимать значения UAH, RUB
  • Поле customer не обрабатывается
  • Пример формы:
        
            <form method="POST" action="https://<предоставленный url>/payment/form">
                <input type="hidden" name="merchant" value="M1VJDHSI6DYXS" />
                <input type="hidden" name="item_name" value="Samsung TV" />
                <input type="hidden" name="order" value="20" />
                <input type="hidden" name="amount" value="16" />
                <input type="hidden" name="currency" value="UAH" />
                <input type="hidden" name="first_name" value="IVAN" />
                <input type="hidden" name="last_name" value="IVANOV" />
                <input type="hidden" name="country" value="UA" />
                <input type="hidden" name="ip" value="212.10.20.75" />
                <input type="hidden" name="custom" value=""/>
                <button type="submit"> Купить </button>
            </form>
        
                                    
  • Поле в личном кабинете в настройках мерчанта “Send URL in Form” – YES/NO.
    При выборе значения “YES” в форму можно добавить три поля:

    success_url – страница удачной оплаты (link) fail_url – страница неудачной оплаты (link) process_url – обработчик платежей на стороне магазина (link)
  • При отсутствии какого-либо поля используется URL указанный в настройках мерчанта.
  • В настройках мерчанта указывается метод передачи ответа GET или POST.
  • Добавлены поля идентификации клиента:

    first_name – имя клиента. Максимальная длина: 30 символов last_name – фамилия клиента. Максимальная: 30 символов country – страна клиента в ISO 3166-1 alpha-2 формате ip – IP адрес клиента

Success URL – страница, на которую переправляется покупатель при успешном проведении

  • При удачном проведении платежа покупатель переводится на страницу Success URL
  • Данные передаются методом POST:

    order_no – номер платежа, переданный в форме платежа (номер заказа Order) amount – сумма currency – валюта item_name – наименование товара co_inv_id – номер платежа в платежной системе co_inv_st – статус платежа в платежной системе (Success)
  • Пример:
    
            Array (
                [order_no] => 20
                [amount] => 16
                [currency] => UAH
                [item_name] => Supergame
                [co_inv_id] => 26
                [co_inv_st] => success
            )
                                    

Fail URL

  • При отказе от оплаты покупатель переводится на страницу Fail URL
  • Данные передаются методом POST. Список переменных (см.п.2)
  • Статус платежа co_inv_st – Canceled
  • Пример:
                                        
            Array (
                [order_no] => 20
                [amount] => 16
                [currency] => UAH
                [item_name] => Supergame
                [co_inv_id] => 27
                [co_inv_st] => canceled
            )
                                        
                                    
*Внимание! Перевод покупателя на Success URL или Fail URL является только информационным и не может подтверждать прием или отказ в приеме платежа!

Process URL – обработчик платежей на стороне магазина

  • При успешном проведении платежа на сервер магазина Process URL передаются данные о платеже методом POST:

    co_inv_id – номер платежа в платежной системе co_inv_crt – дата создания платежа co_inv_prc – дата проведения платежа co_inv_st – статус успешного проведения success co_order_no – номер платежа, передан в форме платежа (номер заказа) co_amount – сумма платежа co_to_wlt – сумма зачисления на счет мерчанта (за вычетом комиссий) co_cur => UAH – валюта платежа co_merchant_id – ID мерчанта co_merchant_uuid – уникальный номер мерчанта co_sign – подпись ключом мерчанта
  • Обновление от (14.05.2020). В список полей добавлено поле co_card_number. Это поле по умолчанию отсутствует в ответе. Чтобы получать его в ответе на Process URL, необходимо в настройках мерчанта установить поле “Cardmask in callback” в значение “YES”.

  • Пример:
                                        
            Array
            (
                [co_inv_id] => 34
                [co_inv_crt] => 2019-02-19 19:12:04
                [co_inv_prc] => 2019-02-19 19:12:11
                [co_inv_st] => success
                [co_order_no] => 20
                [co_amount] => 16
                [co_to_wlt] => 15.76
                [co_cur] => UAH
                [co_merchant_id] => 1
                [co_merchant_uuid] => M1VJDHSI6DYXS
                [co_sign] => pQQgUBfjz+XxRSpwo5srmw==
            )
                                        
                                    
  • При отказе в проведении платежа на сервер магазина Process URL передаются данные об ошибочном платеже методом POST:

    co_inv_id – номер платежа в платежной системе co_inv_crt – дата создания платежа co_inv_prc – дата обновления платежа co_inv_st – статус отказа проведения fail co_order_no – номер платежа, переданный в форме платежа (номер заказа) co_merchant_id – ID мерчанта co_merchant_uuid – уникальный номер мерчанта co_sign – подпись ключом мерчанта
  • Пример:
                                        
            Array
            (
                [co_inv_id] => 34
                [co_inv_crt] => 2019-02-19 19:12:04
                [co_inv_prc] => 2019-02-19 19:12:11
                [co_inv_st] => fail
                [co_order_no] => 20
                [co_merchant_id] => 1
                [co_merchant_uuid] => M1VJDHSI6DYXS
                [co_sign] => pQQgUBfjz+XxRSpwo5srmw==
            )
                                        
                                    
  • В ответ на принятый пакет сервер магазина должен ответить двумя английскими буквами «OK».

Электронная подпись

  • Все поля формы с префиксом "co_" должны быть отсортированы по алфавиту.
  • В конец добавляется секретный ключ мерчанта.
  • Конкатенация всех полей идет через символ ":" без их названия.
  • Пример строки для подписи:
                                        
            16:RUB:2019-02-19 19:12:04:2019-02-19
            19:12:11:success:1:M1VJDHSI6DYXS:20:34:15.76:SecRetKey0123
                                        
                                    
  • Полученная строка хешируется методом MD5 и его байтовое представление кодируется в Base64.
  • co_sign = Base64(MD5(Implode(Sort(Params) + SecretKey, ':'))));
  • Пример подписи данных для запроса Payout Send, Payout Status (PHP):
                                        
            $post = ['merchant' => ‘M1VJDHSI6DYXS’,
                'method' => 1,
                'payout_id' => ‘ex1’,
                'account' => '4751xxxxxxxxxx62',
                'amount' => 1.19,
                'currency' => 'UAH'];
            $dataSet = $data;
            ksort($dataSet, SORT_STRING);
            array_push($dataSet, 'SecRetKey0123’);
            $signString = implode(':', $dataSet);
            $calc_sign = base64_encode(md5($signString, true));
            $post['sign'] = $calc_sign;
                                        
                                    
  • Проверка электронной подписи:
                                        
            $secret_key = 'SecRetKey0123’; // секретный ключ мерчанта
            $dataSet = json_decode($response, TRUE);
            $sign = $dataSet['sign'];
            unset($dataSet['sign']);
            ksort($dataSet, SORT_STRING);
            array_push($dataSet, $secret_key);
            $signString = implode(':', $dataSet);
            $calc_sign = base64_encode(md5($signString, true));
    
            if ($sign != $calc_sign) {
                // Sign error
                echo ('Sign error');
            } else {
                echo 'Sign Ok';
            }
                                        
                                    
  • Ответ на статус ‘Error’ не подписывается. Описание ошибки в поле ‘description’

Запрос статуса платежа

  • Запрос статуса платежа отправляется на URL https://<предоставленный url>/payment/status
  • Метод передачи данных может быть POST или GET
  • Поля для запроса статуса:

    merchant – идентификатор мерчанта order – номер платежа в системе мерчанта co_inv_id – номер платежа в системе BillLine (номер передается после обработки платежа на Process URL мерчанта) sign – подпись запроса (link)
  • В ответ на запрос возвращаются данные в формате JSON:

    status – Success, Pending, Fail, Refund, Error order – ID платежа в системе мерчанта description – описание статуса card_number – номер карты плательщика в формате NNNNNNXXXXXXNNNN, где N-цифра; поле передается только при status=’success’ sign – подпись ключом мерчанта
    Где:
    success – платеж проведен pending – платеж новый или находится в очереди на обработке fail – платеж ошибочный refund – платеж возвращен error – ошибка принятых данных (подпись в ответе пустая “sign” = “”)
  • (Обновлено от 23.07.2020) Статусы Success, Fail, Refund – финальные. Статус Error не финальный и является основанием для выяснения причины возникновения данного статуса
  • Статус Pending требует дополнительного запроса Payment Status

Запрос баланса

  • Запрос баланса отправляется на URL https://<предоставленный url>/payment/balance
  • Метод передачи данных POST
  • Поля для запроса статуса:

    merchant – идентификатор мерчанта currency – запрашиваемая валюта (UAH, RUB) sign – подпись запроса (link)
  • В ответ на запрос возвращаются данные в формате JSON:

    status – Success, Error currency – валюта (UAH, RUB) balance – доступная сумма в валюте с двумя знаками после запятой, разделитель точка (например 212.07) description – описание статуса sign – подпись ключом мерчанта
    Где:
    success – запрос успешен error – ошибка принятых данных (в случае, если мерчант не найден, подпись в ответе будет пустая “sign” = “”)

Запрос списка платежей

  • Запрос списка платежей отправляется на URL https://<предоставленный url>/api/payment-list
  • Метод передачи данных может быть POST или GET
  • Обязательные поля для получения списка платежей:

    merchant – идентификатор мерчанта currency – валюта платежей (UAH, RUB) order – номер платежа в системе мерчанта, с которого начинается выборка в заданном периоде (Если передается 0, то возвращаются все транзакции) start_date – дата и время начала периода в формате YYYY-MM-DD HH:ii:ss finish_date – дата и время окончания периода в формате YYYY-MM-DD HH:ii:ss status – статус транзакций, которые будут выбраны (all, success, pending, blocked, refund) type – тип транзакции withdrawal, deposit sign – подпись запроса (link)
  • Запросы обрабатываются не более одного в минуту
  • Максимальное количество транзакций в ответе 10 000
  • Ответ возвращается в формате JSON:
                                        
            {
                "id":"id",
                "uid":"uid",
                "order_id":"order_id",
                "subtotal":subtotal,
                "fee_percentage":fee_percentage,
                "fee_fixed":fee_fixed,
                "total":total,
                "currency":"currency",
                "type":"type",
                "status":"type",
                "created_at":"created_at",
                "updated_ad":"created_at"
            }
                                        
                                    
  • Пример ответа:
                                        
            {
                "id":"201",
                "uid":"64TE02NPNBKP9",
                "order_id":"180",
                "subtotal":10.29,
                "fee_percentage":0,
                "fee_fixed":0,
                "total":10.29,
                "currency":"UAH",
                "type":"Deposit",
                "status":"Success",
                "created_at":"2020-01-01 15:31:08",
                "updated_ad":"2020-01-11 18:33:58"
            },{
                "id":"242",
                "uid":"F0G9IZ6GSMORR",
                "order_id":"181",
                "subtotal":100.18,
                "fee_percentage":0,
                "fee_fixed":0,
                "total":100.18,
                "currency":"UAH",
                "type":"Deposit",
                "status":"Success",
                "created_at":"2020-02-24 21:24:02",
                "updated_ad":"2020-02-24 21:24:02"
            },{
                "id":"248",
                "uid":"LRYT78S3NBZW8",
                "order_id":"182",
                "subtotal":100.18,
                "fee_percentage":0,
                "fee_fixed":0,
                "total":100.18,
                "currency":"UAH",
                "type":"Deposit",
                "status":"Success",
                "created_at":"2020-02-24 21:24:35",
                "updated_ad":"2020-02-24 21:24:35"
            }
                                        
                                    

Payout Send

  • URL запроса – https://<предоставленный url>/merchant/api/payout_send
  • Данные передаются методом POST:

    merchant – уникальный номер мерчанта (пример M1VJDHSI6DYXS) method – метод выплаты. Целое число. 1 – Visa/Mastercard UAH 2 – Bitcoin (Beta) 3 – Visa/Mastercard RUB payout_id – номер исходящего платежа в системе мерчанта (латинские буквы и цифры) account – номер карточки Visa или Mastercard или адрес получателя Bitcoin amount – сумма в валюте, разделитель точка “.” currency – UAH для метода 1 и 2; RUB для метода 3 sign – подпись ключом мерчанта
  • В ответ возвращаются данные в формате JSON:

    status – Success, Pending, Blocked, Error code – расширенный код статуса (link) payout_id – ID платежа в системе BillLine description – описание статуса sign – подпись ключом мерчанта
    Где
    Success – платеж проведен Pending – платеж новый или находится в очереди на обработке Blocked – платеж ошибочный Error – ошибка принятых данных (подпись ответа пустым ключом)
  • (Обновлено от 23.07.2020) Статусы Success, Fail, Refund – финальные. Статус Error не финальный и является основанием для выяснения причины возникновения данного статуса
  • Статус Pending требует дополнительного запроса Payment Status
  • Примеры ответов:
                                        
            {
                "status":"Errror",
                ”code”:”4”,
                "payout_id":"",
                "description":"Merchant not found or blocked",
                "sign":"IbCvAOUorZYEXJPiuyxHF1=="
            }
    
            {
                "status":"Pending",
                ”code”:”40”,
                "payout_id":"ex211",
                "description":"Payment in order",
                "sign":"SNplBJ47mTVRvS6ZTdh1EQ=="
            }
    
            {
                "status":"Success",
                ”code”:”0”,
                "payout_id":188,
                "description":"Payment successful. Status final",
                "sign":"\/WEoLZ7fiYEeQmkfq2U3jw=="
            }
                                        
                                    

Payout Status

  • Данные передаются методом POST:
  • URL запроса – https://<предоставленный url>/merchant/api/payout_status

    merchant – уникальный номер мерчанта (пример M1VJDHSI6DYXS) payout_id – номер исходящего платежа в системе мерчанта (латинские буквы и цифры) sign – подпись ключом мерчанта
  • В ответ возвращаются данные в формате JSON:

    status – Success, Pending, Blocked, Error code – расширенный код статуса (link) payout_id – ID платежа в системе BillLine sign – подпись ключом мерчанта
    Где:
    Success – платеж проведен Pending – платеж новый или находится в очереди на обработке Blocked – платеж ошибочный Error – ошибка принятых данных (подпись пустым ключом)
  • (Обновлено от 23.07.2020) Статусы Success, Fail, Refund – финальные. Статус Error не финальный и является основанием для выяснения причины возникновения данного статуса
  • Статус Pending требует дополнительного запроса Payment Status
  • Пример ответа:
                                        
            {
                "status":"Error",
                ”code”:”4”,
                "payout_id":"",
                "description":"Merchant not found or blocked",
                "sign":"IbCvAOUorZYEXJPiuyxHF1=="
            }
                                        
                                    

Отправка статуса Callback

  • Уведомление будет отправлено, в случае изменения статуса транзакции. Чтобы его получить, нужно указать в настройках мерчанта поле “Send Withdraw Callback” значение “Yes”, а также задать “Callback Withdraw URL” на который будет отправляться ответ о результате проведения выплаты и метод, которым будут передаваться данные (GET или POST). Если эти действия не выполнить, то уведомление об изменении статуса транзакции отправлено не будет.

    Callback
  • Формат передаваемых данных:
                                        
            Array (
                co_inv_id - номер платежа в платежной системе
                co_inv_crt - дата создания платежа
                co_inv_prc - дата проведения платежа
                co_inv_st - статус успешного проведения success или fail
                co_payout_id - номер платежа в системе мерчанта (номер выплаты)
                co_merchant_uuid - уникальный номер мерчанта
                co_sign - подпись ключом мерчанта
            )
                                        
                                    
  • Пример:
                                        
            Array
            (
                [co_inv_id] => 34
                [co_inv_crt] => 2019-02-19 19:12:04
                [co_inv_prc] => 2019-02-19 19:12:11
                [co_inv_st] => Success
                [co_payout_id] => 20
                [co_merchant_uuid] => XXXXXXI6DYXS
                [co_sign] => pQQgUBfjz+XxRSpxxxxxxx==
            )
                                        
                                    

Запрос рекуррентного платежа

  • Запрос для проведения рекуррентного платежа отправляется на URL https://<предоставленный url>/payment/recurrent
  • Метод передачи данных может быть POST или GET
  • Поля для проведения рекуррентного платежа:

    merchant – идентификатор мерчанта order – номер платежа в системе мерчанта amount – сумма платежа currency – валюта платежей (в настоящий момент только UAH) rec_order – номер платежа в системе мерчанта, который был принят посредством формы оплаты. Платеж должен быть успешным process_url – обработчик платежей на стороне магазина (link) sign – подпись запроса (link)
  • Запросы обрабатываются не более одного в месяц по одной карте
  • Ответ возвращается в формате JSON

    в случае успеха:
    {'status' => 'success', 'description' => 'Payment success'}
    в случае ошибки:
    {'status': ‘error’, 'description': ‘Описание ошибки’'} - ошибка данных {'status': ‘fail’, 'description': ‘Описание ошибки’'} - отказ в проведении платежа
  • На адрес, указанный в запросе, отправляется callback в формате link
  • Если адрес не указали в запросе, callback будет отправлен на адрес из настроек мерчанта.

Запрос возврата принятого платежа

  • Запрос для возврата платежа отправляется на URL https://<предоставленный url>/payment/reversal
  • Метод передачи данных может быть POST или GET
  • Поля для проведения возврата платежа:

    merchant – идентификатор мерчанта order – номер платежа в системе мерчанта process_url – обработчик платежей на стороне магазина (link) sign – подпись запроса (link)
  • Ответ возвращается в формате JSON

    в случае успеха:
    {'status' : refund, 'description' : 'Payment refunded', 'sign' : 'подпись ответа (link)'}
    в случае ошибки:
    {'status' : ‘error’, 'description' : ‘Описание ошибки’'} - ошибка данных {'status' : ‘fail’, 'description' : ‘Описание ошибки’'} - отказ в возврате платежа)
  • На адрес, указанный в запросе, отправляется callback в формате link
  • Если адрес не указали в запросе, callback будет отправлен на адрес из настроек мерчанта.

Коды статуса

    Код статуса Статус Финальный Описание
    0 Success Да Выплата успешна
    2 Error Нет Ошибка входных данных
    3 Error Нет Платежный метод заблокирован
    4 Error Нет Марчант заблокирован
    5 Error Нет Ошибка валюты выплаты
    6 Error Нет Счет мерчанта заблокирован
    7 Error Нет Сумма превышает баланс
    8 Error Нет ID транзакции не найден
    10 Error Нет Повторный запрос выплаты, требуется запрос статуса транзакции
    40 Pending Нет Транзакция в обработке
    80 Blocked Да Отказано в выплате
    99 Error Нет Ошибка подписи в запросе
    100 Error Нет Ошибка не документирована