Callbacks (Webhooks)

Огляд

Callback — це HTTP-запит від RozetkaPay до вашого сервера з інформацією про статус платежу.

Налаштування

При створенні платежу вкажіть callback_url:

curl -X POST https://api.rozetkapay.com/api/payments/v1/new \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "UAH",
    "external_id": "order_12345",
    "callback_url": "https://your-site.com/api/rozetkapay/callback",
    "result_url": "https://your-site.com/order/12345/result"
  }'

Верифікація підпису

Кожен callback від RozetkaPay підписується за допомогою вашого пароля. Підпис передається в заголовку X-ROZETKAPAY-SIGNATURE.

Алгоритм розрахунку

signature = base64url_encode(sha1($password + base64url_encode($json_body) + $password))

Приклад на Python

import base64
import hashlib

def verify_webhook_signature(password: str, body: str, signature: str) -> bool:
    """
    Верифікація підпису webhook від RozetkaPay.

    Args:
        password: Пароль мерчанта (той самий, що для API)
        body: Тіло запиту як рядок
        signature: Значення заголовка X-ROZETKAPAY-SIGNATURE

    Returns:
        True якщо підпис валідний
    """
    base64_body = base64.urlsafe_b64encode(body.encode('UTF-8')).decode('UTF-8')
    signature_data = password + base64_body + password
    calculated = base64.urlsafe_b64encode(
        hashlib.sha1(signature_data.encode('UTF-8')).digest()
    ).decode('UTF-8')
    return calculated == signature


# Приклад використання
callback_body = '{"payment_id": "abc123", "status": "success"}'
received_signature = "aBcDeFgHiJkLmNoPqRsTuVwXyZ=="
password = "your_api_password"

if verify_webhook_signature(password, callback_body, received_signature):
    print("Підпис валідний - обробляємо callback")
else:
    print("Підпис невалідний - відхиляємо запит")

Приклад на bash

#!/bin/bash

PASSWORD="your_api_password"
BODY='{"payment_id": "abc123", "status": "success"}'

# Base64 encode body
BASE64_BODY=$(echo -n "$BODY" | base64 | tr '+/' '-_')

# Calculate signature
SIGNATURE=$(echo -n "${PASSWORD}${BASE64_BODY}${PASSWORD}" | sha1sum | cut -d' ' -f1 | xxd -r -p | base64 | tr '+/' '-_')

echo "Calculated signature: $SIGNATURE"

Повторна відправка callback

Якщо вам потрібно повторно отримати callback для платежу, використовуйте endpoint:

curl -X POST https://api.rozetkapay.com/api/payments/v1/callback/resend \
  -u "login:password" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order_12345"
  }'

Можна також вказати конкретну операцію через поле operation. Якщо не вказано — відправиться callback для останньої операції.

Структура callback

Callback містить повну інформацію про платіж:

{
  "payment_id": "rp_abc123",
  "external_id": "order_12345",
  "status": "success",
  "amount": 100,
  "currency": "UAH",
  "created_at": "2024-01-15T10:30:00Z",
  "processed_at": "2024-01-15T10:30:05Z",
  "customer": {
    "card_mask": "424242******4242",
    "card_type": "visa"
  }
}

Best Practices

Завжди верифікуйте підпис — це захищає від підроблених запитів
Відповідайте швидко — повертайте 200 OK якомога швидше, обробку робіть асинхронно
Обробляйте дублікати — callback може прийти повторно, використовуйте payment_id для дедуплікації
Логуйте все — зберігайте тіло callback для діагностики