[POST] Отправка webhook-оповещения
Описание запроса
Оповещение отправляется по факту наступления события для продукта заказа.
Обратите внимание. Если в заказе несколько продуктов, то вы получите отдельные оповещения по каждому из них.
В запросе передаются:
- Подпись сообщения
- Данные заказа
- Данные покупателя
- Данные продукта
- Данные об оплате
- (Опционально) Данные о рассрочке
- (Опционально) Данные о подписке
- (Опционально) Дополнительные параметры заказа
- (Опционально) Данные по возврату
Характеристики запроса:
- Метод: POST
- Формат: JSON
- Кодировка: UTF-8
Подпись webhook-оповещения
Проверка подписи позволит подтвердить, что оповещение отправлено Softline.
Формат подписи: hash, сгенерированный по алгоритму SHA-512, от строки:
Проверка подписи позволит подтвердить, что оповещение отправлено Softline.
Формат подписи: hash, сгенерированный по алгоритму SHA-512, от строки:
[secret key];[event];[order_id];[create_date];[payment_method];[currency];[customer.email]где:
- secret key - создается при подключении webhook-оповещений для события
- event; order_id; create_date; payment_method; currency; customer.email - значения соответствуют значениям аналогичных полей в уведомлении
Дата и время события, по которому отправлено webhook-оповещение
Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
Дополненный идентификатор
Формат идентификатора, в котором к нему может быть добавлен префикс. Это тот вид, в котором покупатель видит номер заказа.
Для платежа Softline Payments: Дополненный идентификатор платежа
Формат идентификатора, в котором к нему может быть добавлен префикс. Это тот вид, в котором покупатель видит номер заказа.
Для платежа Softline Payments: Дополненный идентификатор платежа
Статус заказа
Узнайте подробнее о статусах заказа.
Варианты значений:
Узнайте подробнее о статусах заказа.
Варианты значений:
- not paid - не оплачен
- paid - оплачен
- deleted - удален
Идентификатор корзины
Используется, если оформлен заказ на продукт с динамическими характеристиками. Этот идентификатор вы получаете в ответ на запрос генерации ссылки на покупку продукта с динамическими характеристиками (buy_link). В ином случае параметр будет передан с пустым значением ("").
Для платежа Softline Payments: идентификатор платежа на вашей стороне
Используется, если оформлен заказ на продукт с динамическими характеристиками. Этот идентификатор вы получаете в ответ на запрос генерации ссылки на покупку продукта с динамическими характеристиками (buy_link). В ином случае параметр будет передан с пустым значением ("").
Для платежа Softline Payments: идентификатор платежа на вашей стороне
Дата и время создания заказа
Если webhook-оповещение отправляется по событию order.created, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
Для платежа Softline Payments: Дата и время создания платежа
Если webhook-оповещение отправляется по событию order.created, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
Для платежа Softline Payments: Дата и время создания платежа
Дата и время успешной оплаты заказа
Если webhook-оповещение отправляется по событию order.payment.succeeded, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
Если webhook-оповещение отправляется по событию order.payment.succeeded, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
- Формат: YYYY-MM-DDThh:mm:ss±hh:mm
- Если оплата не была произведена, то параметр будет передан с пустым значением ("")
Код валюты заказа
- Формат: ISO 4217 alpha-3, 3 символа
- Варианты значений см. в справочнике
Код языка интерфейса корзины
Варианты значений см. в справочнике
Варианты значений см. в справочнике
Cсылка на страницу заказа
При получении webhook-оповещения по заказу/платежу в тестовой среде - ссылка будет предназначена для тестовой среды (ссылка будет иметь суффикс .demoslweb.com).
Для платежа Softline Payments: cсылка на страницу платежной формы
При получении webhook-оповещения по заказу/платежу в тестовой среде - ссылка будет предназначена для тестовой среды (ссылка будет иметь суффикс .demoslweb.com).
Для платежа Softline Payments: cсылка на страницу платежной формы
Код страны покупателя
- Формат: ISO 3166-1 alpha-2
- Варианты значений см. в справочнике
Тип покупателя
Варианты значения:
Варианты значения:
- physical - физическое лицо
- juridical - юридическое лицо
Телефон покупателя
Если не заполнен, то параметр будет передан с пустым значением ("").
Если не заполнен, то параметр будет передан с пустым значением ("").
Номер налогоплательщика
Также, используется для передачи:
Также, используется для передачи:
- ИНН компании при оплате в рублях
- DNI/CUIL или CUIT при оплате в аргентинских песо
Наименование компании
Если не заполнено, то параметр будет передан с пустым значением ("").
Если не заполнено, то параметр будет передан с пустым значением ("").
Юридический адрес компании
Если не заполнен, то параметр будет передан с пустым значением ("").
Если не заполнен, то параметр будет передан с пустым значением ("").
Фактический адрес компании
Если не заполнен, то параметр будет передан с пустым значением ("").
Если не заполнен, то параметр будет передан с пустым значением ("").
Данные продукта в заказе
Для платежа Softline Payments: дополнительные данные о платеже
Для платежа Softline Payments: дополнительные данные о платеже
Ваш идентификатор продукта
Если не заполнен, то параметр будет передан с пустым значением ("").
Для платежа Softline Payments: техническое значение
Если не заполнен, то параметр будет передан с пустым значением ("").
Для платежа Softline Payments: техническое значение
Ваш SKU (артикул) продукта
Если не заполнен, то параметр будет передан с пустым значением ("").
Для платежа Softline Payments: техническое значение
Если не заполнен, то параметр будет передан с пустым значением ("").
Для платежа Softline Payments: техническое значение
Бизнес сегмент продажи
Варианты значения:
Для платежа Softline Payments: техническое значение
Варианты значения:
- b2c - продукт предназначен для физических лиц
- b2b - продукт предназначен для юридичесих лиц
- mobile - мобильное приложение
Для платежа Softline Payments: техническое значение
Цена за одну единицу продукта
- Передается в валюте заказа
- Не учитывает VAT и скидку
- Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
Количество единиц продукта в заказе
Для платежа Softline Payments: всегда передается "1"
Для платежа Softline Payments: всегда передается "1"
Процент скидки на продукт в заказе
Если к продукту не была применена скидка, то параметр будет передан с пустым значением "".
Для платежа Softline Payments не используется, параметр будет передан с пустым значением ("")
Если к продукту не была применена скидка, то параметр будет передан с пустым значением "".
Для платежа Softline Payments не используется, параметр будет передан с пустым значением ("")
Сумма скидки
- Передается в валюте заказа
- Рассчитывается от цены без VAT
- Учитывает количество продукта в заказе
- Формат: Число с 2 десятичными знаками, разделитель - точка, передается как строка
- Если к продукту не была применена скидка, то параметр будет передан с пустым значением ""
Сумма VAT
- Передается в валюте заказа
- Учитывает количество продуктов
- Формат: Число с 2 десятичными знаками, разделитель - точка, передается как строка
- Если процент VAT равен нулю, то параметр будет передан с значением "0.00"
Полная стоимость продукта
- Передается в валюте заказа
- Учитывает количество продукта в заказе, VAT, скидку
- Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
Сумма вашего дохода
- Передается в валюте заказа
- Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
Лицензионная информация, отправленная покупателю по продукту
Передается, если продукт использует электронную доставку, отправка была выполнена и данные сохранены на стороне Softline.
Для платежа Softline Payments не используется
Передается, если продукт использует электронную доставку, отправка была выполнена и данные сохранены на стороне Softline.
Для платежа Softline Payments не используется
Код платежного метода
Варианты значений см. в справочнике.
Варианты значений см. в справочнике.
Название платежного метода
Это то название, которое покупатель видит в корзине при оформлении заказа.
Это то название, которое покупатель видит в корзине при оформлении заказа.
Код ошибки оплаты
* - Обязательный параметр, если при оплате произошла ошибка.
* - Обязательный параметр, если при оплате произошла ошибка.
Описание ошибки оплаты
* - Обязательный параметр, если при оплате произошла ошибка.
* - Обязательный параметр, если при оплате произошла ошибка.
Последние 4 цифры номера банковской карты покупателя
Может быть заполнено, если:
Может быть заполнено, если:
- Покупатель оплатил заказ банковской картой
- Заказ создан для продления AR подписки (дочерний) и еще не был оплачен. В этом случае используется значение из родительского заказа, если он был оплачен банковской картой
Срок окончания действия банковской карты покупателя
Может быть заполнено, если:
Если не заполнен, то параметр будет передан с пустым значением ("").
Может быть заполнено, если:
- Покупатель оплатил заказ банковской картой
- Заказ создан для продления AR подписки (дочерний) и еще не был оплачен. В этом случае используется значение из родительского заказа, если он был оплачен банковской картой
Если не заполнен, то параметр будет передан с пустым значением ("").
Признак, истекает ли срок действия банковской карты покупателя до окончания действия подписки
Передается в случае, если выполняются условия:
Варианты значений:
Передается в случае, если выполняются условия:
- В заказе есть подписка (AR или PMR)
- Для оплаты используется банковая карта и срок окончания ее действия определен (передан параметр payment.card_expiration_date). Если заказ создан для продления подписки (дочерний) и еще не оплачен, то используется значение из родительского заказа
Варианты значений:
- true - срок действия банковской карты истекает до окончания срока действия подписки
- false - срок действия банковской карты истекает после окончания срока действия подписки, т.е. [дата окончания действия карты] ≥ [дата окончания действия подписки]
Наличие оплаты в рассрочку
Узнайте подробнее об оплате в рассрочку. Этот и другие параметры по рассрочку учитывают только рассрочку Sofline Checkout (не учитывают рассрочку на стороне PSP).
Варианты значений:
Узнайте подробнее об оплате в рассрочку. Этот и другие параметры по рассрочку учитывают только рассрочку Sofline Checkout (не учитывают рассрочку на стороне PSP).
Варианты значений:
- true - оплата выполняется в рассрочку
- false - рассрочка не используется (оплата выполняется единоразово)
Сумма одного платежа (одной доли) при оплате в рассрочку
- * - Обязательный параметр, если payment.is_installment_payment равно true, в ином случае не передается
- Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка
- Сумма последней доли рассрочки может незначительно отличаться от остальных долей
Код валюты суммы одного платежа при оплате в рассрочку
- * - Обязательный параметр, если payment.is_installment_payment равно true, в ином случае не передается
- Всегда совпадает с значением параметра currency
Количество долей при оплате в рассрочку
* - Обязательный параметр, если payment.is_installment_payment равно true, в ином случае не передается.
* - Обязательный параметр, если payment.is_installment_payment равно true, в ином случае не передается.
Данные о подписке
Передается, если для продукта существует подписка с автоматическим продлением лицензии (AR / AR Trial) или подписка с оплатой продления вручную (PMR).
Обратите внимание. Создание подписки происходит по факту оплаты заказа-инициатора. Поэтому в событии order.created для такого заказа параметр subscription в общем случае отсутствует, так как подписка еще не создана на момент создания заказа. Если параметр присутствует для события order.created, то это может быть в двух случаях:
Передается, если для продукта существует подписка с автоматическим продлением лицензии (AR / AR Trial) или подписка с оплатой продления вручную (PMR).
Обратите внимание. Создание подписки происходит по факту оплаты заказа-инициатора. Поэтому в событии order.created для такого заказа параметр subscription в общем случае отсутствует, так как подписка еще не создана на момент создания заказа. Если параметр присутствует для события order.created, то это может быть в двух случаях:
- Оповещение отправлено по заказу, который создан для продления подписки
- Оповещение отправлено по заказу, который является инициатором подписки, и оплата на момент отправки события уже успешно завершена, то есть подписка создана
Идентификатор подписки
- * - Обязательный параметр, если был передан параметр subscription
- Формат: NN_MM, где NN это идентификатор заказа, который инициировал подписку (родительский заказ)
Идентификатор предыдущего заказа, созданного в рамках подписки:
Например:
Если в подписке участвовали заказы: 0001 (инициировал подписку), 0002 (первое продление подписки), 0003 (второе продление подписки), и webhook-оповещение отправляется:
- Если текущий заказ является родительским (инициирует подписку), то параметр будет передан с пустым значением (null)
- Если текущий заказ является дочерним, то в параметре будет передан идентификатор предыдущего дочернего заказа (или идентификатор родительского заказа, если это продление является первым)
Например:
Если в подписке участвовали заказы: 0001 (инициировал подписку), 0002 (первое продление подписки), 0003 (второе продление подписки), и webhook-оповещение отправляется:
- По факту события с заказом 0001, то "order_id":0001, "subscription.previous_order_id":null
- По факту события с заказом 0002, то "order_id":0002, "subscription.previous_order_id":0001
- По факту события с заказом 0003, то "order_id":0003, "subscription.previous_order_id":0002
Идентификатор позиции из предыдущего заказа, созданного в рамках подписки.
Идентификатор позиции - это дополнительный внутренний идентификатор, который присваивается продукту внутри заказа.
Например:
Идентификатор позиции - это дополнительный внутренний идентификатор, который присваивается продукту внутри заказа.
- Если текущий заказ является родительским (инициирует подписку), то параметр будет передан с пустым значением (null)
- Если текущий заказ является дочерним, то в параметре будет передан идентификатор позиции, которую занимал продукт в предыдущем заказе, созданном в рамках подписки
Например:
- В родительском заказе был продукт с идентификатором 11111, который инициировал подписку:
- В рамках заказа продукту был присвоен идентификатор позиции 12345
- По факту события с заказом в webhook-оповещении отправляется "subscription.previous_order_item_id":null
- При первом продлении подписки был создан заказ на продление:
- Для продления был использован продукт с идентификатором 22222
- В рамках заказа продукту был присвоен идентификатор позиции 54321
- По факту события с заказом в webhook-оповещении отправляется "subscription.previous_order_item_id":12345
Тип подписки
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
- AR - подписка с автоматическим продлением (включая AR Trial).
- PMR - подписка с продлением вручную.
Признак первого продления после бесплатного пробного периода
Он обозначает, что заказ, по которому отправлено webhook-оповещение, создан для продления подписки сразу после завершения бесплатного пробного периода.
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
Он обозначает, что заказ, по которому отправлено webhook-оповещение, создан для продления подписки сразу после завершения бесплатного пробного периода.
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
- true - если выполняются все условия:
- Заказ создан для продления AR подписки (заказ является дочерним, subscription.type равен AR)
- Это первый дочерний заказ данной подписки
- В подписке есть бесплатный пробный период (покупатель приобрел родительский продукт бесплатно)
- false - если условия для передачи true не выполнены
Статус подписки
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
Для подписок с продлением вручную (PMR) используются аналогичные статусы, но не доступно восстановление подписки.
* - Обязательный параметр, если был передан параметр subscription.
Варианты значений:
- active - подписка действует и не требует оплаты
- not paid - подписка ожидает оплаты
- cancelled - продление отменено
Для подписок с продлением вручную (PMR) используются аналогичные статусы, но не доступно восстановление подписки.
Срок действия продукта
- * - Обязательный параметр, если был передан параметр subscription
- Формат: ISO 8601 code: P[число][ед.измерения]
- Поддерживаемые единицы измерения: Y - год, M - месяц, D - день. Например, "P1Y" соответствует сроку "1 год"
Дата окончания периода действия подписки
- * - Обязательный параметр, если был передан параметр subscription
- Формат: YYYY-MM-DDThh:mm:ss±hh:mm
Дата следующей попытки оплаты продления для AR подписки
Передается только дата первой попытки оплаты, дополнительные повторные попытки при неуспешной оплате не учитываются. Если дата наступила, и попытка была неуспешна, или все попытки оплаты закончены (но подписка не была продлена), то передаваемая дата не изменится. После успешной оплаты будет рассчитана новая дата для оплаты следующего продления.
Передается только дата первой попытки оплаты, дополнительные повторные попытки при неуспешной оплате не учитываются. Если дата наступила, и попытка была неуспешна, или все попытки оплаты закончены (но подписка не была продлена), то передаваемая дата не изменится. После успешной оплаты будет рассчитана новая дата для оплаты следующего продления.
- * - Обязательный параметр, если был передан параметр subscription, и subscription.type равен AR
- Формат: YYYY-MM-DDThh:mm:ss±hh:mm
Ссылка на управление подпиской с автоматическим продлением (AR, AR Trial)
Ведет на якорь секции подписки на странице заказа-инициатора подписки.
* - Обязательный параметр, если был передан параметр subscription, и subscription.type равен AR. В ином случае параметр не передается.
Обратите внимание:
Ведет на якорь секции подписки на странице заказа-инициатора подписки.
* - Обязательный параметр, если был передан параметр subscription, и subscription.type равен AR. В ином случае параметр не передается.
Обратите внимание:
- Если webhook-оповещение отправлено по заказу-инициатору подписки (родительскому), то в параметрах order_detail_url и subscription.detail_url будет ссылка на одну и ту же страницу.
- Если webhook-оповещение отправлено по заказу на продление (дочернему), то в этих параметрах будут разные значения: order_detail_url ведет на страницу заказа на продление, а subscription.detail_url – на страницу заказа инициатора подписки.
- При получении webhook-оповещения по заказу/платежу в тестовой среде - ссылка будет предназначена для тестовой среды (ссылка будет иметь суффикс .demoslweb.com).
Дополнительные параметры заказа/платежа
Узнайте подробнее о дополнительных параметрах. Обратите внимание, срок хранения дополнительных параметров в заказе ограничен.
Узнайте подробнее о дополнительных параметрах. Обратите внимание, срок хранения дополнительных параметров в заказе ограничен.
Название дополнительного параметра
* - Обязательный параметр, если был передан параметр additional_data.
* - Обязательный параметр, если был передан параметр additional_data.
Значение дополнительного параметра
* - Обязательный параметр, если был передан параметр additional_data.
* - Обязательный параметр, если был передан параметр additional_data.
Информация о возврате
Передается, если webhook-оповещение отправлено по событию product.returned. В ином случае не передается.
Передается, если webhook-оповещение отправлено по событию product.returned. В ином случае не передается.
Тип операции
* - Обязательный параметр, если был передан параметр return.
Варианты значений:
* - Обязательный параметр, если был передан параметр return.
Варианты значений:
- returned - возврат или замена
- removed - удаление некорректной лицензионной информации, например, если по техническим причинам покупатель получил ошибочные данные вместо лицензионной информации
Дата и время события
Если webhook-оповещение отправляется по событию product.returned, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
Если webhook-оповещение отправляется по событию product.returned, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
- * - Обязательный параметр, если был передан параметр return
- Формат: YYYY-MM-DDThh:mm:ss±hh:mm
Описание причины события
* - Обязательный параметр, если был передан параметр return.
Примеры значений:
* - Обязательный параметр, если был передан параметр return.
Примеры значений:
- Проблема установки / активации
- Географически ограничения
- Ошибка при выборе продукта
- Не устроил срок доставки
- Не возможно поставить продукт
- Автопродление
- Повторная оплата
- ChargeBack
- Недоволен программой
- TYPO
- Дубли заказа
- Тестовый заказ
Порядковый номер позиции, которую занимает продукт в заказе
Нумерация позиций сохраняется по всем событиям.
Формат: "[порядковый номер позиции в заказе]-of-[общее количество позиций в заказе]".
Например: "1-of-2", если в заказе всего два продукта и уведомление отправлено по первому из них.
(Для платежа Softline Payments) Всегда будет передано "1-of-1".
Нумерация позиций сохраняется по всем событиям.
Формат: "[порядковый номер позиции в заказе]-of-[общее количество позиций в заказе]".
Например: "1-of-2", если в заказе всего два продукта и уведомление отправлено по первому из них.
(Для платежа Softline Payments) Всегда будет передано "1-of-1".
Ответ на оповещение
В случае успешного получения оповещения ваш веб-сервис должен вернуть ответ на полученное оповещение.
Возможные ответы:
- HTTP/1.1 200 OK - оповещение успешно получено.
- Любой другой ответ или отсутствие ответа - оповещение не получено.
В случае, если оповещение не было получено, то:
- Отправка будет повторяться по следующему расписанию: 1 раз в 20 минут.
- Повторная отправка будет выполняться до тех пор, пока не будет получен код ответа HTTP/1.1 200 OK или не будет совершено 10 попыток.
- При повторной отправке данные уведомления не обновляются. В случае изменения заказа/платежа во время отправки оповещения - содержание оповещения не изменится.