SDK & API

Event Reference

Evidence events are the core data RecurCite uses to build dispute responses. Each event type has specific required fields and an optional stripe_refs object for linking to Stripe objects.

terms.accepted

Customer accepted your terms of service. This is one of the strongest pieces of evidence — it proves the customer agreed to your policies before the transaction.

Field	Type	Required	Description
`version`	string	Yes	Terms version identifier (e.g. "2.0")
`accepted_at`	ISO 8601	Yes	When the customer accepted

json

{
  "type": "terms.accepted",
  "payload": {
    "version": "2.0",
    "accepted_at": "2025-01-15T10:30:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

user.login

Customer logged into your product. Demonstrates active product usage and that the customer had access to their account.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Login timestamp
`ip`	string	No	Client IP address
`user_agent`	string	No	Browser user agent
`device_fingerprint`	string	No	Device fingerprint

json

{
  "type": "user.login",
  "payload": {
    "occurred_at": "2025-01-20T14:22:00Z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

product.used

Customer used a product feature. Quantifies engagement and proves the customer derived value from your service.

Field	Type	Required	Description
`feature_key`	string	Yes	Feature identifier (e.g. "api_calls")
`count`	integer	Yes	Usage count (≥ 1)
`occurred_at`	ISO 8601	Yes	When usage occurred

json

{
  "type": "product.used",
  "payload": {
    "feature_key": "api_calls",
    "count": 150,
    "occurred_at": "2025-01-18T09:00:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123",
    "stripe_subscription_id": "sub_xyz456"
  }
}

cancellation.requested

Customer requested cancellation. Shows you had a proper cancellation flow and the customer was aware of how to cancel.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Request timestamp

json

{
  "type": "cancellation.requested",
  "payload": {
    "occurred_at": "2025-02-01T16:45:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

cancellation.confirmed

Cancellation was confirmed and processed. Proves your cancellation policy was followed.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Confirmation timestamp
`receipt_id`	string	No	Cancellation receipt identifier

json

{
  "type": "cancellation.confirmed",
  "payload": {
    "occurred_at": "2025-02-01T16:50:00Z",
    "receipt_id": "cancel_receipt_789"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

support.ticket.created

Customer opened a support ticket. Shows you provided customer support channels and the customer engaged with them.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Ticket creation timestamp
`ticket_id`	string	No	Your ticket system ID

json

{
  "type": "support.ticket.created",
  "payload": {
    "occurred_at": "2025-01-25T11:00:00Z",
    "ticket_id": "TICKET-1234"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

support.ticket.resolved

Support ticket was resolved. Demonstrates you addressed the customer's concerns before the dispute.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Resolution timestamp
`ticket_id`	string	No	Your ticket system ID

json

{
  "type": "support.ticket.resolved",
  "payload": {
    "occurred_at": "2025-01-25T15:30:00Z",
    "ticket_id": "TICKET-1234"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

transaction.completed

A successful charge was completed. This is the canonical purchase event and is required for Visa Compelling Evidence 3.0 (CE3) eligibility. Session signals (IP, email_sha256, device fingerprint) are hashed and encrypted at rest to enable signal matching against future disputes.

Field	Type	Required	Description
`charge_id`	string	Yes	Stripe charge ID (ch_...)
`amount`	integer	Yes	Charge amount in smallest currency unit (e.g. cents)
`currency`	string	Yes	Three-letter ISO 4217 currency code
`occurred_at`	ISO 8601	Yes	Transaction timestamp
`ip`	string	No	Customer IP address (hashed + encrypted at rest)
`email_sha256`	string	No	SHA-256 hex of lowercase trimmed email
`device_fingerprint`	string	No	Device fingerprint (hashed + encrypted at rest)
`product_description`	string	No	Description of the product or service (strongly recommended)
`merchandise_or_services`	string	No	Product type: "merchandise" or "services" (default: services for SaaS)

json

{
  "type": "transaction.completed",
  "payload": {
    "charge_id": "ch_abc123",
    "amount": 4999,
    "currency": "usd",
    "ip": "203.0.113.42",
    "email_sha256": "a1b2c3d4e5f6...64 hex chars",
    "device_fingerprint": "fp_abc123",
    "product_description": "Pro Plan — Monthly",
    "merchandise_or_services": "services",
    "occurred_at": "2025-06-15T10:30:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

Note

CE3 requires at least 2 prior undisputed transactions within 120–365 days of the disputed charge, with at least one matching signal (IP address or email). Send this event on every successful charge for maximum CE3 coverage.

Stripe references

All events accept an optional stripe_refs object to link evidence to specific Stripe objects. Include as many references as possible — this helps RecurCite match events to disputes automatically.

json

{
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123",
    "stripe_subscription_id": "sub_xyz456",
    "stripe_payment_intent_id": "pi_...",
    "stripe_invoice_id": "in_..."
  }
}

Tip

At minimum, always include stripe_customer_id. This is the primary key RecurCite uses to match evidence to disputes.

Evidence Health

Evidence Health is a score from 0 to 100 that measures how complete your evidence coverage is for a given dispute. A higher score means stronger evidence and better chances of winning.

Score	Grade	Meaning
80–100	A	Excellent — strong evidence across all categories
60–79	B	Good — some evidence gaps but still competitive
40–59	C	Fair — missing key evidence types
0–39	D	Weak — significant evidence gaps

Proof Discount

Maintain an Evidence Health grade of A on 80%+ of disputes to qualify for reduced success fees on Pro and Scale plans. See Pricing & Billing → Proof Discount.

Privacy rules

RecurCite enforces strict data minimization. The API validates all payloads against strict schemas — unknown fields are rejected.

No raw emails — use email_sha256 (SHA-256 hex) instead
No content payloads — only metadata, counters, and timestamps
IP + user_agent — optional, configurable per organization
No sensitive PII — SSNs, credit card numbers, etc. are rejected

Next steps

SDK Installation — set up the SDK and start sending events
Security & Data — learn about encryption, signing, and data handling

API Reference

Next.js Integration