Перейти к содержанию

Установка платежного виджета

Для приема платежей от клиентов с помощью платежного виджета eComCharge выполните следующие действия:

  1. Установите скрипт виджета.

    Для проведения платежей пропишите на вашем сайте скрипт:

    <script type="text/javascript" src="https://js.ecomcharge.com/widget/be_gateway.js"></script>
    
  2. Создайте платежный виджет.

    Зарегистрируйте функцию, которая сформирует необходимые параметры для конструктора объекта BeGateway и вызовет у него метод createWidget. Оплата считается успешно завершенной только после получения автоматического уведомления о платеже.

    <script type="text/javascript">
        this.payment = function() {
            var params ={
                checkout_url: "https://checkout.ecomcharge.com",
                checkout: {
                    iframe: true,
                    test: true,
                    transaction_type: "payment",
                    public_key: "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3w/PWC6UPzzDsuV+760fviKz5/ytl6w6immXEvlxzHVm+rwJpYLPEp/gIftkoXl5wgRjzXhFsCBUqm+FNy9LGIqjunv4vKes8+IU8nvEDQk9YhjLH4hcenJbtMK1Zisk03f3rCoxjjxs1a/Z3QHYahjWvI+45K3A77wQ51EVGnvTTIvX1paazzkoN6udRfN9+yFxj1rYadp8oMDFEQPL3fwrcnRdTUyj3kXzXx2LPC9lmdR+OEwGq/HFwHjjLlPRoifuh8wYT23lApT3KBcw5Zzcb93ETakZ8hfLtJDyP5XCkNZjRuAnFWLWbbYXluTu0CBQAdTAshzNiYKcs9CDAQIDAQAB",
                    order: {
                        amount: 100,
                        currency: "EUR",
                        description: "Payment description",
                        tracking_id: "my_transaction_id"
                    },
                },
                closeWidget: function(status) {
                  // возможные значения status
                  // successful - операция успешна
                  // failed - операция не успешна
                  // pending - ожидаем результат/подтверждение операции
                  // redirected - пользователь отправлен на внешнюю платежную систему
                  // error - ошибка (в параметрах/сети и тд)
                  // null - виджет закрыли без запуска оплаты
                  console.debug('close widget callback')
                }
            };
    
            new BeGateway(params).createWidget();
        };
    </script>
    
  3. Вызовите функцию для запуска виджета.

    Пропишите вызов созданной выше функции на событие, например, на нажатие ссылки «Оплатить».

    <a onclick="payment()" href="#">Оплатить</a>
    

Параметры виджета

Параметр Тип Описание
checkout_url * обязательный
string Всегда https://checkout.ecomcharge.com
token * условно обязательный
string Токен платежа.

Обязателен, если не прислан параметр public_key. Виджет можно запустить с помощью токена платежа, который получили ранее в запросе на токен платежа. Тем самым пользователь не может внести изменения в параметрах платежа.
checkout object
transaction_type * обязательный
string Tип транзакции или запроса, который будет отправлен шлюзу.

Возможные значения - authorization, payment, tokenization и charge (для запроса на взимание платы).
attempts integer Количество попыток для оплаты. По умолчанию, 1.
dynamic_billing_descriptor string Динамический идентификатор платежа.
public_key * условно обязательный
string Публичный ключ магазина. Обязателен, если не прислан параметр token. При использовании такого способа запуска виджета обязательно проверяйте в автоматических уведомлениях данные оплаты и только потом меняйте статус оплаты на полученный.
test boolean Транзакция будет тестовой, если значение true. Иначе, false (по умолчанию).
iframe boolean При true открывать, по возможности, переходы на внешние сервисы внутри виджета. По умолчанию, false
order object
amount * обязательный
integer Сумма к оплате в минимальных денежных единицах. Например, $32.45 должна быть отправлена как 3245.
currency * обязательный
string Валюта транзакции в формате ISO-4217 alpha-3 code. Например, USD.
description * обязательный
string Описание платежа.
tracking_id string Идентификатор транзакции или заказа в вашей системе. Рекомендуется использовать уникальное значение для каждой транзакции.
expired_at string Дата и время, до которого должна быть сделана оплата. По умолчанию оплата должна быть сделана в течение 24 часов после открытия виджета. Формат: ISO 8601 вида YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например, 2019), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – временная зона (+hh:mm или –hh:mm).
additional_data object Секция, содержащая детальную информацию о платеже.
receipt_text array Текст, который будет добавлен в письмо клиенту и отображен на странице об успешной оплате. Должен быть представлен как массив строк, например ["Первая строка", "Вторая строка"].
contract array Массив, элементами которого могут быть параметры:

