Авторизация
x-hallify-signature: <HALLIFY_SIGNATURE>Подпись HMAC-SHA256. Точный протокол каждой операции указан в метаданных x-hallify-hmac и её описании.
Параметры
providerKeyПуть · ОбязательноСтабильный ключ платёжного провайдера, выбирающий профиль проверки webhook для этой доставки.
stringПолное определение
{ "example": "simulator", "type": "string" }x-hallify-timestampЗаголовок · ОбязательноВремя в формате RFC3339; допустимое расхождение часов — ±300 секунд.
stringПолное определение
{ "type": "string", "example": "example" }
Тело запроса
Обязательно
Идентификаторы попытки оплаты и события провайдера, статус, время события, необязательные внешние метаданные и маскированные сведения карты: подписанное платёжное событие.
application/json
Полное определение
{
"$ref": "#/components/schemas/PaymentProviderWebhookDto"
}Ответы
200Возвращает признак применения подписанного события провайдера или его распознавания как идемпотентного повтора.
Полное определение
{
"$ref": "#/components/schemas/PaymentProviderWebhookResultDto"
}{
"attemptId": "ebc45c68-e765-435d-8f7f-7ef875ce04bf",
"status": "PENDING",
"revision": 1,
"duplicate": true
}400Некорректный ключ провайдера или тело платёжного webhook.
Полное определение
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"statusCode": 400,
"error": "errors:http.badRequest",
"code": "HTTP_BAD_REQUEST",
"message": "errors:http.badRequest",
"translationKey": "errors:http.badRequest"
}401Платёжный webhook недоступен либо его HMAC-подпись недействительна или просрочена.
Полное определение
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"statusCode": 401,
"error": "errors:http.unauthorized",
"code": "HTTP_UNAUTHORIZED",
"message": "errors:http.unauthorized",
"translationKey": "errors:http.unauthorized"
}404Попытка оплаты не найдена.
Полное определение
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"statusCode": 404,
"error": "errors:http.notFound",
"code": "HTTP_NOT_FOUND",
"message": "errors:http.notFound",
"translationKey": "errors:http.notFound"
}409Идентификатор события провайдера повторно использован с другим телом.
Полное определение
{
"$ref": "#/components/schemas/TranslatedErrorDto"
}{
"statusCode": 409,
"error": "errors:http.conflict",
"code": "HTTP_CONFLICT",
"message": "errors:http.conflict",
"translationKey": "errors:http.conflict"
}Схемы
PaymentProviderWebhookDto
Подписанное тело события платёжного провайдера после проверки HMAC на входе webhook.
attemptIdОбязательноUUID Hallify для
attemptId.string · uuidПолное определение
{ "type": "string", "format": "uuid", "description": "UUID Hallify для `attemptId`.", "example": "ebc45c68-e765-435d-8f7f-7ef875ce04bf" }eventIdОбязательноНепрозрачный идентификатор
eventId; клиент не должен предполагать формат UUID. Ограничения: максимальная длина 191.stringПолное определение
{ "type": "string", "maxLength": 191, "description": "Непрозрачный идентификатор `eventId`; клиент не должен предполагать формат UUID. Ограничения: максимальная длина 191.", "example": "example-id" }statusОбязательноТекущий статус жизненного цикла
status; допустимые значения: AUTHORIZED, CAPTURED, DECLINED, FAILED, CANCELED.stringПолное определение
{ "type": "string", "enum": [ "AUTHORIZED", "CAPTURED", "DECLINED", "FAILED", "CANCELED" ], "description": "Текущий статус жизненного цикла `status`; допустимые значения: AUTHORIZED, CAPTURED, DECLINED, FAILED, CANCELED.", "example": "AUTHORIZED" }occurredAtОбязательноВремя
occurredAtв формате RFC3339; разные часовые смещения могут обозначать один абсолютный момент.string · date-timeПолное определение
{ "type": "string", "format": "date-time", "description": "Время `occurredAt` в формате RFC3339; разные часовые смещения могут обозначать один абсолютный момент.", "example": "2026-01-15T12:00:00.000Z" }externalReferenceНеобязательноИдентификатор, назначенный внешней системой и сохранённый для сверки платёжного webhook. Максимальная длина — 128 символов.
stringПолное определение
{ "type": "string", "maxLength": 128, "description": "Идентификатор, назначенный внешней системой и сохранённый для сверки платёжного webhook. Максимальная длина — 128 символов.", "example": "example-reference" }cardBrandНеобязательноПлатёжная система карты
cardBrand. Ограничения: максимальная длина 32.stringПолное определение
{ "type": "string", "maxLength": 32, "description": "Платёжная система карты `cardBrand`. Ограничения: максимальная длина 32.", "example": "example" }cardLast4НеобязательноПоследние четыре цифры карты
cardLast4.stringПолное определение
{ "type": "string", "pattern": "^\\d{4}$", "description": "Последние четыре цифры карты `cardLast4`.", "example": "0001" }
Полное определение
{
"type": "object",
"properties": {
"attemptId": {
"type": "string",
"format": "uuid",
"description": "UUID Hallify для `attemptId`.",
"example": "ebc45c68-e765-435d-8f7f-7ef875ce04bf"
},
"eventId": {
"type": "string",
"maxLength": 191,
"description": "Непрозрачный идентификатор `eventId`; клиент не должен предполагать формат UUID. Ограничения: максимальная длина 191.",
"example": "example-id"
},
"status": {
"type": "string",
"enum": [
"AUTHORIZED",
"CAPTURED",
"DECLINED",
"FAILED",
"CANCELED"
],
"description": "Текущий статус жизненного цикла `status`; допустимые значения: AUTHORIZED, CAPTURED, DECLINED, FAILED, CANCELED.",
"example": "AUTHORIZED"
},
"occurredAt": {
"type": "string",
"format": "date-time",
"description": "Время `occurredAt` в формате RFC3339; разные часовые смещения могут обозначать один абсолютный момент.",
"example": "2026-01-15T12:00:00.000Z"
},
"externalReference": {
"type": "string",
"maxLength": 128,
"description": "Идентификатор, назначенный внешней системой и сохранённый для сверки платёжного webhook. Максимальная длина — 128 символов.",
"example": "example-reference"
},
"cardBrand": {
"type": "string",
"maxLength": 32,
"description": "Платёжная система карты `cardBrand`. Ограничения: максимальная длина 32.",
"example": "example"
},
"cardLast4": {
"type": "string",
"pattern": "^\\d{4}$",
"description": "Последние четыре цифры карты `cardLast4`.",
"example": "0001"
}
},
"required": [
"attemptId",
"eventId",
"status",
"occurredAt"
],
"description": "Подписанное тело события платёжного провайдера после проверки HMAC на входе webhook.",
"example": {
"attemptId": "fc6f0fa9-b807-43e6-87b6-56edb271fb3f",
"eventId": "evt_01JHALLIFYEXAMPLE",
"status": "CAPTURED",
"occurredAt": "2026-08-11T10:30:00.000Z",
"externalReference": "provider-payment-1842",
"cardBrand": "visa",
"cardLast4": "4242"
}
}PaymentProviderWebhookResultDto
Возвращает признак применения подписанного события провайдера или его распознавания как идемпотентного повтора.
attemptIdОбязательноUUID Hallify для
attemptId.string · uuidПолное определение
{ "type": "string", "format": "uuid", "description": "UUID Hallify для `attemptId`.", "example": "ebc45c68-e765-435d-8f7f-7ef875ce04bf" }statusОбязательноТекущий статус жизненного цикла
status; допустимые значения: PENDING, APPROVED, FAILED, CANCELED, CREATED, REQUIRES_ACTION, AUTHORIZED, CAPTURED, DECLINED, OFFLINE_ACCEPTED, RECONCILIATION_REQUIRED.stringПолное определение
{ "type": "string", "enum": [ "PENDING", "APPROVED", "FAILED", "CANCELED", "CREATED", "REQUIRES_ACTION", "AUTHORIZED", "CAPTURED", "DECLINED", "OFFLINE_ACCEPTED", "RECONCILIATION_REQUIRED" ], "description": "Текущий статус жизненного цикла `status`; допустимые значения: PENDING, APPROVED, FAILED, CANCELED, CREATED, REQUIRES_ACTION, AUTHORIZED, CAPTURED, DECLINED, OFFLINE_ACCEPTED, RECONCILIATION_REQUIRED.", "example": "PENDING" }revisionОбязательноМонотонно возрастающая ревизия
revisionдля оптимистичного контроля конкурентных изменений.integerПолное определение
{ "type": "integer", "description": "Монотонно возрастающая ревизия `revision` для оптимистичного контроля конкурентных изменений.", "example": 1 }duplicateОбязательноБыло ли переданное событие уже принято и обработано как повтор.
booleanПолное определение
{ "type": "boolean", "description": "Было ли переданное событие уже принято и обработано как повтор.", "example": true }
Полное определение
{
"type": "object",
"properties": {
"attemptId": {
"type": "string",
"format": "uuid",
"description": "UUID Hallify для `attemptId`.",
"example": "ebc45c68-e765-435d-8f7f-7ef875ce04bf"
},
"status": {
"type": "string",
"enum": [
"PENDING",
"APPROVED",
"FAILED",
"CANCELED",
"CREATED",
"REQUIRES_ACTION",
"AUTHORIZED",
"CAPTURED",
"DECLINED",
"OFFLINE_ACCEPTED",
"RECONCILIATION_REQUIRED"
],
"description": "Текущий статус жизненного цикла `status`; допустимые значения: PENDING, APPROVED, FAILED, CANCELED, CREATED, REQUIRES_ACTION, AUTHORIZED, CAPTURED, DECLINED, OFFLINE_ACCEPTED, RECONCILIATION_REQUIRED.",
"example": "PENDING"
},
"revision": {
"type": "integer",
"description": "Монотонно возрастающая ревизия `revision` для оптимистичного контроля конкурентных изменений.",
"example": 1
},
"duplicate": {
"type": "boolean",
"description": "Было ли переданное событие уже принято и обработано как повтор.",
"example": true
}
},
"required": [
"attemptId",
"status",
"revision",
"duplicate"
],
"description": "Возвращает признак применения подписанного события провайдера или его распознавания как идемпотентного повтора.",
"example": {
"attemptId": "ebc45c68-e765-435d-8f7f-7ef875ce04bf",
"status": "PENDING",
"revision": 1,
"duplicate": true
}
}TranslatedErrorDto
Стабильная оболочка ошибки общего обработчика HTTP-исключений. Дополнительные машинные данные домена вложены в details.
statusCodeОбязательноHTTP-статус, повторённый из ответа.
integerПолное определение
{ "type": "integer", "description": "HTTP-статус, повторённый из ответа.", "example": 400 }errorОбязательноКлюч перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.
stringПолное определение
{ "type": "string", "description": "Ключ перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.", "example": "errors.request.invalid" }codeОбязательноСтабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями.
stringПолное определение
{ "type": "string", "example": "HTTP_BAD_REQUEST", "description": "Стабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями." }messageОбязательноКлюч перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе.
stringПолное определение
{ "type": "string", "example": "errors:http.badRequest", "description": "Ключ перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе." }translationKeyОбязательноКанонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте.
stringПолное определение
{ "type": "string", "example": "errors:http.badRequest", "description": "Канонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте." }translationValuesНеобязательноНеобязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.
objectПолное определение
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.", "example": { "exampleKey": "example" } }validationErrorsНеобязательноОшибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.
arrayПолное определение
{ "description": "Ошибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.", "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" }, "example": [ { "field": "email", "translationKey": "validation:isEmail", "code": "isEmail", "message": "validation:isEmail" } ] }detailsНеобязательноНеобязательные сведения о доменных препятствиях или ошибках валидации.
oneOfПолное определение
{ "description": "Необязательные сведения о доменных препятствиях или ошибках валидации.", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/JsonValue" }, "example": [ "example" ] }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "example": { "exampleKey": "example" } } ], "example": [ "example" ] }
Полное определение
{
"type": "object",
"properties": {
"statusCode": {
"type": "integer",
"description": "HTTP-статус, повторённый из ответа.",
"example": 400
},
"error": {
"type": "string",
"description": "Ключ перевода HTTP-категории, например errors:http.conflict. Конкретную причину определяют code и translationKey.",
"example": "errors.request.invalid"
},
"code": {
"type": "string",
"example": "HTTP_BAD_REQUEST",
"description": "Стабильный машинный код домена либо стандартный HTTP_*, если доменный код не задан. Используйте это поле и HTTP-статус для программной логики; локализованная формулировка не управляет повторами или бизнес-решениями."
},
"message": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Ключ перевода, идентичный translationKey. API не возвращает локализованный текст интерфейса. Найдите перевод ключа и подставьте translationValues в приложении-потребителе."
},
"translationKey": {
"type": "string",
"example": "errors:http.badRequest",
"description": "Канонический ключ перевода, идентичный message. Ключи errors:http.* соответствующего статуса описывают неуточнённые ошибки. Публичные ключи и пояснения EN/RU перечислены в Developers; неизвестный ключ требует локализованного запасного сообщения в клиенте."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.",
"example": {
"exampleKey": "example"
}
},
"validationErrors": {
"description": "Ошибки проверки полей с ключами переводов и стабильными кодами валидаторов. Введённые значения и исходные тексты валидаторов не включаются.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidationErrorDto"
},
"example": [
{
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
]
},
"details": {
"description": "Необязательные сведения о доменных препятствиях или ошибках валидации.",
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"example": [
"example"
]
}
},
"required": [
"statusCode",
"error",
"code",
"message",
"translationKey"
],
"description": "Стабильная оболочка ошибки общего обработчика HTTP-исключений. Дополнительные машинные данные домена вложены в details.",
"example": {
"statusCode": 400,
"error": "errors:http.badRequest",
"code": "HTTP_BAD_REQUEST",
"message": "errors:http.badRequest",
"translationKey": "errors:http.badRequest"
}
}ValidationErrorDto
Ошибка проверки поля с путём поля, стабильным кодом валидатора и ключом перевода. Человекочитаемый текст принадлежит приложению-потребителю.
fieldОбязательноПубличный путь поля. Вложенные свойства и индексы массива разделены точками.
stringПолное определение
{ "type": "string", "example": "email", "description": "Публичный путь поля. Вложенные свойства и индексы массива разделены точками." }translationKeyОбязательноКлюч перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers.
stringПолное определение
{ "type": "string", "example": "validation:isEmail", "description": "Ключ перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers." }codeОбязательноСтабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы.
stringПолное определение
{ "type": "string", "example": "isEmail", "description": "Стабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы." }messageОбязательноКлюч перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются.
stringПолное определение
{ "type": "string", "example": "validation:isEmail", "description": "Ключ перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются." }translationValuesНеобязательноНеобязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.
objectПолное определение
{ "type": "object", "additionalProperties": { "oneOf": [ { "type": "string", "example": "example" }, { "type": "number", "example": 0 }, { "type": "boolean", "example": true } ], "example": "example" }, "description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.", "example": { "exampleKey": "example" } }
Полное определение
{
"type": "object",
"properties": {
"field": {
"type": "string",
"example": "email",
"description": "Публичный путь поля. Вложенные свойства и индексы массива разделены точками."
},
"translationKey": {
"type": "string",
"example": "validation:isEmail",
"description": "Ключ перевода этого валидатора, идентичный message. Найдите его в клиентском словаре; см. публичный каталог ошибок Developers."
},
"code": {
"type": "string",
"example": "isEmail",
"description": "Стабильный идентификатор валидатора для ошибки поля. Пользовательские валидаторы могут определять дополнительные идентификаторы."
},
"message": {
"type": "string",
"example": "validation:isEmail",
"description": "Ключ перевода, описывающий ошибку проверки поля, идентичный translationKey. Введённые значения и тексты валидаторов не включаются."
},
"translationValues": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "string",
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
}
],
"example": "example"
},
"description": "Необязательные скалярные значения параметров шаблона перевода. Обрабатывайте их как данные, экранируйте при отображении и никогда не используйте как настройки переводчика.",
"example": {
"exampleKey": "example"
}
}
},
"required": [
"field",
"translationKey",
"code",
"message"
],
"description": "Ошибка проверки поля с путём поля, стабильным кодом валидатора и ключом перевода. Человекочитаемый текст принадлежит приложению-потребителю.",
"example": {
"field": "email",
"translationKey": "validation:isEmail",
"code": "isEmail",
"message": "validation:isEmail"
}
}JsonValue
Рекурсивно допустимое JSON-значение. Используется только там, где контракт явно разрешает произвольные структурированные данные.
Полное определение
{
"oneOf": [
{
"type": "string",
"nullable": true,
"example": "example"
},
{
"type": "number",
"example": 0
},
{
"type": "boolean",
"example": true
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JsonValue"
},
"example": [
"example"
]
},
{
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/JsonValue"
},
"example": {
"exampleKey": "example"
}
}
],
"description": "Рекурсивно допустимое JSON-значение. Используется только там, где контракт явно разрешает произвольные структурированные данные.",
"example": "example"
}