Оплаты по платёжным ссылкам

В этом разделе представлена информация о проведении оплат по платёжным ссылкам, дополняющая сведения из раздела о модели проведения таких оплат (Оплата по платёжной ссылке).

Общая информация

Оплата по платёжной ссылке — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется создание и отправка платёжной ссылки, а затем один (разовый) перевод денежных средств от пользователя к мерчанту. Платёжная платформа ECommPay поддерживает следующие варианты таких оплат:

  • оплата по платёжной ссылке в одну стадию,
  • оплата по платёжной ссылке в две стадии.

Оба варианта проводятся с использованием платёжной формы Payment Page, ссылка на которую отправляется на электронную почту пользователя средствами ECommPay или любым другим способом средствами мерчанта. Срок действия такой ссылки и вариант проведения платежа определяются на стороне мерчанта и указываются в параметрах запроса на его инициирование. Также в параметрах такого запроса можно указать платёжный метод, с использованием которого необходимо провести платёж, или предоставить пользователю возможность выбора из всех методов, подключенных для проекта мерчанта.

Так как оплаты по платёжной ссылке проводятся с использованием платёжной формы Payment Page, в параметрах запросов на инициирование таких оплат реквизиты платёжного инструмента либо не указываются, либо указываются в форме токена карты. В последнем случае пользователю понадобится только подтвердить подлинность платёжного инструмента, без указания его реквизитов в платёжной форме.

Как и при проведении других типов платежей, в процессе проведения оплаты по платёжной ссылке может потребоваться выполнить вспомогательные процедуры, такие как аутентификация с использованием технологии 3‑D Secure, дополнение информации о платеже и конвертация валют. Эти процедуры полностью выполняются на стороне Payment Page, дополнительных действий со стороны веб-сервиса мерчанта при этом не требуется.

Сценарии использования

Допустим, пользователь веб-сервиса оформил заказ на сумму 12.99 GBP и выбрал возможность оплаты по платёжной ссылке, указав для получения ссылки свой адрес электронной почты — baskerville@mail.uk.

Успешная оплата

  1. Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос с параметрами, необходимыми для отправки платёжной ссылки пользователю средствами ECommPay.
  2. Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на указанный в запросе адрес электронной почты письмо, стандартные вид и содержание которого представлены в примере далее. Стандартный язык письма — английский.

    Рис.: Пример письма с платёжной ссылкой



  3. Пользователь переходит по ссылке, после чего ему отображается Payment Page. Если в запросе на инициирование платежа не указан платёжный метод, то пользователю отображается страница выбора платёжного метода, а если платёжный метод указан — страница указанного платёжного метода.

    Рис.: Пример страницы оплаты с использованием карты



  4. Пользователь указывает платёжные данные и подтверждает оплату, а также, при необходимости, осуществляет дополнительные действия, требуемые для выполнения одной или нескольких вспомогательных процедур.
  5. По результатам проведения платежа к веб-сервису направляется оповещение о результате, а пользователю отображается страница результата оплаты.

    Рис.: Пример страницы результата оплаты



Отмена платежа

  1. Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос на отмену платежа.
  2. Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на ранее указанный адрес электронной почты письмо, стандартные вид и содержание которого представлены в примере далее. Стандартный язык письма — английский.

    Рис.: Пример письма об отмене платежа



  3. Если пользователь переходит по платёжной ссылке, ему отображается страница с уведомлением об отмене платежа.

    Рис.: Пример страницы с уведомлением об отмене платежа



Истечение срока действия платёжной ссылки

  1. К веб-сервису мерчанта направляется оповещение об истечении срока действия платёжной ссылки.
  2. Если пользователь переходит по платёжной ссылке, ему отображается страница с уведомлением об истечении срока действия платёжной ссылки.

    Рис.: Пример страницы с уведомлением об истечении срока действия платёжной ссылки



Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежа, представлены далее.

Настройка

Содержание и оформление писем

По умолчанию для составления писем, отправляемых на электронную почту пользователя, используются следующие данные из запроса на создание платёжной ссылки:

  • идентификатор платежа (payment_id);
  • сумма (amount) и валюта (currency) платежа;
  • срок действия платёжной ссылки (best_before);
  • описание платежа (description).

Рис.: Шаблон письма по умолчанию



По желанию мерчанта можно изменить состав данных, которые необходимо передавать в составе письма, или предоставить собственную вёрстку письма.

По всем вопросам, связанным с изменением содержания и оформления писем, следует обращаться к специалистам технической поддержки — support@ecommpay.com.

Дизайн платёжной формы

По умолчанию пользователю отображается платёжная форма с базовый вариантом вёрстки от ECommPay. По желанию мерчанта можно внести изменения в этот вариант вёрстки (изменить используемые цвета, добавить логотипы или, например, скорректировать используемые тексты) или разработать собственную с учётом требований, перечисленных в разделе Индивидуальный дизайн.

