Callbacks (Webhooks) — RozetkaPay Docs

Огляд

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",
    "mode": "hosted",
    "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"
  }'

Щоб повторити callback конкретної операції, передайте поле operation. Без нього API надсилає callback останньої операції.

Структура callback

Callback містить повну інформацію про платіж. Нижче — повне тіло callback, яке надходить на ваш callback_url. Весь перелік полів — у API Reference.

{
  "id": "rp_abc123",
  "external_id": "order_12345",
  "operation": "payment",
  "is_success": true,
  "action_required": false,
  "details": {
    "payment_id": "563338115268219116",
    "status": "success",
    "status_code": "transaction_successful",
    "status_description": "Transaction successful",
    "amount": "100",
    "currency": "UAH",
    "auth_code": "294956",
    "rrn": "012345678901",
    "created_at": "2024-01-15T10:30:00Z",
    "processed_at": "2024-01-15T10:30:05Z",
    "method": "purchase"
  },
  "customer": {
    "external_id": "user_123",
    "email": "user@example.com",
    "phone": "380501234567"
  },
  "payment_method": {
    "type": "cc_token",
    "cc_token": {
      "token": "tok_2df5e29f-7ace-4e1a-9153-7a95e5d6a503",
      "mask": "424242******4242",
      "payment_system": "VISA",
      "bank_short_name": "ПриватБанк"
    }
  },
  "receipt_url": "https://pay.rozetkapay.com/receipt/rp_abc123"
}