По всей базе знаний
Softline Payments
Наверх
По всей базе знаний
Softline PaymentsИнтеграцияWebhooks
[POST] Отправка webhook-оповещения

[POST] Отправка webhook-оповещения

Описание запроса

Оповещение отправляется по факту наступления события с платежом (или с родительским заказом в сценарии покупки через корзину с последующими автоплатежами).

В запросе по платежу передаются:

Если оповещение отправляется по сценарию покупки через корзину с последующими автоплатежами, то в запросе будут заполнены соответствующие данные о продукте/корзине. См. описание формата в документации Checkout.

Описание запроса

Характеристики запроса:

  • Метод: POST
  • Формат: JSON
  • Кодировка: UTF-8

Параметры заголовка

content-type
string
required
MIME-тип данных

Должен быть равен "application/json".
signature
string
required
Подпись webhook-оповещения Проверка подписи позволит подтвердить, что оповещение отправлено Softline.

Формат подписи: hash, сгенерированный по алгоритму SHA-512, от строки: 
[secret key];[event];[order_id];[create_date];[payment_method];[currency];[customer.email]
где: См. пример генерации подписи.

Параметры в теле запроса

event
string
required
Код события, по которому отправлено оповещение
Значение кодов см. в справочнике.
event_date
string
required
Дата и время события, по которому отправлено webhook-оповещение

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
order_id
number
required
Идентификатор платежа
Этот идентификатор вы таже получаете в ответ на запрос создания платежа (order_id) или проведение автоплатежа (order_id).
order_name
string
required
Дополненный идентификатор платежа
Формат идентификатора, в котором к нему может быть добавлен префикс.
status
string
required
Статус платежа
Узнайте подробнее о статусах платежа.

Варианты значений:
  • not paid - оплата не завершена
  • paid - оплата успешно завершена
  • deleted - платеж удален, в том числе, если был сделан полный возврат
external_id
string
required
Идентификатор платежа на вашей стороне
Этот идентификатор вы передаете при создании платежа (payment_id) или проведении автоплатежа (payment_id).
create_date
string
required
Дата и время создания платежа
Если webhook-оповещение отправляется по событию order.created, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.

Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
pay_date
string
Дата и время успешного завершения оплаты
Если webhook-оповещение отправляется по событию order.payment.succeeded, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
  • Формат: YYYY-MM-DDThh:mm:ss±hh:mm
  • Если оплата не завершена, то параметр будет передан с пустым значением ("")
currency
string
required
Код валюты платежа
  • Формат: ISO 4217 alpha-3, 3 символа
  • Варианты значений см. в справочнике
locale
string
required
Код языка интерфейса платежной формы
Варианты значений см. в справочнике.
recurring_indicator
boolean
required
Признак родительского заказа с возможностью автооплаты через Payments API
Варианты значений:
order_detail_url
string
required
Cсылка на страницу платежной формы
При получении webhook-оповещения по платежу/заказу в тестовой среде - ссылка будет предназначена для тестовой среды (ссылка будет иметь суффикс .demoslweb.com).
customer
object
required
Данные покупателя
customer
/
country
string
required
Код страны покупателя

customer
/
type
string
required
Тип покупателя

Варианты значения:
  • physical - физическое лицо
  • juridical - юридическое лицо
customer
/
email
string
required
E-mail покупателя
customer
/
first_name
string
required
Имя покупателя
customer
/
last_name
string
required
Фамилия покупателя
customer
/
phone
string
Телефон покупателя
Если не заполнен, то параметр будет передан с пустым значением ("").
customer
/
vat_number
string
Номер налогоплательщика покупателя
Также, используется для передачи:
  • ИНН компании при оплате в рублях
Если не заполнен, то параметр будет передан с пустым значением ("").
customer
/
company_name
string
Наименование компании
Если не заполнено, то параметр будет передан с пустым значением ("").
customer
/
company_billing_address
string
Юридический адрес компании
Если не заполнен, то параметр будет передан с пустым значением ("").
customer
/
company_delivery_address
string
Фактический адрес компании
Если не заполнен, то параметр будет передан с пустым значением ("").
product
object
required
Данные платежа

Если оповещение отправляется по родительскому заказу при покупке через корзину с последующими автоплатежами, то в запросе будут заполнены соответствующие данные о продукте/корзине. См. описание формата в документации Checkout.
product
/
id
string
required
Не используется, будет заполнено техническим значением.
product
/
vendor_code
string
Не используется, будет передано пустым ("") или заполнено техническим значением.
product
/
sku
string
Не используется, будет передано пустым ("") или заполнено техническим значением.
product
/
business_segment
string
Не используется, будет передано пустым ("") или заполнено техническим значением.
product
/
name
string
required
Описание платежа
Это описание вы передаете при создании платежа (payment_description) или проведении автоплатежа (payment_description).
product
/
price
string
required
Сумма платежа без VAT

