Skip to main content

​
События вебхуков

Love&Pay отправляет уведомления о различных событиях на ваш webhook URL в реальном времени.

​
Формат уведомления

Все вебхуки отправляются методом POST с JSON payload: 
{
  "id": "evt_1234567890_abc123",
  "event": "invoice.paid",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "PAID",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "paidAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}
Важно: ID счета передается в поле data.id, не data.invoiceId

​
Заголовки запроса

ЗаголовокОписание
Content-Typeapplication/json
x-webhook-signatureПодпись в формате sha256=xxx
x-webhook-idУникальный ID вебхука
x-webhook-timestampUnix timestamp отправки (миллисекунды)
User-AgentLovePay/1.0

​
Доступные события

События счетов

  • INVOICE_CREATED — Счёт создан
  • INVOICE_UPDATED — Данные счёта обновлены
  • INVOICE_PAID — Счёт оплачен успешно
  • INVOICE_CANCELLED — Счёт отменён
  • INVOICE_EXPIRED — Истёк срок действия счёта

События транзакций

  • TRANSACTION_CREATED — Создана транзакция
  • TRANSACTION_COMPLETED — Транзакция завершена успешно
  • TRANSACTION_FAILED — Транзакция не прошла

​
События счетов

​
INVOICE_CREATED

Отправляется при создании нового счёта. 
{
  "id": "evt_1234567890_abc123",
  "event": "INVOICE_CREATED",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "PENDING",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
INVOICE_UPDATED

Отправляется при обновлении данных счёта. 
{
  "id": "evt_1234567890_def456",
  "event": "INVOICE_UPDATED",
  "timestamp": "2024-01-15T10:15:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "PENDING",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:15:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
INVOICE_PAID

Отправляется при успешной оплате счёта. Это основное событие для подтверждения оплаты. 
{
  "id": "evt_1234567890_ghi789",
  "event": "INVOICE_PAID",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "PAID",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "paidAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
INVOICE_EXPIRED

Отправляется когда срок оплаты счёта истёк. 
{
  "id": "evt_1234567890_jkl012",
  "event": "INVOICE_EXPIRED",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "EXPIRED",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "expiredAt": "2024-01-15T11:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
INVOICE_CANCELLED

Отправляется при отмене счёта. 
{
  "id": "evt_1234567890_mno345",
  "event": "INVOICE_CANCELLED",
  "timestamp": "2024-01-15T10:45:00.000Z",
  "data": {
    "id": "uuid-v4",
    "invoiceNumber": "INV-12345",
    "amount": 150000,
    "currency": "RUB",
    "status": "CANCELLED",
    "customerEmail": "[email protected]",
    "customerName": "Иван Иванов",
    "customerPhone": "+79991234567",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "cancelledAt": "2024-01-15T10:45:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
События транзакций

​
TRANSACTION_CREATED

Отправляется при создании новой транзакции. 
{
  "id": "evt_1234567890_pqr678",
  "event": "TRANSACTION_CREATED",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": "transaction-uuid",
    "invoiceId": "invoice-uuid",
    "amount": 150000,
    "currency": "RUB",
    "status": "PENDING",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
TRANSACTION_COMPLETED

Отправляется при успешном завершении транзакции. 
{
  "id": "evt_1234567890_stu901",
  "event": "TRANSACTION_COMPLETED",
  "timestamp": "2024-01-15T10:30:05.000Z",
  "data": {
    "id": "transaction-uuid",
    "invoiceId": "invoice-uuid",
    "amount": 150000,
    "currency": "RUB",
    "status": "COMPLETED",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "completedAt": "2024-01-15T10:30:05.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
TRANSACTION_FAILED

Отправляется когда транзакция не прошла. 
{
  "id": "evt_1234567890_vwx234",
  "event": "TRANSACTION_FAILED",
  "timestamp": "2024-01-15T10:30:05.000Z",
  "data": {
    "id": "transaction-uuid",
    "invoiceId": "invoice-uuid",
    "amount": 150000,
    "currency": "RUB",
    "status": "FAILED",
    "failureReason": "Недостаточно средств",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "failedAt": "2024-01-15T10:30:05.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

## События KYC

### KYC_COMPLETED

Отправляется при успешном прохождении KYC верификации.

```json
{
  "id": "evt_1234567890_kyc001",
  "event": "KYC_COMPLETED",
  "timestamp": "2024-01-15T14:00:00.000Z",
  "data": {
    "sessionId": "kyc_abc123",
    "status": "COMPLETED",
    "level": "basic",
    "metadata": {
      "userId": "user_123"
    },
    "completedAt": "2024-01-15T14:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
KYC_FAILED

Отправляется при неудачной KYC верификации. 
{
  "id": "evt_1234567890_kyc002",
  "event": "KYC_FAILED",
  "timestamp": "2024-01-15T14:00:00.000Z",
  "data": {
    "sessionId": "kyc_abc123",
    "status": "FAILED",
    "level": "basic",
    "failureReason": "document_expired",
    "metadata": {
      "userId": "user_123"
    },
    "failedAt": "2024-01-15T14:00:00.000Z"
  },
  "partnerId": "partner-uuid",
  "retryCount": 0
}

​
Обработка вебхуков

​
Требования к ответу

HTTP 200-299

Ваш сервер должен вернуть код 200-299 для подтверждения получения

Таймаут 30 секунд

Ответ должен быть получен в течение 30 секунд

Идемпотентность

Обрабатывайте события идемпотентно — они могут приходить повторно

Верификация

Всегда проверяйте подпись x-webhook-signature

​
Повторные попытки

При неудачной доставке (таймаут или код ≥400) Love&Pay автоматически повторяет отправку до 5 раз:
ПопыткаЗадержка
11 минута
25 минут
330 минут
42 часа
512 часов
Количество повторных попыток отображается в поле retryCount в payload вебхука.