Skip to content

Developers

The Connect API: feed evidence from anything.

Send your first order in 5 minutes with curl, no SDK needed. It's a small REST API for orders and activity, signed evidence requests and dispute webhooks, and our WooCommerce plugin runs on it.

Quickstart

Three curl commands take you from nothing to data flowing. Each step works on its own, so stop wherever you like: what you've sent keeps working for you. On WooCommerce? Install the plugin and click Connect instead; it does this for you.

  1. Get a token

    1 min

    Sign up (no card, and no processor needed yet). Open Sources, pick the Custom app / API tab, name your source and click Create source. Leave the URLs empty for now.

    Copy the API token (dg_live_…) and signing secret (whsec_…). They're shown once; if you lose them, rotate from the source's menu, which replaces both at once; the old ones stop working immediately. A 401 means the token is wrong or was rotated.

    Token and check
    export DISPUTEGUARD_TOKEN=dg_live_...
    
    # Check it works: you get your source back
    curl https://app.disputeguard.com/api/v1/source \
      -H "Authorization: Bearer $DISPUTEGUARD_TOKEN" \
      -H "Accept: application/json"
  2. Send an order

    2 min

    Open Orders in the dashboard and order 1001 is there. Only four fields are required: external_id (your id), amount (in cents), currency and placed_at.

    Put every processor id you have in payment: that is how a dispute finds its order. Without one, we fall back to the customer's email and the amount, which is weaker.

    Send the same order again whenever it changes. It's an upsert on external_id.

    Send an order
    curl -X POST https://app.disputeguard.com/api/v1/orders \
      -H "Authorization: Bearer $DISPUTEGUARD_TOKEN" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{
        "external_id": "1001",
        "amount": 4999,
        "currency": "usd",
        "placed_at": "2026-11-18T14:03:00Z",
        "customer": { "email": "[email protected]", "ip": "203.0.113.7" },
        "payment": { "processor": "stripe", "payment_intent_id": "pi_3PqX..." }
      }'
  3. Send an event

    1 min

    Events are the evidence: what the customer did and what you did for them. The idempotency_key makes retries safe, so a second run reports a duplicate and adds nothing.

    The shipment now shows on order 1001's timeline.

    Send an event
    curl -X POST https://app.disputeguard.com/api/v1/events \
      -H "Authorization: Bearer $DISPUTEGUARD_TOKEN" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{
        "events": [{
          "type": "fulfillment.shipped",
          "occurred_at": "2026-11-18T16:00:00Z",
          "order_external_id": "1001",
          "idempotency_key": "ship-1001",
          "data": { "carrier": "ups", "tracking_number": "1Z999AA10123456784" }
        }]
      }'
    
    # {"created":1,"duplicates":0}
    # Run it again: {"created":0,"duplicates":1}

You're connected.

From here, every order you send is matched the moment a dispute arrives for it.

