Quickstart

Go from zero to a working VertexY integration in a few steps.

ℹ️

This quickstart covers the fastest path to value: register, authenticate, assess one transaction, and start ingesting events.

What you need

  • A backend service that can call HTTPS endpoints
  • A safe place to store secrets
  • A company admin account in VertexY

The VertexY base URL is:

plaintext
https://api.vertexY.com/api

Step 1: Register your company

Create your company and first admin user.

bash
curl -X POST https://api.vertexY.com/api/auth/register-company-admin \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Corp",
    "companySlug": "acme-corp",
    "email": "fraud-admin@acme.com",
    "password": "Sup3rSecurePass!"
  }'

Example response:

json
{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "userId": "11f8bc0b-3fd8-4a2d-b52d-42ec7bce6e9a",
  "webhookSigningSecret": "whs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "secretPrefix": "whs_live_"
}
⚠️

Save webhookSigningSecret immediately. It is only returned when created or rotated.

Step 2: Save your credentials

At minimum, store these values:

  1. VERTEXY_COMPANY_ID Your company UUID.
  2. VERTEXY_WEBHOOK_SECRET Secret used to sign /events/ingest requests.
  3. VERTEXY_ADMIN_EMAIL Your VertexY admin email.
  4. VERTEXY_ADMIN_PASSWORD Your VertexY admin password.

Example:

bash
export VERTEXY_COMPANY_ID="a1b2c3d4-e5f6-4789-abcd-ef1234567890"
export VERTEXY_WEBHOOK_SECRET="whs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export VERTEXY_ADMIN_EMAIL="fraud-admin@acme.com"
export VERTEXY_ADMIN_PASSWORD="Sup3rSecurePass!"

Step 3: Log in

Use your companyId, email, and password to get an access token and refresh token.

bash
curl -X POST https://api.vertexY.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d "{
    \"companyId\": \"$VERTEXY_COMPANY_ID\",
    \"email\": \"$VERTEXY_ADMIN_EMAIL\",
    \"password\": \"$VERTEXY_ADMIN_PASSWORD\"
  }"

Example response:

json
{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "subscriptionStatus": "none",
  "planCode": null,
  "planFeatures": []
}

Use accessToken in:

plaintext
Authorization: Bearer <accessToken>

Example:

bash
export VERTEXY_ACCESS_TOKEN="eyJhbGciOi..."
export VERTEXY_REFRESH_TOKEN="eyJhbGciOi..."

Step 4: Choose a plan in the frontend

Plan selection and checkout are initiated from the VertexY frontend experience, not by calling backend billing endpoints directly.

Use the frontend billing UI to:

  • review the available plans
  • start checkout
  • manage upgrades or cancellations

If you are embedding billing into your own product, route users through your frontend or backend-for-frontend layer rather than calling checkout APIs directly from public clients.

Step 5: Assess a transaction

Call POST /risk-engine/assess before approving a payment or order.

bash
curl -X POST https://api.vertexY.com/api/risk-engine/assess \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_100001",
    "userId": "user_123",
    "amountMinor": 4999,
    "currency": "USD",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceFingerprint": "device_abc_001",
    "phoneNumber": "+14155550123",
    "paymentMethodHash": "pm_hash_001",
    "shippingAddressHash": "addr_hash_001",
    "metadata": {
      "orderId": "order_100001",
      "channel": "web"
    }
  }'

Example response:

json
{
  "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
  "riskScore": 23,
  "action": "allow",
  "recommendedAction": "allow",
  "policyMode": "hybrid",
  "riskLevel": "low",
  "reasonCodes": [],
  "featureContributions": {
    "velocity_zscore": 0,
    "indicator_overlap_ratio": 0
  },
  "engineVersion": "v2",
  "latencyMs": 41
}

Step 6: Start ingesting events

Assessments give you real-time scoring. Event ingestion gives VertexY history, velocity, graph links, and better future decisions.

Signed ingest example:

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "'"$VERTEXY_COMPANY_ID"'",
  "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",
    "orderId": "order_100001"
  },
  "paymentDetails": {
    "methodType": "card",
    "gatewayPaymentId": "pay_100001",
    "fingerprint": "pm_hash_001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized"
  }
}'
sig=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$VERTEXY_WEBHOOK_SECRET" -hex | sed 's/^.* //')

curl -X POST https://api.vertexY.com/api/events/ingest \
  -H "Content-Type: application/json" \
  -H "x-event-signature: $sig" \
  -H "x-event-timestamp: $ts" \
  -H "x-event-nonce: $nonce" \
  -d "$body"

Step 7: Close the loop with feedback

When you know the outcome, send it back.

bash
curl -X POST https://api.vertexY.com/api/risk-engine/feedback \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assessmentId": "c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23",
    "outcome": "approved"
  }'

Recommended next reading