Callbacks

// headers: X-Event-Type / X-Event-Id / X-Request-Attempt /
// X-Login / X-Timestamp / X-Signature-Version: 4 / X-Signature
{
  "id": "19e14b58-...",
  "type": "payment.updated",
  "created_at": "2026-08-03T09:29:46Z",
  "project_id": 1001,
  "data": {
    "customer": { "type": "mobile_phone", "msisdn": "79600000000" },
    "invoice": {
      "invoice_id": "1aa2b436-...",
      "merchant_order_id": "ORDER-001",
      "status": "Processed",
      "payment_status": "PAID",
      "price": { "amount": "99.00", "currency": "RUB", "vat_included": true }
    },
    "transaction": {
      "transaction_id": "B4DA05E2-...",
      "sequence_number": 1,
      "status": "SUCCESS",
      "result_code": 0,
      "result_description": "OK",
      "paid_at": "2026-08-03T09:29:46Z",
      "price": { "amount": "99.00", "currency": "RUB", "vat_included": true }
    },
    "content_required": false
  }
}

// payment.completed (payment.failed on failure)
// headers: X-Event-Type / X-Event-Id / X-Event-Attempt /
// X-Login / X-Timestamp / X-Signature-Version: 3 / X-Signature
{
  "event_type": "payment.completed",
  "event": "payment.completed",
  // deprecated alias of event_type, removed in 3.0.0
  "event_id": "19e14b58-...",
  "occurred_at": "2026-08-03T09:29:46Z",
  "data": {
    "invoice_id": "1aa2b436-...",
    "merchant_order_id": "ORDER-001",
    "status": "Processed",
    "payment_status": "PAID",
    "price": { "amount": "99.00", "currency": "RUB", "vat_included": true },
    "billing_result": "Success",
    "result_code": 0,
    "result_description": "OK",
    // deprecated aliases, removed in 3.0.0
    "amount": "99.00",
    "currency": "RUB"
  }
}

<SendPaymentTransactionRequest>
  <ProjectID>1001</ProjectID>
  <CustomerInfo xsi:type="MobilePhoneCustomer"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <MSISDN>79600000000</MSISDN>
    <OperatorID>42</OperatorID>
  </CustomerInfo>
  <InvoiceInfo>
    <InvoiceID>1624505c-0031-00cf-...</InvoiceID>
    <MerchantOrderID>ORDER-001</MerchantOrderID>
    <InvoiceStatus>Billing</InvoiceStatus>
    <PaymentStatus>PAID</PaymentStatus>
  </InvoiceInfo>
  <PaymentTransactionInfo>
    <TransactionID>B4DA05E2-1D77-40C9-...</TransactionID>
    <PaymentStatus>SUCCESS</PaymentStatus>
    <PaymentResultCode>0</PaymentResultCode>
    <CustomerPriceTotalPaid amount="99.00" currency="RUB"/>
    <BillingInfo><BillingChannel>CPA</BillingChannel></BillingInfo>
  </PaymentTransactionInfo>
</SendPaymentTransactionRequest>

import hashlib, hmac
from datetime import datetime, timezone
 
SECRET = "demo_password"
DRIFT_SECONDS = 20 * 60
 
 
def _hmac(key: str, msg: str) -> str:
    return hmac.new(key.encode(), msg.encode(), hashlib.sha256).hexdigest()
 
 
def callback_is_authentic(headers, my_login: str) -> bool:
    # 1. the sender is who it claims to be
    if headers.get("X-Login") != my_login:
        return False
    if headers.get("X-Signature-Version") != "3":
        return False
 
    # 2. protection against replaying an intercepted request
    ts = headers.get("X-Timestamp", "")
    try:
        sent = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
    except ValueError:
        return False
    if abs((datetime.now(timezone.utc) - sent).total_seconds()) > DRIFT_SECONDS:
        return False
 
    # 3. signature: HMAC(secret, login + HMAC(secret, timestamp))
    expected = _hmac(SECRET, my_login + _hmac(SECRET, ts))
    # constant-time comparison, not ==
    return hmac.compare_digest(expected, headers.get("X-Signature", ""))

import hashlib, hmac
from datetime import datetime, timezone
 
SECRET = "$CALLISTO_PASSWORD"
DRIFT_SECONDS = 20 * 60
 
 
def _hmac(key: str, msg: str) -> str:
    return hmac.new(key.encode(), msg.encode(), hashlib.sha256).hexdigest()
 
 
def callback_is_authentic(headers, my_login: str) -> bool:
    # 1. the sender is who it claims to be
    if headers.get("X-Login") != my_login:
        return False
    if headers.get("X-Signature-Version") != "3":
        return False
 
    # 2. protection against replaying an intercepted request
    ts = headers.get("X-Timestamp", "")
    try:
        sent = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
    except ValueError:
        return False
    if abs((datetime.now(timezone.utc) - sent).total_seconds()) > DRIFT_SECONDS:
        return False
 
    # 3. signature: HMAC(secret, login + HMAC(secret, timestamp))
    expected = _hmac(SECRET, my_login + _hmac(SECRET, ts))
    # constant-time comparison, not ==
    return hmac.compare_digest(expected, headers.get("X-Signature", ""))