Submit Feedback

Send final outcomes back to VertexY so the risk engine can improve over time.

Why feedback matters

Feedback is how VertexY learns what actually happened after the decision.

Good feedback improves:

  • future risk scores
  • fraud-ring confidence
  • false-positive reduction
  • chargeback detection quality

Endpoint

plaintext
POST /risk-engine/feedback

Supported outcomes

  • approved: the transaction was legitimate and accepted.
  • rejected: your business rejected the transaction.
  • chargeback: the transaction later resulted in a chargeback.
  • confirmed_fraud: your team confirmed the transaction was fraudulent.
  • false_positive: the transaction was flagged but later proved legitimate.

Request by assessment ID

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": "false_positive",
    "falsePositive": true,
    "metadata": {
      "reviewId": "rev_1001",
      "resolution": "customer passed secondary verification"
    }
  }'

Request by transaction ID

bash
curl -X POST https://api.vertexY.com/api/risk-engine/feedback \
  -H "Authorization: Bearer $VERTEXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "txn_100001",
    "outcome": "chargeback",
    "chargeback": true
  }'

Fields reference

The most important fields are:

  • outcome: required. One of the supported outcomes above.
  • assessmentId: recommended. Best option when you have the exact stored assessment.
  • transactionId: optional. Useful when the assessment ID is not available.
  • idempotencyKey: optional but strongly recommended if your workflow might retry.
  • occurredAt: optional timestamp for when the outcome happened.
  • confirmedFraud, chargeback, falsePositive: optional explicit flags that reinforce the outcome.
  • metadata: optional internal context for audits or analyst notes.

Recommended patterns

Immediate operational outcomes

Send feedback quickly for:

  • manual review decisions
  • confirmed fraud investigations
  • customer verification outcomes

Delayed financial outcomes

Send feedback later for:

  • disputes
  • refunds with fraud context
  • chargebacks

Idempotency

If your workflow might retry feedback submission, provide idempotencyKey.

Good examples:

  • chargeback:cb_100001
  • review-resolution:rev_1001

Best practices

  • Prefer assessmentId over transactionId when available.
  • Send false_positive events aggressively. They are critical for tuning.
  • Attach internal metadata that helps with auditability.
  • Keep one canonical outcome event per operational fact.

Example automation

javascript
await fetch('https://api.vertexY.com/api/risk-engine/feedback', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.VERTEXY_ACCESS_TOKEN}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    assessmentId: 'c8acf6d5-8bf4-4b80-a7e5-1b33583c1c23',
    outcome: 'confirmed_fraud',
    confirmedFraud: true,
    idempotencyKey: 'case:fraud:100001',
  }),
});