recurring - eComCharge вернет токен карты для осуществления последующих платежей без повторного ввода реквизитов карты. Пользователь, соглашаясь с условиями регулярного списания, единожды производит оплату, вводя реквизиты карты, включая проверочный код карты CVC/CVV и проходя авторизацию по протоколу 3-D ­Secure;

oneclick - eComCharge вернет токен карты для осуществления последующих платежей по схеме oneclick, когда на странице оплаты будут уже частично заполнены реквизиты карты, а пользователю для завершения оплаты достаточно ввести проверочный код карты CVC/CVV и пройти авторизацию по протоколу 3-D ­Secure;

credit - eComCharge вернет токен карты для осуществления операций выплаты средств;

card_on_file - eComCharge вернет токен карты, чтобы сохранить ее на профайле пользователя в вашем сервисе или приложении, и использовать этот токен для последующих операций по снятию денег с карты за оказанные услуги или проданные товары. Ознакомьтесть ниже с секцией card_on_file, чтобы узнать какие есть сценарии использования данного значения. Данное значение может быть отправлено, когда transaction_type=authorization;

save_card - возвращает информацию о том, что пользователь перевел тогл сохранения карты в активное состояние. Используется в качестве дополненния к параметрам recurring, oneclick, credit. Условия использования:
1. Параметр save_card_toggle.customer_contract имеет значение true;
2. Пользователь перевел тогл сохранения карты в активное состояние.
avs_cvc_verification object AVS/CVC проверка.
card_on_file object Данная секция устанавливает атрибуты операции, которые будут отправлены в дальнейшем в платёжную систему и атрибуты операции которые, если секция не передана, будут использованы по умолчанию для initiator и type.
initiator string merchant - (по умолчанию) операция инициирована вашей системой или приложением (например, оплата за поездку в такси);

customer - операция инициирована клиентом (например, клиент сам нажал кнопку оплатить сохраненной картой в вашем приложении).
type string Используется только если additional_data.card_on_file.initiator имеет значение merchant.

delayed_charge - (по умолчанию) отложенная оплата (например, за оказанную услугу);

increment - досписание суммы (например, при допродаже товара или замене на более дорогой товар);

resubmission - повторная попытка списать деньги из-за предыдущего отказа в операции (например, не было денег на карте);

reauthorization - обновление авторизации (например, нужно перезаблокировать деньги на карте в связи с истечением срока авторизации предыдущей операции);

no_show - клиент не пришел (например, не заехал в отель).
settings object
save_card_toggle object Секция для настройки тогла сохранения карты.
display boolean Если true, то тогл сохранения карты будет отображаться на виджете.

Данный параметр имеет более высокий приоритет, чем параметр Показывать опцию сохранения карты на платежной форме в настройках магазина в личном кабинете Мерчанта.

По умолчанию, true.
customer_contract boolean true - при активации тогла сохранения карты, пользователь тем самым дает Мерчанту свое юридическое согласие на хранение карточных данных и их использование в additional_data.contract
false - при активации тогла сохранения карты, пользователь тем самым дает юридическое согласие на то, что его карточные данные будут сохранены только для отображения на платежной форме виджета.

По умолчанию, false.
text string Параметр заменяет стандартное имя тогла Save card на любой текст Мерчанта.
hint string Текст описывающий, для чего нужна опция сохранения карты.
another_card_toggle object Секция для настройки тогла оплаты другой картой.
display boolean Если true, то тогл Оплатить другой картой будет отображаться на виджете.

Данный параметр имеет более высокий приоритет, чем параметр Показывать опцию оплаты другой картой на платежной форме в настройках магазина в личном кабинете Мерчанта.

