Python SDK Guide

pip install requests

import hashlib
import hmac
import json
import time
import uuid

import requests

BASE_URL = "https://api.vertexY.com/api"


class VertexYClient:
    def __init__(self, company_id: str, access_token: str, webhook_secret: str):
        self.company_id = company_id
        self.access_token = access_token
        self.webhook_secret = webhook_secret
        self.session = requests.Session()
        self.session.headers.update(
            {
                "Authorization": f"Bearer {access_token}",
                "Content-Type": "application/json",
            }
        )

    def assess(self, payload: dict) -> dict:
        response = self.session.post(f"{BASE_URL}/risk-engine/assess", json=payload)
        response.raise_for_status()
        return response.json()

    def submit_feedback(self, payload: dict) -> dict:
        response = self.session.post(f"{BASE_URL}/risk-engine/feedback", json=payload)
        response.raise_for_status()
        return response.json()

    def get_subscription(self) -> dict | None:
        response = self.session.get(f"{BASE_URL}/subscriptions/me")
        response.raise_for_status()
        return response.json()

    def ingest_event(self, event: dict) -> dict:
        payload = {**event, "companyId": self.company_id}
        body = json.dumps(payload, separators=(",", ":"))
        timestamp = str(int(time.time()))
        nonce = str(uuid.uuid4())
        signature = hmac.new(
            self.webhook_secret.encode(),
            body.encode(),
            hashlib.sha256,
        ).hexdigest()

        response = requests.post(
            f"{BASE_URL}/events/ingest",
            data=body,
            headers={
                "Content-Type": "application/json",
                "x-event-signature": signature,
                "x-event-timestamp": timestamp,
                "x-event-nonce": nonce,
            },
        )
        response.raise_for_status()
        return response.json()

import os

client = VertexYClient(
    company_id=os.environ["VERTEXY_COMPANY_ID"],
    access_token=os.environ["VERTEXY_ACCESS_TOKEN"],
    webhook_secret=os.environ["VERTEXY_WEBHOOK_SECRET"],
)

subscription = client.get_subscription()
print(subscription["status"] if subscription else "no subscription")

assessment = client.assess(
    {
        "transactionId": "txn_100001",
        "userId": "user_123",
        "amountMinor": 4999,
        "currency": "USD",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
    }
)

print(assessment["action"])
print(assessment["riskScore"])

client.ingest_event(
    {
        "eventSource": "checkout-service",
        "externalEventId": "evt_100001",
        "idempotencyKey": "evt_100001",
        "userId": "user_123",
        "eventType": "payment_succeeded",
        "timestamp": "2026-04-07T12:00:00.000Z",
        "metadata": {
            "email": "buyer@example.com",
            "ipAddress": "203.0.113.10",
            "deviceId": "device_abc_001",
        },
    }
)