Формат: Число с 2 десятичными знаками, разделитель - точка. Передается как строка.
product
/
quantity
number
required
Не используется, всегда передается "1".
product
/
discount_percent
string
Не используется, параметр будет передан с пустым значением ("").
product
/
discount_amount
string
Не используется, параметр будет передан с пустым значением ("").
product
/
vat_percent
string
required
Процент VAT
product
/
vat_amount
string
required
Сумма VAT
  • Передается в валюте заказа
  • Формат: Число с 2 десятичными знаками, разделитель - точка, передается как строка
  • Если процент VAT равен нулю, то параметр будет передан с значением "0.00"
product
/
amount
string
required
Полная сумма платежа
  • Передается в валюте заказа
  • Включает VAT
  • Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
product
/
margin
string
required
Сумма вашего дохода
  • Передается в валюте заказа
  • Формат: число с 2 десятичными знаками, разделитель - точка, передается как строка
payment
object
required
Информация об оплате
payment
/
payment_method
string
required
Код платежного метода
Варианты значений см. в справочнике.
payment
/
payment_system_name
string
required
Название платежного метода (техническое значение)
payment
/
payment_error_code
string
required*
Код ошибки оплаты

* - Обязательный параметр, если webhook-оповещение отправляется по событию ошибки оплаты (order.payment.failed), в ином случае не передается.
payment
/
payment_error_description
string
required*
Описание ошибки оплаты

* - Обязательный параметр, если webhook-оповещение отправляется по событию ошибки оплаты (order.payment.failed), в ином случае не передается.
payment
/
card_type
string
Тип банковской карты покупателя
Примеры значений: Visa, MASTERCARD.

Может быть заполнено, если покупатель успешно завершил оплату банковской картой. В ином случае, параметр будет передан с пустым значением ("").
payment
/
card_last_4
string
Последние 4 цифры номера банковской карты покупателя

Может быть заполнено, если покупатель успешно завершил оплату банковской картой. В ином случае, параметр будет передан с пустым значением (null).
payment
/
card_expiration_date
string
Срок окончания действия банковской карты покупателя
Может быть заполнено, если покупатель успешно завершил оплату банковской картой. В ином случае, параметр будет передан с пустым значением ("").

Формат значения: MM/YYYY, например, 12/2026.
payment
/
is_card_expired
boolean
required
Не используется, всегда будет передано false.
payment
/
is_installment_payment
boolean
required
Не используется, всегда будет передано false.
additional_data
array [objects]
Дополнительные параметры
Эти параметры могут быть заполнены при создании платежа (additional_data) или в процессе обработки. Обратите внимание, срок хранения дополнительных параметров в платеже ограничен.
additional_data / [object]
/
name
string
required*
Название дополнительного параметра

* - Обязательный параметр, если параметр additional_data передан.
additional_data / [object]
/
value
string
required*
Значение дополнительного параметра

* - Обязательный параметр, если параметр additional_data передан.
return
object
Информация о возврате

Передается, если webhook-оповещение отправлено по событию product.returned. В ином случае не передается.
return
/
type
string
required*
Тип операции

* - Обязательный параметр, если был передан параметр return.

Варианты значений:
  • returned - возврат/chargeback
  • removed - не используется в Softline Payments
return
/
date
required*
Дата и время возврата.
Если webhook-оповещение отправляется по событию product.returned, то дата и время в этом параметре будут совпадать со значением, которое передано в параметре event_date.
  • * - Обязательный параметр, если был передан параметр return.
  • Формат: YYYY-MM-DDThh:mm:ss±hh:mm.
return
/
reason
string
required*
Описание причины возврата

* - Обязательный параметр, если был передан параметр return.

Примеры значений:
  • Географически ограничения
  • Повторная оплата
  • ChargeBack
  • Дубли заказа
  • Тестовый заказ
или другая причина.
document_part
string
required
Не используется, всегда будет передано "1-of-1".

Ответ на оповещение

В случае получения оповещения ваш веб-сервис должен вернуть ответ на полученное оповещение. Время ожидания ответа: 1 минута.

Возможные ответы:

  • HTTP/1.1 200 OK - оповещение успешно получено
  • Любой другой ответ или отсутствие ответа - оповещение не получено

В случае, если оповещение не было получено, то:

  • Отправка будет повторяться по следующему расписанию: 1 раз в 20 минут
  • Повторная отправка будет выполняться до тех пор, пока не будет получен код ответа HTTP/1.1 200 OK или не будет совершено 10 попыток
  • При повторной отправке данные уведомления не обновляются. В случае изменения заказа/платежа во время отправки оповещения - содержание оповещения не изменится
Политика конфиденциальности
© 2024 Softline