Event Types

Reference for the event types accepted by POST /events/ingest, including complete example requests for every supported event.

Supported event types

VertexY currently accepts these event types:

  • user_created
  • login_event
  • order_created
  • order_canceled
  • payment_failed
  • payment_succeeded
  • payment_captured
  • refund_requested
  • refund_completed
  • dispute_opened
  • chargeback_received

Common fields on every event

Every event request includes these required fields:

  1. companyId Your company UUID.
  2. eventSource The source system sending the event, such as checkout-service or auth-service.
  3. externalEventId The event ID from your own system.
  4. idempotencyKey A retry-safe unique key for this event.
  5. userId The stable user identifier in your system.
  6. eventType One of the supported event types above.
  7. timestamp The event time in ISO 8601 format.
  8. metadata Event-specific business context.

Optional enrichment fields are also supported:

  • paymentDetails
  • billingAddress
  • shippingAddress
  • cardDetails
  • deviceMeta
  • ipGeo
ℹ️

The examples below are intentionally verbose. Each sample payload includes the full shape for that event so your team can see every supported key in one place.

Common signing helpers

Node.js helper

javascript
import crypto from "crypto";

async function sendVertexYEvent(payload) {
  const rawBody = JSON.stringify(payload);
  const signature = crypto
    .createHmac("sha256", process.env.VERTEXY_WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");

  const response = await fetch("https://api.vertexy.com/api/events/ingest", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-event-signature": signature,
      "x-event-timestamp": String(Math.floor(Date.now() / 1000)),
      "x-event-nonce": crypto.randomUUID(),
    },
    body: rawBody,
  });

  if (!response.ok) {
    throw new Error(`VertexY request failed with ${response.status}`);
  }

  return response.json();
}

Python helper

python
import hashlib
import hmac
import json
import os
import time
import uuid

import requests


