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

Проведение платежа

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

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

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

   
   
   

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

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

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

   

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

Оформление писем

По умолчанию в письмах, отправляемых пользователям, содержатся адрес отправителя, noreply@ecommpay.com, тема письма с указанием названия мерчанта или используемого проекта (в соответствии с указанными в платформе), например Payment Link from Cosmoshop, а также сведения из запроса на создание платёжной ссылки:

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

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

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

Оформление платёжной формы

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

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

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

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:mm; необходимо указывать таким образом, чтобы срок действия ссылки не превышал 30 суток.
3. При передаче токена — токен карты в параметре token.
4. Для отправки платёжной ссылки средствами ecommpay:
   • email — адрес электронной почты пользователя, содержится в объекте customer;
   • send_email — индикатор автоматической отправки платёжной ссылки, для отправки необходимо передать значение true;
   • language — код языка, содержится в объекте customer; необходимо передавать в случае, если язык пользователя отличается от английского и для этого языка настроена вёрстка письма.
5. Для предварительного выбора платёжного метода — код этого метода в параметре force_method (список таких кодов — в разделе Коды платёжных методов).
6. Для регистрации дальнейших списаний в рамках повторяемой оплаты — объект recurring, содержащий обязательные параметры с информацией о регистрируемой оплате:
   • register — признак регистрации повторяемой оплаты, необходимо использовать значение true;
   • type — категория регистрируемой повторяемой оплаты, необходимо использовать одно из следующих значений:
     • C — для экспресс-оплаты,
     • U — для автооплаты,
     • R — для регулярной оплаты;
   • time — время последующих списаний (для регулярной оплаты) в формате hh:mm:ss;
   • period — периодичность списаний (для регулярной оплаты):
     • D — ежедневно,
     • W — еженедельно,
     • M — ежемесячно,
     • Q — ежеквартально,
     • Y — ежегодно.

   Также могут использоваться и любые другие параметры в объекте recurring, указанные в спецификации.

7. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату по платёжной ссылке должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, валюту и сумму платежа, дату и время окончания срока действия платёжной ссылки и, при необходимости, токен платёжной карты. Дополнительно, если платёжную ссылку необходимо отправить средствами 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"  
}

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

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

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":"431422******0056",
    "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":"431422******0056",
    "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":"431422******0056",
    "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":"431422******0056",
    "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=="
}