Оплаты по платёжным ссылкам
В этом разделе представлена информация о проведении оплат по платёжным ссылкам, дополняющая сведения из раздела о модели проведения таких оплат (Оплата по платёжной ссылке).
Общая информация
Оплата по платёжной ссылке — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется создание и отправка платёжной ссылки, а затем один (разовый) перевод денежных средств от пользователя к мерчанту. Платёжная платформа ecommpay поддерживает следующие варианты таких оплат:
- оплата по платёжной ссылке в одну стадию,
- оплата по платёжной ссылке в две стадии.
Оба варианта поддерживают возможность зарегистрировать дальнейшие списания в рамках повторяемой оплаты любого вида и проводятся с использованием платёжной формы Payment Page, ссылка для открытия которой отправляется на электронную почту пользователя через платформу ecommpay или любым другим способом со стороны мерчанта. Срок действия такой ссылки и вариант проведения платежа определяются на стороне мерчанта и указываются в параметрах запроса на его инициирование. Также в параметрах такого запроса можно указать платёжный метод, с использованием которого необходимо провести платёж, или предоставить пользователю возможность выбора из всех методов, подключенных для проекта мерчанта.
Так как оплаты по платёжной ссылке проводятся с использованием платёжной формы Payment Page, в параметрах запросов на инициирование таких оплат реквизиты платёжного инструмента либо не указываются, либо указываются в форме токена карты. В последнем случае пользователю понадобится только подтвердить подлинность платёжного инструмента, без указания его реквизитов в платёжной форме.
Как и при проведении других типов платежей, в процессе проведения оплаты по платёжной ссылке может потребоваться выполнить вспомогательные процедуры, такие как аутентификация с использованием технологии 3‑D Secure, дополнение информации о платеже и конвертация валют. Эти процедуры полностью выполняются на стороне Payment Page, дополнительных действий со стороны веб-сервиса мерчанта при этом не требуется.
Сценарии использования
Допустим, пользователь веб-сервиса оформил заказ на сумму 12.99 GBP
и выбрал возможность оплаты по платёжной ссылке, указав для получения ссылки свой адрес электронной почты — baskerville@mail.uk
.
Успешная оплата
- Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос с параметрами, необходимыми для отправки платёжной ссылки пользователю средствами ecommpay.
- Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на указанный в запросе адрес электронной почты письмо, стандартные вид и содержание которого представлены в примере далее. Стандартный язык письма — английский.
Рис.: Пример письма с платёжной ссылкой
- Пользователь переходит по ссылке, после чего ему отображается Payment Page. Если в запросе на инициирование платежа не указан платёжный метод, то пользователю отображается страница выбора платёжного метода, а если платёжный метод указан — страница указанного платёжного метода.
Рис.: Пример страницы оплаты с использованием карты
- Пользователь указывает платёжные данные и подтверждает оплату, а также, при необходимости, осуществляет дополнительные действия, требуемые для выполнения одной или нескольких вспомогательных процедур.
- По результатам проведения платежа к веб-сервису направляется оповещение о результате, а пользователю отображается страница результата оплаты.
Рис.: Пример страницы результата оплаты
Отмена платежа
- Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос на отмену платежа.
- Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на ранее указанный адрес электронной почты письмо, стандартные вид и содержание которого представлены в примере далее. Стандартный язык письма — английский.
Рис.: Пример письма об отмене платежа
- Если пользователь переходит по платёжной ссылке, ему отображается страница с уведомлением об отмене платежа.
Рис.: Пример страницы с уведомлением об отмене платежа
Истечение срока действия платёжной ссылки
- К веб-сервису мерчанта направляется оповещение об истечении срока действия платёжной ссылки.
- Если пользователь переходит по платёжной ссылке, ему отображается страница с уведомлением об истечении срока действия платёжной ссылки.
Рис.: Пример страницы с уведомлением об истечении срока действия платёжной ссылки
Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежа, представлены далее.
Настройка
Содержание и оформление писем
По умолчанию для составления писем, отправляемых на электронную почту пользователя, используются следующие данные из запроса на создание платёжной ссылки:
- идентификатор платежа (
payment_id
); - сумма (
amount
) и валюта (currency
) платежа; - срок действия платёжной ссылки (
best_before
); - описание платежа (
description
).
Рис.: Шаблон письма по умолчанию