def send_vertexy_event(payload: dict) -> dict:
    raw_body = json.dumps(payload, separators=(",", ":"))
    signature = hmac.new(
        os.environ["VERTEXY_WEBHOOK_SECRET"].encode(),
        raw_body.encode(),
        hashlib.sha256,
    ).hexdigest()

    response = requests.post(
        "https://api.vertexy.com/api/events/ingest",
        data=raw_body,
        headers={
            "Content-Type": "application/json",
            "x-event-signature": signature,
            "x-event-timestamp": str(int(time.time())),
            "x-event-nonce": str(uuid.uuid4()),
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Payment and enrichment dictionaries

paymentDetails

Use paymentDetails for payment, refund, dispute, and chargeback events whenever the gateway context is available.

Common keys:

  • methodType
  • provider
  • fingerprint
  • cardLast4
  • cardBin
  • cardNetwork
  • issuer
  • country
  • walletId
  • upiVpa
  • gatewayPaymentId
  • amountMinor
  • currency
  • authStatus
  • captureStatus
  • failureCode
  • failureCategory
  • attemptCount
  • threeDsResult

Enrichment objects

You can attach the following optional objects to any event:

  • billingAddress
  • shippingAddress
  • cardDetails
  • deviceMeta
  • ipGeo

Per-event examples

user_created example requests

Use this event when a new account is created.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "auth-service",
  "externalEventId": "evt_user_created_100001",
  "idempotencyKey": "evt_user_created_100001",
  "userId": "user_123",
  "eventType": "user_created",
  "timestamp": "2026-04-08T10:00:00.000Z",
  "metadata": {
    "email": "buyer@example.com",
    "phone": "+14155550123",
    "deviceId": "device_abc_001",
    "ipAddress": "203.0.113.10",
    "signupChannel": "web",
    "accountStatus": "new",
    "marketingOptIn": true
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "auth-service",
  externalEventId: "evt_user_created_100001",
  idempotencyKey: "evt_user_created_100001",
  userId: "user_123",
  eventType: "user_created",
  timestamp: "2026-04-08T10:00:00.000Z",
  metadata: {
    email: "buyer@example.com",
    phone: "+14155550123",
    deviceId: "device_abc_001",
    ipAddress: "203.0.113.10",
    signupChannel: "web",
    accountStatus: "new",
    marketingOptIn: true,
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "auth-service",
    "externalEventId": "evt_user_created_100001",
    "idempotencyKey": "evt_user_created_100001",
    "userId": "user_123",
    "eventType": "user_created",
    "timestamp": "2026-04-08T10:00:00.000Z",
    "metadata": {
        "email": "buyer@example.com",
        "phone": "+14155550123",
        "deviceId": "device_abc_001",
        "ipAddress": "203.0.113.10",
        "signupChannel": "web",
        "accountStatus": "new",
        "marketingOptIn": True,
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
login_event example requests

Use this event for successful or failed login attempts.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "auth-service",
  "externalEventId": "evt_login_100001",
  "idempotencyKey": "evt_login_100001",
  "userId": "user_123",
  "eventType": "login_event",
  "timestamp": "2026-04-08T10:05:00.000Z",
  "metadata": {
    "email": "buyer@example.com",
    "deviceId": "device_abc_001",
    "ipAddress": "203.0.113.10",
    "loginOutcome": "failed",
    "failureReason": "bad_password",
    "sessionId": "sess_100001"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "auth-service",
  externalEventId: "evt_login_100001",
  idempotencyKey: "evt_login_100001",
  userId: "user_123",
  eventType: "login_event",
  timestamp: "2026-04-08T10:05:00.000Z",
  metadata: {
    email: "buyer@example.com",
    deviceId: "device_abc_001",
    ipAddress: "203.0.113.10",
    loginOutcome: "failed",
    failureReason: "bad_password",
    sessionId: "sess_100001",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "auth-service",
    "externalEventId": "evt_login_100001",
    "idempotencyKey": "evt_login_100001",
    "userId": "user_123",
    "eventType": "login_event",
    "timestamp": "2026-04-08T10:05:00.000Z",
    "metadata": {
        "email": "buyer@example.com",
        "deviceId": "device_abc_001",
        "ipAddress": "203.0.113.10",
        "loginOutcome": "failed",
        "failureReason": "bad_password",
        "sessionId": "sess_100001",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
order_created example requests

Use this event when an order is created before payment finalization.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "checkout-service",
  "externalEventId": "evt_order_created_100001",
  "idempotencyKey": "evt_order_created_100001",
  "userId": "user_123",
  "eventType": "order_created",
  "timestamp": "2026-04-08T10:10:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceId": "device_abc_001",
    "amountMinor": 4999,
    "currency": "USD",
    "itemsCount": 2
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "checkout-service",
  externalEventId: "evt_order_created_100001",
  idempotencyKey: "evt_order_created_100001",
  userId: "user_123",
  eventType: "order_created",
  timestamp: "2026-04-08T10:10:00.000Z",
  metadata: {
    orderId: "order_100001",
    email: "buyer@example.com",
    ipAddress: "203.0.113.10",
    deviceId: "device_abc_001",
    amountMinor: 4999,
    currency: "USD",
    itemsCount: 2,
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "checkout-service",
    "externalEventId": "evt_order_created_100001",
    "idempotencyKey": "evt_order_created_100001",
    "userId": "user_123",
    "eventType": "order_created",
    "timestamp": "2026-04-08T10:10:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
        "deviceId": "device_abc_001",
        "amountMinor": 4999,
        "currency": "USD",
        "itemsCount": 2,
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
order_canceled example requests

Use this event when an order is canceled.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "checkout-service",
  "externalEventId": "evt_order_canceled_100001",
  "idempotencyKey": "evt_order_canceled_100001",
  "userId": "user_123",
  "eventType": "order_canceled",
  "timestamp": "2026-04-08T10:15:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "cancelReason": "customer_changed_mind",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceId": "device_abc_001"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "checkout-service",
  externalEventId: "evt_order_canceled_100001",
  idempotencyKey: "evt_order_canceled_100001",
  userId: "user_123",
  eventType: "order_canceled",
  timestamp: "2026-04-08T10:15:00.000Z",
  metadata: {
    orderId: "order_100001",
    cancelReason: "customer_changed_mind",
    email: "buyer@example.com",
    ipAddress: "203.0.113.10",
    deviceId: "device_abc_001",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "checkout-service",
    "externalEventId": "evt_order_canceled_100001",
    "idempotencyKey": "evt_order_canceled_100001",
    "userId": "user_123",
    "eventType": "order_canceled",
    "timestamp": "2026-04-08T10:15:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "cancelReason": "customer_changed_mind",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
        "deviceId": "device_abc_001",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
payment_failed example requests

Use this event for failed authorization or failed checkout attempts.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_payment_failed_100001",
  "idempotencyKey": "evt_payment_failed_100001",
  "userId": "user_123",
  "eventType": "payment_failed",
  "timestamp": "2026-04-08T10:20:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceId": "device_abc_001",
    "attemptLabel": "retry_2"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "failed",
    "captureStatus": "not_applicable",
    "failureCode": "do_not_honor",
    "failureCategory": "suspected_fraud",
    "attemptCount": 2,
    "threeDsResult": "failed"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_payment_failed_100001",
  idempotencyKey: "evt_payment_failed_100001",
  userId: "user_123",
  eventType: "payment_failed",
  timestamp: "2026-04-08T10:20:00.000Z",
  metadata: {
    orderId: "order_100001",
    email: "buyer@example.com",
    ipAddress: "203.0.113.10",
    deviceId: "device_abc_001",
    attemptLabel: "retry_2",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "failed",
    captureStatus: "not_applicable",
    failureCode: "do_not_honor",
    failureCategory: "suspected_fraud",
    attemptCount: 2,
    threeDsResult: "failed",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_payment_failed_100001",
    "idempotencyKey": "evt_payment_failed_100001",
    "userId": "user_123",
    "eventType": "payment_failed",
    "timestamp": "2026-04-08T10:20:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
        "deviceId": "device_abc_001",
        "attemptLabel": "retry_2",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "failed",
        "captureStatus": "not_applicable",
        "failureCode": "do_not_honor",
        "failureCategory": "suspected_fraud",
        "attemptCount": 2,
        "threeDsResult": "failed",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
payment_succeeded example requests

Use this event when a payment authorization succeeds.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_payment_succeeded_100001",
  "idempotencyKey": "evt_payment_succeeded_100001",
  "userId": "user_123",
  "eventType": "payment_succeeded",
  "timestamp": "2026-04-08T10:25:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceId": "device_abc_001",
    "attemptLabel": "primary"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "pending",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_payment_succeeded_100001",
  idempotencyKey: "evt_payment_succeeded_100001",
  userId: "user_123",
  eventType: "payment_succeeded",
  timestamp: "2026-04-08T10:25:00.000Z",
  metadata: {
    orderId: "order_100001",
    email: "buyer@example.com",
    ipAddress: "203.0.113.10",
    deviceId: "device_abc_001",
    attemptLabel: "primary",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "pending",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_payment_succeeded_100001",
    "idempotencyKey": "evt_payment_succeeded_100001",
    "userId": "user_123",
    "eventType": "payment_succeeded",
    "timestamp": "2026-04-08T10:25:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
        "deviceId": "device_abc_001",
        "attemptLabel": "primary",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "pending",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
payment_captured example requests

Use this event when an authorized payment is captured.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_payment_captured_100001",
  "idempotencyKey": "evt_payment_captured_100001",
  "userId": "user_123",
  "eventType": "payment_captured",
  "timestamp": "2026-04-08T10:30:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "captureChannel": "auto_capture",
    "email": "buyer@example.com",
    "ipAddress": "203.0.113.10",
    "deviceId": "device_abc_001"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "captured",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_payment_captured_100001",
  idempotencyKey: "evt_payment_captured_100001",
  userId: "user_123",
  eventType: "payment_captured",
  timestamp: "2026-04-08T10:30:00.000Z",
  metadata: {
    orderId: "order_100001",
    captureChannel: "auto_capture",
    email: "buyer@example.com",
    ipAddress: "203.0.113.10",
    deviceId: "device_abc_001",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "captured",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_payment_captured_100001",
    "idempotencyKey": "evt_payment_captured_100001",
    "userId": "user_123",
    "eventType": "payment_captured",
    "timestamp": "2026-04-08T10:30:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "captureChannel": "auto_capture",
        "email": "buyer@example.com",
        "ipAddress": "203.0.113.10",
        "deviceId": "device_abc_001",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "captured",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
refund_requested example requests

Use this event as soon as a refund starts.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_refund_requested_100001",
  "idempotencyKey": "evt_refund_requested_100001",
  "userId": "user_123",
  "eventType": "refund_requested",
  "timestamp": "2026-04-08T10:35:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "refundReason": "customer_request",
    "requestedBy": "support_agent",
    "refundId": "refund_100001"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "captured",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_refund_requested_100001",
  idempotencyKey: "evt_refund_requested_100001",
  userId: "user_123",
  eventType: "refund_requested",
  timestamp: "2026-04-08T10:35:00.000Z",
  metadata: {
    orderId: "order_100001",
    refundReason: "customer_request",
    requestedBy: "support_agent",
    refundId: "refund_100001",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "captured",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_refund_requested_100001",
    "idempotencyKey": "evt_refund_requested_100001",
    "userId": "user_123",
    "eventType": "refund_requested",
    "timestamp": "2026-04-08T10:35:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "refundReason": "customer_request",
        "requestedBy": "support_agent",
        "refundId": "refund_100001",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "captured",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
refund_completed example requests

Use this event when the refund is fully completed.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_refund_completed_100001",
  "idempotencyKey": "evt_refund_completed_100001",
  "userId": "user_123",
  "eventType": "refund_completed",
  "timestamp": "2026-04-08T10:40:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "refundId": "refund_100001",
    "refundReason": "customer_request",
    "completedBy": "payments_worker"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "captured",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_refund_completed_100001",
  idempotencyKey: "evt_refund_completed_100001",
  userId: "user_123",
  eventType: "refund_completed",
  timestamp: "2026-04-08T10:40:00.000Z",
  metadata: {
    orderId: "order_100001",
    refundId: "refund_100001",
    refundReason: "customer_request",
    completedBy: "payments_worker",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "captured",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_refund_completed_100001",
    "idempotencyKey": "evt_refund_completed_100001",
    "userId": "user_123",
    "eventType": "refund_completed",
    "timestamp": "2026-04-08T10:40:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "refundId": "refund_100001",
        "refundReason": "customer_request",
        "completedBy": "payments_worker",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "captured",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
dispute_opened example requests

Use this event as soon as your payment provider opens a dispute.

ℹ️

dispute_opened is a strong risk signal. Send it as quickly as possible.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_dispute_opened_100001",
  "idempotencyKey": "evt_dispute_opened_100001",
  "userId": "user_123",
  "eventType": "dispute_opened",
  "timestamp": "2026-04-08T10:45:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "disputeId": "dp_100001",
    "reason": "fraudulent",
    "stage": "opened"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "captured",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_dispute_opened_100001",
  idempotencyKey: "evt_dispute_opened_100001",
  userId: "user_123",
  eventType: "dispute_opened",
  timestamp: "2026-04-08T10:45:00.000Z",
  metadata: {
    orderId: "order_100001",
    disputeId: "dp_100001",
    reason: "fraudulent",
    stage: "opened",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "captured",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_dispute_opened_100001",
    "idempotencyKey": "evt_dispute_opened_100001",
    "userId": "user_123",
    "eventType": "dispute_opened",
    "timestamp": "2026-04-08T10:45:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "disputeId": "dp_100001",
        "reason": "fraudulent",
        "stage": "opened",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "captured",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)
chargeback_received example requests

Use this event when a chargeback is confirmed.

⚠️

When you receive a chargeback, also send POST /risk-engine/feedback with outcome: "chargeback" if you know the related assessment.

bash
ts=$(date +%s)
nonce=$(uuidgen)
body='{
  "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "eventSource": "payments-service",
  "externalEventId": "evt_chargeback_received_100001",
  "idempotencyKey": "evt_chargeback_received_100001",
  "userId": "user_123",
  "eventType": "chargeback_received",
  "timestamp": "2026-04-08T10:50:00.000Z",
  "metadata": {
    "orderId": "order_100001",
    "chargebackId": "cb_100001",
    "reason": "fraudulent",
    "stage": "received"
  },
  "paymentDetails": {
    "methodType": "card",
    "provider": "Stripe",
    "fingerprint": "pm_hash_001",
    "cardLast4": "1111",
    "cardBin": "411111",
    "cardNetwork": "visa",
    "issuer": "Chase",
    "country": "US",
    "walletId": "wallet_001",
    "upiVpa": "alice@upi",
    "gatewayPaymentId": "pay_100001",
    "amountMinor": 4999,
    "currency": "USD",
    "authStatus": "authorized",
    "captureStatus": "captured",
    "failureCode": "none",
    "failureCategory": "unknown",
    "attemptCount": 1,
    "threeDsResult": "authenticated"
  },
  "billingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "shippingAddress": {
    "country": "US",
    "postalCode": "10001",
    "city": "New York"
  },
  "cardDetails": {
    "bin": "411111",
    "last4": "1111",
    "network": "visa",
    "issuingCountry": "US",
    "cardType": "credit"
  },
  "deviceMeta": {
    "os": "iOS",
    "browser": "Mobile Safari",
    "language": "en-US",
    "timezone": "America/New_York"
  },
  "ipGeo": {
    "country": "US",
    "region": "NY",
    "city": "New York",
    "lat": 40.7128,
    "lon": -74.0060
  }
}'
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"
javascript
const payload = {
  companyId: "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  eventSource: "payments-service",
  externalEventId: "evt_chargeback_received_100001",
  idempotencyKey: "evt_chargeback_received_100001",
  userId: "user_123",
  eventType: "chargeback_received",
  timestamp: "2026-04-08T10:50:00.000Z",
  metadata: {
    orderId: "order_100001",
    chargebackId: "cb_100001",
    reason: "fraudulent",
    stage: "received",
  },
  paymentDetails: {
    methodType: "card",
    provider: "Stripe",
    fingerprint: "pm_hash_001",
    cardLast4: "1111",
    cardBin: "411111",
    cardNetwork: "visa",
    issuer: "Chase",
    country: "US",
    walletId: "wallet_001",
    upiVpa: "alice@upi",
    gatewayPaymentId: "pay_100001",
    amountMinor: 4999,
    currency: "USD",
    authStatus: "authorized",
    captureStatus: "captured",
    failureCode: "none",
    failureCategory: "unknown",
    attemptCount: 1,
    threeDsResult: "authenticated",
  },
  billingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  shippingAddress: {
    country: "US",
    postalCode: "10001",
    city: "New York",
  },
  cardDetails: {
    bin: "411111",
    last4: "1111",
    network: "visa",
    issuingCountry: "US",
    cardType: "credit",
  },
  deviceMeta: {
    os: "iOS",
    browser: "Mobile Safari",
    language: "en-US",
    timezone: "America/New_York",
  },
  ipGeo: {
    country: "US",
    region: "NY",
    city: "New York",
    lat: 40.7128,
    lon: -74.006,
  },
};

const response = await sendVertexYEvent(payload);
console.log(response);
python
payload = {
    "companyId": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "eventSource": "payments-service",
    "externalEventId": "evt_chargeback_received_100001",
    "idempotencyKey": "evt_chargeback_received_100001",
    "userId": "user_123",
    "eventType": "chargeback_received",
    "timestamp": "2026-04-08T10:50:00.000Z",
    "metadata": {
        "orderId": "order_100001",
        "chargebackId": "cb_100001",
        "reason": "fraudulent",
        "stage": "received",
    },
    "paymentDetails": {
        "methodType": "card",
        "provider": "Stripe",
        "fingerprint": "pm_hash_001",
        "cardLast4": "1111",
        "cardBin": "411111",
        "cardNetwork": "visa",
        "issuer": "Chase",
        "country": "US",
        "walletId": "wallet_001",
        "upiVpa": "alice@upi",
        "gatewayPaymentId": "pay_100001",
        "amountMinor": 4999,
        "currency": "USD",
        "authStatus": "authorized",
        "captureStatus": "captured",
        "failureCode": "none",
        "failureCategory": "unknown",
        "attemptCount": 1,
        "threeDsResult": "authenticated",
    },
    "billingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "shippingAddress": {
        "country": "US",
        "postalCode": "10001",
        "city": "New York",
    },
    "cardDetails": {
        "bin": "411111",
        "last4": "1111",
        "network": "visa",
        "issuingCountry": "US",
        "cardType": "credit",
    },
    "deviceMeta": {
        "os": "iOS",
        "browser": "Mobile Safari",
        "language": "en-US",
        "timezone": "America/New_York",
    },
    "ipGeo": {
        "country": "US",
        "region": "NY",
        "city": "New York",
        "lat": 40.7128,
        "lon": -74.0060,
    },
}

response = send_vertexy_event(payload)
print(response)

Best practices

  • Make externalEventId and idempotencyKey stable.
  • Reuse userId consistently across all event types.
  • Include email, ipAddress, and deviceId in metadata whenever available.
  • Attach paymentDetails to all payment-related events.
  • Include chargebacks and disputes, not only successful payments.
  • Send chargeback_received and dispute_opened as soon as your payment provider exposes them.