По умолчанию true.
return_url string URL, на который будет перенаправлен клиент после завершения оплаты. Если не задан, то только вызывается функция closeWidget. Если задан, то success_url и decline_url игнорируются.
success_url string URL, на который будет перенаправлен клиент при успешной транзакции.
decline_url string URL, на который будет перенаправлен клиент при отклоненной банком транзакции.
fail_url string URL, на который будет перенаправлен клиент при неудавшейся транзакции (из-за ошибки, исключительной ситуации и т.д.). Вы можете запросить статус транзакции, используя токен оплаты, изучить status ответа или параметр message, чтобы оценить, почему транзакция не прошла.
cancel_url string URL, на который будет перенаправлен клиент в случае отмены операции.
verification_url string URL, на который будут приходить запрос на подтверждение транзакции. Формат запроса на подтверждение аналогичен формату ответа транзакции.
notification_url string URL, на который будут приходить уведомления.
auto_return string После завершения операции eComCharge показывает страницу результа операции на заданное количество секунд и затем автоматически перенаправит клиента обратно на сайт торговца. Если параметр равен 0, то по окончанию оплаты клиент будет сразу перенаправлен на сайт торговца и результирующая страница оплаты показана не будет.
button_text string Пользовательский текст кнопки начала оплаты. Замечание: {amount} может быть использован как шаблон для отображения суммы транзакции внутри текста.
button_next_text string Пользовательский текст кнопки возврата со страницы результа операции на сайт торговца.
language string Язык страницы оплаты. По умолчанию - en. Доступные значения параметра language.
customer_fields object Управляет полями ввода на странице оплаты
read_only array Массив, который может содержать значения email, first_name, last_name, address, city, state, zip, phone, country, birth_date и taxpayer_id.
Поля, указанные в массиве, будут заблокированы (disabled).
Если массив содержит поле email, то оно должно быть в секция customer ниже и не должно быть пустым.
visible array Массив, который может содержать значения first_name, last_name, address, city, state, zip, phone, country, birth_date и taxpayer_id. Поля, указанные в массиве, отобразятся на странице платежа и будут обязательны для заполнения.
credit_card_fields object Управляет автоматическим заполнением на странице оплаты поля с именем владельца карты.
holder string Имя держателя карты для автоматического заполнения на странице оплаты.
read_only array Массив, который может принимать только значение holder. Блокирует редактирование выбранного поля.
customer * условно обязательный
object Секция информации о покупателе.
Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции.
email string Адрес электронной почты клиента.
first_name string Имя клиента.
last_name string Фамилия клиента.
address string Адрес для выставления счёта.
city string Город клиента.
state string Штат / область / регион клиента (состоит из двух букв), только если страна адреса для выставления счёта US или CA
zip string Почтовый индекс клиента.
country string Страна клиента в формате ISO 3166-1 alpha-2.
phone string Номер телефона.
birth_date string Дата рождения клиента в формате ISO 8601 YYYY-MM-DD.
taxpayer_id string Идентификационный номер налогоплательщика (ИНН), присвоенный клиенту.
payment_method object Секция содержит информацию о том, какие способы оплаты доступны клиенту, чтобы осуществить платёж, а также параметры, необходимые для инициализации каждого способа оплаты. Если не передана, то по умолчанию доступны все активные способы оплаты.
types array Массив способов оплаты для отображения на странице оплаты.

Возможные значения: credit_card - оплата банковской картой


Отображение Apple Pay, Google Pay, Samsung Pay и Yandex Pay на виджете зависит от типа устройства и браузера клиента. Подробнее описано здесь.
excluded_types array Массив способов оплаты, которые будут исключены из доступных методов, отображаемых на платежной странице. При отправке в запросе обоих параметров payment_method.types и payment_method.excluded_types приоритетной считается информация в payment_method.types. Данные из payment_method.excluded_types игнорируются.
credit_card object
token string Токен карты. На платежной странице будут отображаться данные токенизированной карты.
travel object Секция, предоставляющая расширенную информацию о продаже авиабилетов, туристических путевок и т.д.
airline object Необязательная секция, содержащая расширенную информацию о проданном авиабилете.
agency_code string IATA код агентства, например 03.
agency_name string Название агенства, продавшего билет, например Corel travel.
ticket_number string 14-значный номер билета. Должен содержать 3-значный код билета, 4-значный номер формы, 6-значный серийный номер и контрольное число, например 390 5241 025377 1.
booking_number string Код брони, например DKZVUA.
restricted_ticked_indicator string Если билет можно вернуть, 0. Если вернуть нельзя, 1.
legs array Список перелетов, каждый элемент которого состоит из:
airline_code string 2-символьный IATA код авиакомпании, например B2.
stop_over_code string IATA код длительности пересадки. Если пересадка больше 24 часов, то значение параметра O или пусто. Если аэропорт является транзитным, то значение параметра X.
flight_number string Номер рейса, например A3 971.
departure_date_time string Время и дата вылета, например 2014-05-26T05:15:00.
arrival_date_time string Время и дата прибытия, например 2014-05-26T07:30:00.
originating_country string Страна вылета, например RU.
originating_city string Город вылета, например Moscow.
originating_airport_code string 3-значный код аэропорта вылета, например DME.
destination_country string Страна прилета, например Greece.
destination_city string Город прилета, например Athens.
destination_airport_code string 3-значный код аэропорта прилета, например ATH.
coupon string Номер скидочного купона, если был применен.
class string Класс полета, 1-значный IATA код, например C.
passengers array Список пассажиров, каждый элемент которого состоит из:
first_name string Имя пассажира, например KONSTANTIN.
last_name string Фамилия пассажира, например IVANOV.