По желанию мерчанта можно изменить состав данных, которые необходимо передавать в составе письма, или предоставить собственную вёрстку письма.
По всем вопросам, связанным с изменением содержания и оформления писем, следует обращаться к специалистам технической поддержки — support@ecommpay.com.
Оформление платёжной формы
По умолчанию пользователю отображается платёжная форма с типовым вариантом оформления от ecommpay. По желанию мерчант может настроить собственный вариант оформления, применив различные изменения к отдельным элементам платёжной формы с помощью соответствующего конструктора. С вопросами, выходящими за рамки возможностей конструктора, можно обращаться к курирующему менеджеру.
Схема проведения
Для проведения оплаты по платёжной ссылке через Gate необходимо:
- Отправить запрос на оплату по платёжной ссылке к конечной точке
/v2/payment/invoice[/card/token]/create
. - Принять оповещение о создании платёжной ссылки.
- Принять оповещение о результате оплаты или оповещение об истечении срока действия ссылки.
Для проведения оплаты по платёжной ссылке в две стадии дополнительно требуется выполнить вторую стадию такой оплаты: подтверждение списания заблокированных средств или отмену блокировки. Подробная информация о выполнении второй стадии оплаты в две стадии представлена в разделе Оплата в две стадии.
Схема проведения оплаты по платёжной ссылке представлена далее.
Рис.: Проведение оплаты по платёжной ссылке
- От веб-сервиса на заданный URL ecommpay передаётся запрос на оплату по платёжной ссылке.
- Запрос поступает в платёжную платформу.
- В платёжной платформе выполняется приём запроса с проверкой его корректности.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
- В платёжной платформе осуществляется обработка запроса.
- От платёжной платформы к веб-сервису мерчанта направляется оповещение о создании платёжной ссылки.
- От платёжной платформы на электронную почту пользователя (или от веб-сервиса мерчанта на электронную почту либо другим способом) отправляется платёжная ссылка.
- Пользователь переходит по этой платёжной ссылке.
- Запрос на открытие платёжной формы поступает в платёжную платформу.
- В платёжной платформе осуществляется обработка запроса.
- Осуществляется генерация Payment Page согласно настройкам проекта.
- Пользователю отображается ранее сгенерированная платёжная форма.
- Пользователь указывает платёжные данные и подтверждает оплату.
- Запрос на проведение оплаты поступает в платёжную платформу.
- Выполняются обработка запроса и его отправка в платёжную систему (или в сервис провайдера).
- В платёжной системе (или в сервисе провайдера) выполняется обработка платежа.
- От платёжной системы (или сервиса провайдера) к платёжной платформе направляется уведомления о результате платежа.
- От платёжной платформы к веб-сервису направляется оповещение о результате платежа.
- От платёжной платформы к Payment Page направляется результат платежа.
- Результат платежа отображается пользователю на Payment Page.
Для отмены такой оплаты до её подтверждения пользователем необходимо:
- Отправить запрос на отмену платежа к конечной точке
/v2/payment/invoice/cancel
. - Принять оповещение об отмене платежа.
Далее приведена информация о форматах запросов и параметрах инициирования оплаты по платёжной ссылке и её отмены, а также о форматах оповещений, используемых при проведении платежа.
Форматы запросов
Формат запроса на проведение платежа
При формировании запросов необходимо учитывать следующее:
- Должен использоваться POST-запрос к одной из следующих конечных точек: /v2/payment/invoice/create или /v2/payment/invoice/card/token/create.
- В запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта;signature
— подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
customer
— объект, содержащий сведения о пользователе:id
— идентификатор пользователя в веб-сервисе мерчанта;
payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;currency
— валюта платежа в формате ISO-4217 alpha-3;best_before
— срок действия платёжной ссылки в форматеYYYY-MM-DDThh:mm:ss±hh:mm
.
- При передаче токена — токен карты в параметре
token
. - Для отправки платёжной ссылки средствами ecommpay:
email
— адрес электронной почты пользователя, содержится в объектеcustomer
;send_email
— индикатор автоматической отправки платёжной ссылки, для отправки необходимо передать значениеtrue
;language
— код языка, содержится в объектеcustomer
; необходимо передавать в случае, если язык пользователя отличается от английского и для этого языка настроена вёрстка письма.
- Для предварительного выбора платёжного метода — код этого метода в параметре
force_method
(список таких кодов — в разделе Коды платёжных методов). - Для регистрации дальнейших списаний в рамках повторяемой оплаты — объект
recurring
, содержащий обязательные параметры с информацией о регистрируемой оплате:register
— признак регистрации повторяемой оплаты, необходимо использовать значениеtrue
;type
— категория регистрируемой повторяемой оплаты, необходимо использовать одно из следующих значений:C
— для экспресс-оплаты,U
— для автооплаты,R
— для регулярной оплаты;
time
— время последующих списаний (для регулярной оплаты) в форматеhh:mm:ss
;period
— периодичность списаний (для регулярной оплаты):D
— ежедневно,W
— еженедельно,M
— ежемесячно,Q
— ежеквартально,Y
— ежегодно.
Также могут использоваться и любые другие параметры в объекте
recurring
, указанные в спецификации. - Дополнительно могут использоваться любые другие параметры, указанные в спецификации, например параметры объекта
cash_voucher_data
с данными для формирования фискального чека (подробнее).
Таким образом, корректный запрос на оплату по платёжной ссылке должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, валюту и сумму платежа, срок действия платёжной ссылки и, при необходимости, токен платёжной карты. Дополнительно, если платёжную ссылку необходимо отправить средствами ecommpay, запрос должен содержать адрес электронной почты пользователя и индикатор автоматической отправки платёжной ссылки.
{ "general": { "project_id": 1901, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm==" }, "customer": { "id": "stapleton", "email": "baskerville@mail.uk" }, "payment": { "amount": 1500, "currency": "GBP", "best_before": "2023-03-08T09:00:00+03:00" }, "send_email": true, // при передаче ранее созданного токена платёжной карты: "token": "f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654" }
Формат запроса на отмену платежа
При формировании запросов необходимо учитывать следующее:
- Должен использоваться POST-запрос к конечной точке /v2/payment/invoice/cancel.
- В запросе должен использоваться объект
general
, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор того платежа, который необходимо отменить;signature
— подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
- Дополнительно могут использоваться любые другие параметры, указанные в спецификации.
Таким образом, корректный запрос на отмену платежа должен содержать идентификаторы проекта и платежа, а также подпись.
{ "general": { "project_id": 1901, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm==" } }
Форматы оповещений
Формат оповещения о создании платёжной ссылки
Для оповещения об отправке платёжной ссылки пользователю используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что пользователю stapleton
на адрес электронной почты baskerville@mail.uk
отправлена платёжная ссылка для оплаты заказа в размере 12,99 GBP
. Срок действия ссылки истекает 11 октября 2020 года, в 11:50.
Рис.: Пример тела оповещения об отправке платёжной ссылки пользователю
{ "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"invoice sent", "date":"2020-01-11T11:50:24+0000", "best_before":"2020-10-11T11:50:00+0000", "force_payment_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":{ "number":"424220******4800", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"STAPLETON JACK", "id":1353, "expiry_month":"11", "expiry_year":"2022" }, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"invoice sent", "date":"2020-01-11T11:57:34+0000", "created_date":"2020-01-11T11:56:32+0000", "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3701", "message":"Merchant sent invoice", "eci":"02" }, "signature":"hghwGGyapGUQnI+Qg==" }
Формат оповещения об отмене платежа
Для оповещения об отмене платежа по инициативе мерчанта используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что платёж 456789
отменён, статус платежа — invoice canceled
.
Рис.: Пример тела оповещения об отмене платежа
{ "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"invoice canceled", "date":"2020-01-11T11:57:36+0000", "best_before":"2020-10-11T11:50:00+0000", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":{ "number":"424220******4800", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"STAPLETON JACK", "id":1353091, "expiry_month":"11", "expiry_year":"2022" }, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"invoice canceled", "date":"2020-01-11T11:57:34+0000", "created_date":"2020-01-11T11:56:32+0000", "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3702", "message":"Merchant canceled invoice", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" }
Формат оповещения об истечении срока действия платёжной ссылки
Для оповещения об истечении срока действия платёжной ссылки используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что срок действия платёжной ссылки, отправленной пользователю stapleton
на адрес электронной почты baskerville@mail.uk
, истёк 11 февраля 2020 года, в 11:50.
Рис.: Пример тела оповещения об отказе в связи с истечением срока действия платёжной ссылки
{ "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"expired", "date":"2020-01-11T11:57:36+0000", "best_before":"2020-02-11T11:50:00+0000", "force_payment_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":{ "number":"424220******4800", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"STAPLETON JACK", "id":1353091, "expiry_month":"11", "expiry_year":"2022" }, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"expired", "date":"2020-01-11T11:57:34+0000", "created_date":"2020-01-11T11:56:32+0000", "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3700", "message":"Best_before has expired", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" }
Формат оповещения о результате платежа
Для оповещения о результате оплаты по платёжной ссылке используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что для пользователя stapleton
проведена оплата в размере 12,99 GBP
.
Рис.: Пример тела оповещения об успешной оплате по платёжной ссылке
{ "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"success", "date":"2020-01-11T11:57:36+0000", "best_before":"2020-10-11T11:50:00+0000", "force_payment_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2020-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&card_operation_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":{ "number":"424220******4800", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"STAPLETON JACK", "id":1353091, "expiry_month":"11", "expiry_year":"2022" }, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"success", "date":"2020-01-11T11:57:34+0000", "created_date":"2020-01-11T11:56:32+0000", "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"0", "message":"Success", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" }