Submit Feedback

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#

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#

curl -X POST https://api.getvertexy.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#

curl -X POST https://api.getvertexy.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#

await fetch("https://api.getvertexy.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",
  }),
});