Then go further

  1. Wire it into your app

    15 min

    Put the calls from steps 2 and 3 where these things already happen in your code. Pick the rows that fit your business.

    When this happens, send this
    When this happens
    Checkout completes The order with its processor ids, plus checkout.completed with IP, user agent and terms_accepted
    Payment is captured, shipped, refunded The order again (it is an upsert)
    You ship, it is delivered fulfillment.shipped, fulfillment.delivered
    Customer signs in customer.login with IP and device id (link by customer_email, no order needed)
    Customer downloads or uses what they bought download.accessed, service.accessed, usage.recorded
    A support message goes either way communication.message
    A subscription renews or is cancelled subscription.renewed, subscription.cancelled

    Backfill your recent orders once so disputes on past charges match too: disputes can arrive weeks or months after the charge, and POST /orders/batch takes 100 orders a call. The SDK examples under Pushing orders & events wrap auth, retries and batching, and every event type is listed in the vocabulary.

  2. Test evidence callbacks

    10 min

    Some evidence is easier to fetch when you need it. Set a callback URL on your source (Sources, then Edit) and we POST a signed evidence.requested there when a dispute lands. Build the handler under Runtime evidence callbacks, then send it a correctly signed request from your terminal.

    You should see 200 and your evidence JSON. Change one character of SECRET and you get 400: the handler checked the signature.

    Signed test request
    SECRET=whsec_...   # your source's signing secret
    BODY='{"id":"evt_test","type":"evidence.requested","created_at":"2026-11-18T12:00:00Z","data":{"dispute":{"id":"dp_test","reason":"fraudulent","amount":4999,"currency":"usd"},"order":{"external_id":"1001"},"requested":["shipping"]}}'
    T=$(date +%s)
    SIG=$(printf '%s' "$T.$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
    curl -i http://localhost:3000/disputeguard/evidence \
      -H "Content-Type: application/json" \
      -H "X-DisputeGuard-Event: evidence.requested" \
      -H "X-DisputeGuard-Signature: t=$T,v1=$SIG" \
      -d "$BODY"
  3. Fight a Stripe test dispute

    10 min

    See the whole loop with no real money and no real customer.

    1. Under Connections, Stripe, paste a test key (sk_test_… or rk_test_…). The connection shows Test mode.
    2. Create a payment with Stripe's test card pm_card_createDispute. It is disputed as fraudulent seconds after it's charged. Copy the pi_… id from the response.
    3. Send the order from step 2 with that id as payment.payment_intent_id, and the shipment from step 3. Order doesn't matter: an order that arrives after its dispute is linked to it.
    4. Open Disputes. It's matched to your order, with an evidence packet built from what you sent, a strength score and what's still missing.
    Create a disputed payment
    curl https://api.stripe.com/v1/payment_intents -u "sk_test_...:" \
      -d amount=4999 -d currency=usd -d "payment_method_types[]=card" \
      -d payment_method=pm_card_createDispute -d confirm=true

When something's wrong

Common API errors and what they mean
You getIt means
401Token missing, mistyped or rotated. Check the Authorization: Bearer header.
403The source was disconnected. Reconnect it, or create a new one, under Sources.
422A field is wrong; errors names it, for example "amount": ["The amount field is required."]. Batches are all-or-nothing.
429Over 600 requests a minute. Wait Retry-After seconds (the SDKs do this).
A dispute with no orderNo processor id matched. Send the order with its payment_intent_id or charge_id; it links on arrival.

There is one token type (dg_live_…) for now; use a separate source for staging so test data stays apart. Running locally or self-hosting: the base URL is {APP_URL}/api/v1.

Overview

A source is anywhere evidence lives: a store, a SaaS app, a CRM. Each source authenticates with its own token and can expose a callback URL. Base URL: https://app.disputeguard.com/api/v1

  • You → DisputeGuard

    Push evidence ahead of time

    Upsert orders with their processor identifiers and append activity events as they happen.

  • DisputeGuard → you

    Answer evidence requests

    When a dispute lands we POST a signed evidence.requested to your callback URL. Reply with anything extra.

  • DisputeGuard → you

    React to dispute webhooks

    Subscribe endpoints to dispute.* and evidence.* events to drive your own workflows.

Authentication

Every request carries a source token: Authorization: Bearer dg_live_…. A token belongs to exactly one source, and a source to exactly one account. Create one in the dashboard under Sources; the quickstart shows how.

Building a plugin or app that other merchants install? Use the connect handshake: send the merchant to /connect/{platform}, receive a one-time code on your return URL, and exchange it for a token and signing secret. Codes are single-use and expire after 10 minutes.

  • JSON bodies; multipart for files
  • Money in integer minor units + ISO currency
  • Timestamps ISO-8601, returned in UTC
  • 600 req/min per token; 429 with Retry-After

Pushing orders & events

Send an order when it's placed and again whenever something material changes (paid, shipped, refunded). Upserts are idempotent and omitted fields are left untouched. Events reference an order by order_external_id or just a customer_email; add an idempotency_key to make retries safe.

import { DisputeGuard, Event } from '@disputeguard/node'

const dg = new DisputeGuard(process.env.DISPUTEGUARD_TOKEN!)

// Ahead of time: upsert the order with its processor identifiers
await dg.orders.upsert({
  external_id: '1042',
  amount: 4999, // minor units
  currency: 'usd',
  placed_at: new Date(),
  customer: { email: '[email protected]', ip: '203.0.113.7' },
  payment: {
    processor: 'stripe',
    payment_intent_id: 'pi_3PqX...',
    cvc_check: 'pass',
    three_d_secure: 'authenticated',
  },
})

// ...then append activity as it happens
await dg.events.create(
  Event.shipped('ups', '1Z999AA10123456784')
    .forOrder('1042')
    .idempotencyKey('ship-1042'),
)

Endpoints

Connect API endpoints
Endpoint
POST/ordersCreate or update an order, keyed by your external_id
POST/orders/batchUpsert up to 100 orders
GET/orders/{external_id}Retrieve an order by your ID
POST/eventsAppend up to 100 activity events
GET/disputesList disputes, newest first
POST/disputes/{id}/evidencePush evidence for a dispute (async callback answer)
POST/disputes/{id}/filesAttach a PDF, PNG or JPEG (≤ 4 MB)
POST/webhook-endpointsRegister an outbound webhook endpoint

Payment identifiers (critical for matching)

Include every identifier you know in order.payment, plus the risk signals you have: AVS, CVC, 3D Secure, card brand and last 4, wallet.

Payment identifier fields
FieldExample
processorstripe
charge_idch_3P…
payment_intent_idpi_3P…
transaction_id8AB12345CD678901E
customer_idcus_…

Event vocabulary

Event types are dotted strings. Every event has occurred_at and can carry ip, user_agent and device_id. Unknown types are kept on the timeline but not used by playbooks.

  • checkout.completed

    Strengthens: fraud, unrecognized

  • checkout.terms_accepted

    Strengthens: subscription, credit, not as described

  • payment.authorized

    Strengthens: fraud

  • customer.account_created

    Strengthens: fraud

  • customer.login

    Strengthens: fraud, unrecognized

  • fulfillment.shipped

    Strengthens: not received

  • fulfillment.delivered

    Strengthens: not received, fraud

  • download.accessed

    Strengthens: not received (digital), fraud

  • service.accessed

    Strengthens: not received (services), subscription

  • usage.recorded

    Strengthens: subscription, not as described

  • communication.message

    Strengthens: all reasons

  • refund.issued

    Strengthens: credit not processed, duplicate

  • refund.declined

    Strengthens: credit not processed

  • subscription.renewed

    Strengthens: subscription

  • subscription.cancelled

    Strengthens: subscription

  • policy.acknowledged

    Strengthens: subscription, credit, not as described

  • order.note

    Strengthens: general

Runtime evidence callbacks

When a dispute arrives, DisputeGuard POSTs a signed evidence.requested event to every active source with a callback URL. If no order was matched, data.order is null and your source can look it up from the payment identifiers or customer email. Respond within 20 seconds.

Request body
{
  "id": "01j9zq4m8k2v7c3t5r6y1x0w9e",
  "type": "evidence.requested",
  "created_at": "2026-09-30T12:00:00Z",
  "data": {
    "dispute": {
      "id": "01j9zq3b1n5f6g7h8j9k0m1p2q",
      "reason": "fraudulent",
      "status": "needs_response",
      "amount": 4999,
      "currency": "usd",
      "evidence_due_by": "2026-10-10T23:59:59Z",
      "processor": "stripe",
      "payment_intent_id": "pi_3PqX..."
    },
    "order": { "external_id": "1042", "order_number": "1042" },
    "requested": ["shipping", "customer_history", "activity", "policies", "communications"]
  }
}

Your response

  • 200Evidence in the body, used immediately.
  • 202Accepted; you’ll push evidence later via POST /disputes/{id}/evidence.
  • 404You have no data for this dispute. Not an error.
  • otherRetried with backoff: 1m, 5m, 30m, 2h, 6h, then marked failed.

An evidence response can include an order, events, text fields, prior_transactions for Visa CE 3.0, and base64 files.

import express from 'express'
import { createEvidenceRequestHandler, Evidence, Event } from '@disputeguard/node'

const app = express()

// Raw body: the HMAC is computed over the exact bytes we sent.
// The handler verifies the signature (and timestamp) before your callback runs.
app.post(
  '/disputeguard/evidence',
  express.raw({ type: 'application/json' }),
  createEvidenceRequestHandler(process.env.DISPUTEGUARD_SIGNING_SECRET!, async (req) => {
    const order = req.orderExternalId
      ? await db.orders.find(req.orderExternalId)
      : await db.orders.findByStripe(req.chargeId, req.paymentIntentId)
    if (!order) return null // 404: no data for this dispute

    return Evidence.make() // 200 + evidence
      .events(order.logins.map((l) => Event.login().forCustomer(order.email).ip(l.ip).at(l.at)))
      .field('product_description', order.description)
      .priorTransaction({ order_external_id: '998', charge_id: 'ch_prev',
        placed_at: '2026-03-01T10:00:00Z', amount: 4999, currency: 'usd' })
  }),
)

Signatures

Every request DisputeGuard sends (runtime callbacks and outbound webhooks) is signed with your source's or endpoint's signing secret (whsec_…, shown once) using HMAC-SHA256.

  1. Compute the HMAC over {t}.{raw_body}: the raw bytes, not re-serialised JSON.
  2. Compare against each v1= value in constant time.
  3. Reject if the timestamp is more than 300 seconds from now.
  4. DisputeGuard sends one v1= value today. Accept the request if any value matches, so your verifier keeps working if that changes.

Both SDKs ship a verification helper that does all four.

X-DisputeGuard-Signature
X-DisputeGuard-Signature: t=1727712000,v1=5f2b...

# v1 = hex( HMAC_SHA256( signing_secret, "{t}.{raw_body}" ) )
# Reject if |now - t| > 300 seconds. Compare in constant time.
# DisputeGuard sends one v1= value; accepting any match keeps verifiers future-proof.

Outbound webhooks

Register endpoints in the dashboard (Developers) or with POST /webhook-endpoints. Payloads use the envelope { id, type, created_at, data }, the same headers and signature scheme as callbacks, and non-2xx responses are retried with the same backoff.

Outbound webhook events
Event
dispute.createdA new dispute or inquiry was received
dispute.updatedStatus, amount, reason or deadline changed
dispute.closedResolved: won, lost, accepted, prevented or inquiry closed
evidence.readyAn evidence packet was built or rebuilt and is ready for review
evidence.submittedEvidence was submitted to the processor
dispute.deadline_approaching72h and 24h before evidence is due, if not yet submitted

SDKs

Official clients wrap authentication, retries and signature verification. Everything else speaks plain HTTPS and is described by our OpenAPI document.

Node.js / TypeScript

@disputeguard/node

npm install @disputeguard/node

PHP

disputeguard/disputeguard-php

composer require disputeguard/disputeguard-php

Your first synced order is a few minutes away.

Create a source, grab your token, and push an order. Evidence starts accumulating immediately.