По всем вопросам, связанным с дизайном платёжной формы, следует обращаться к специалистам технической поддержки — support@ecommpay.com.

Схема проведения

Для проведения оплаты по платёжной ссылке через Gate необходимо:

  1. Отправить запрос на оплату по платёжной ссылке к конечной точке /v2/payment/invoice[/card/token]/create.
  2. Принять оповещение о создании платёжной ссылки.
  3. Принять оповещение о результате оплаты или оповещение об истечении срока действия ссылки.

Для проведения оплаты по платёжной ссылке в две стадии дополнительно требуется выполнить вторую стадию такой оплаты: подтверждение списания заблокированных средств или отмену блокировки. Подробная информация о выполнении второй стадии оплаты в две стадии представлена в разделе Оплата в две стадии.

Схема проведения оплаты по платёжной ссылке представлена далее.



Рис.: Проведение оплаты по платёжной ссылке

  1. От веб-сервиса на заданный URL ECommPay передаётся запрос на оплату по платёжной ссылке.
  2. Запрос поступает в платёжную платформу.
  3. В платёжной платформе выполняется приём запроса с проверкой его корректности.
  4. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
  5. В платёжной платформе осуществляется обработка запроса.
  6. От платёжной платформы к веб-сервису мерчанта направляется оповещение о создании платёжной ссылки.
  7. От платёжной платформы на электронную почту пользователя (или от веб-сервиса мерчанта на электронную почту либо другим способом) отправляется платёжная ссылка.
  8. Пользователь переходит по этой платёжной ссылке.
  9. Запрос на открытие платёжной формы поступает в платёжную платформу.
  10. В платёжной платформе осуществляется обработка запроса.
  11. Осуществляется генерация Payment Page согласно настройкам проекта.
  12. Пользователю отображается ранее сгенерированная платёжная форма.
  13. Пользователь указывает платёжные данные и подтверждает оплату.
  14. Запрос на проведение оплаты поступает в платёжную платформу.
  15. Выполняются обработка запроса и его отправка в платёжную систему (или в сервис провайдера).
  16. В платёжной системе (или в сервисе провайдера) выполняется обработка платежа.
  17. От платёжной системы (или сервиса провайдера) к платёжной платформе направляется уведомления о результате платежа.
  18. От платёжной платформы к веб-сервису направляется оповещение о результате платежа.
  19. От платёжной платформы к Payment Page направляется результат платежа.
  20. Результат платежа отображается пользователю на Payment Page.

Для отмены такой оплаты до её подтверждения пользователем необходимо:

  1. Отправить запрос на отмену платежа к конечной точке /v2/payment/invoice/cancel.
  2. Принять оповещение об отмене платежа.

Далее приведена информация о форматах запросов и параметрах инициирования оплаты по платёжной ссылке и её отмены, а также о форматах оповещений, используемых при проведении платежа.

Форматы запросов

Формат запроса на проведение платежа

При формировании запросов необходимо учитывать следующее:

  1. Должен использоваться POST-запрос к одной из следующих конечных точек: /v2/payment/invoice/create или /v2/payment/invoice/card/token/create.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
    • customer — объект, содержащий сведения о пользователе:
      • id — идентификатор пользователя в веб-сервисе мерчанта;
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты;
      • currency — валюта платежа в формате ISO-4217 alpha-3;
      • best_before — срок действия платёжной ссылки в формате YYYY-MM-DDThh:mm:ss±hh.
  3. При передаче токена — токен карты в параметре token.
  4. Для отправки платёжной ссылки средствами ECommPay:
    • email — адрес электронной почты пользователя, содержится в объекте customer;
    • send_email — индикатор автоматической отправки платёжной ссылки, для отправки необходимо передать значение true;
    • language — код языка, содержится в объекте customer; необходимо передавать в случае, если язык пользователя отличается от английского и для этого языка настроена вёрстка письма.
  5. Для предварительного выбора платёжного метода — код этого метода в параметре force_method (список таких кодов — в разделе Коды поддерживаемых платежных методов на Payment Page).
  6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату по платёжной ссылке должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, валюту и сумму платежа, срок действия платёжной ссылки и, при необходимости, токен платёжной карты. Дополнительно, если платёжную ссылку необходимо отправить средствами 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": "2020-10-11T11:50:00+00"
  },
    "send_email": true,
// при передаче ранее созданного токена платёжной карты:
    "token": "f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654"  
}

Формат запроса на отмену платежа

При формировании запросов необходимо учитывать следующее:

  1. Должен использоваться POST-запрос к конечной точке /v2/payment/invoice/cancel.
  2. В запросе должен использоваться объект general, содержащий основные идентификационные сведения запроса:
    • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
    • payment_id — идентификатор того платежа, который необходимо отменить;
    • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
  3. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на отмену платежа должен содержать идентификаторы проекта и платежа, а также подпись.

{
  "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=="
}