Установка платежного виджета
Для приема платежей от клиентов с помощью платежного виджета eComCharge выполните следующие действия:
-
Установите скрипт виджета.
Для проведения платежей пропишите на вашем сайте скрипт:
<script type="text/javascript" src="https://js.ecomcharge.com/widget/be_gateway.js"></script>
-
Создайте платежный виджет.
Зарегистрируйте функцию, которая сформирует необходимые параметры для конструктора объекта
BeGateway
и вызовет у него методcreateWidget
. Оплата считается успешно завершенной только после получения автоматического уведомления о платеже.<script type="text/javascript"> this.payment = function() { var params ={ checkout_url: "https://checkout.ecomcharge.com", fromWebview: true, 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>
-
Вызовите функцию для запуска виджета.
Пропишите вызов созданной выше функции на событие, например, на нажатие ссылки «Оплатить».
<a onclick="payment()" href="#">Оплатить</a>
Параметры виджета
Параметр | Тип | Описание |
---|---|---|
checkout_url * обязательный |
string | Всегда https://checkout.ecomcharge.com |
token * условно обязательный |
string | Токен платежа. Обязателен, если не прислан параметр public_key . Виджет можно запустить с помощью токена платежа, который получили ранее в запросе на токен платежа. Тем самым пользователь не может внести изменения в параметрах платежа. |
fromWebview | boolean | Если true , при инициализации платежа в WebView (например, внутри веб-приложения) будет открываться платежный виджет. Если false или параметр не отправлен, при инициализации платежа будет открываться платёжная страница. |
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 | Секция информации о покупателе. Уточните у Службы технической поддержки, необходимо ли передавать параметры данной секции. |
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 на виджете зависит от типа устройства и браузера клиента. Подробнее описано здесь. |
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 . |