Overview

Understand what VertexY does, how the platform is structured, and where each API fits.

What VertexY is

VertexY is a fraud decisioning platform for payment, account, and order workflows.

You use it in three complementary ways:

  1. Real-time assessment Call POST /risk-engine/assess before a sensitive action to get a score and decision.
  2. Event ingestion Push behavioural and payment lifecycle events to POST /events/ingest so VertexY can build history and graph context.
  3. Outcome feedback Send final outcomes to POST /risk-engine/feedback so the system improves over time.

Core platform objects

  1. Company Your VertexY tenant.
  2. User Your authenticated VertexY user.
  3. Plan The commercial package that controls features and limits.
  4. Subscription Your company’s current billing state.
  5. Assessment A single risk decision for one transaction.
  6. Event A signed historical signal sent to /events/ingest.
  7. Review A manual investigation case tied to an assessment.
  8. Threat intel subscription Your outbound webhook subscription for threat notifications.

Recommended integration model

For most clients, the best rollout path is:

  1. Register your company and store your secrets.
  2. Subscribe to a plan.
  3. Add POST /risk-engine/assess at the transaction decision point.
  4. Start ingesting all supported event types.
  5. Feed confirmed outcomes back into VertexY.
  6. Enable analyst workflows such as reviews, graph explorer, and audit logs if your plan includes them.

Endpoint families

Authentication and setup

  • POST /auth/register-company-admin
  • POST /auth/login
  • POST /auth/refresh
  • POST /auth/logout
  • POST /auth/webhook-secret/regenerate
  • POST /auth/webhook-secret/status

Billing and subscriptions

  • GET /subscriptions/me
  • GET /subscriptions/me/usage

Billing checkout and plan management are handled through the frontend billing experience rather than direct end-user backend API calls.

Risk engine

  • POST /risk-engine/assess
  • POST /risk-engine/feedback
  • GET /risk-engine/evaluations
  • GET /risk-engine/evaluations/:id
  • GET /risk-engine/analytics/*
  • GET /risk-engine/policy
  • PUT /risk-engine/policy

Event ingestion

  • POST /events/ingest

Investigator workflows

  • GET /graph/explore/:id
  • GET /reviews
  • POST /reviews
  • PATCH /reviews/status
  • GET /audit-logs

Threat intelligence

  • POST /threat-intel/subscriptions
  • GET /threat-intel/subscriptions
  • DELETE /threat-intel/subscriptions/:subscriptionId

Authentication model

VertexY uses two authentication modes:

  • Bearer JWT Used by most endpoints.
  • HMAC signature Used by POST /events/ingest.

Read Authentication and Webhook Signature Verification before building your integration.

Plans, limits, and feature gates

Not every endpoint is available on every plan.

Typical gated capabilities include:

  • event explorer
  • graph explorer
  • reviews
  • audit logs
  • threat intelligence

Usage is also limited by plan, especially for the fraud_events_ingested metric.

Decision model at a glance

Every assessment returns:

  • riskScore: numeric score from 0 to 100
  • action: the action your application should apply
  • recommendedAction: the engine’s direct recommendation
  • riskLevel: severity band
  • reasonCodes: machine-readable explanation list

Read Risk Scores Explained for the scoring model.

What VertexY does not do for you

VertexY makes risk decisions and provides tooling around them, but your system still owns:

  • payment authorization
  • final business workflow execution
  • customer notifications
  • dispute operations in your gateway
  • secure storage of your own secrets and customer data

Good production practices

  • Keep refresh tokens server-side, not in public browser storage.
  • Sign every /events/ingest request.
  • Use unique idempotencyKey values for ingest and feedback.
  • Store assessmentId for every decision.
  • Send feedback as soon as the final outcome is known.
  • Ingest all supported event types, not only successful payments.