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.
Get a token
1 minSign 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. A401means the token is wrong or was rotated.Token and checkexport 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"Send an order
2 minOpen Orders in the dashboard and order 1001 is there. Only four fields are required:
external_id(your id),amount(in cents),currencyandplaced_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 ordercurl -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..." } }'Send an event
1 minEvents are the evidence: what the customer did and what you did for them. The
idempotency_keymakes retries safe, so a second run reports a duplicate and adds nothing.The shipment now shows on order 1001's timeline.
Send an eventcurl -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
Wire it into your app
15 minPut 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 Send Checkout completes The order with its processor ids, plus checkout.completed with IP, user agent and terms_accepted 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) The order again (it is an upsert) You ship, it is delivered fulfillment.shipped, fulfillment.delivered fulfillment.shipped, fulfillment.delivered Customer signs in customer.login with IP and device id (link by customer_email, no order needed) 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 download.accessed, service.accessed, usage.recorded A support message goes either way communication.message communication.message A subscription renews or is cancelled subscription.renewed, subscription.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/batchtakes 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.Test evidence callbacks
10 minSome 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.requestedthere when a dispute lands. Build the handler under Runtime evidence callbacks, then send it a correctly signed request from your terminal.You should see
200and your evidence JSON. Change one character ofSECRETand you get400: the handler checked the signature.Signed test requestSECRET=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"Fight a Stripe test dispute
10 minSee the whole loop with no real money and no real customer.
- Under Connections, Stripe, paste a test key (
sk_test_…orrk_test_…). The connection shows Test mode. - Create a payment with Stripe's test card
pm_card_createDispute. It is disputed as fraudulent seconds after it's charged. Copy thepi_…id from the response. - 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. - 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 paymentcurl 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- Under Connections, Stripe, paste a test key (
When something's wrong
| You get | It means |
|---|---|
| 401 | Token missing, mistyped or rotated. Check the Authorization: Bearer header. |
| 403 | The source was disconnected. Reconnect it, or create a new one, under Sources. |
| 422 | A field is wrong; errors names it, for example "amount": ["The amount field is required."]. Batches are all-or-nothing. |
| 429 | Over 600 requests a minute. Wait Retry-After seconds (the SDKs do this). |
| A dispute with no order | No 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
| Endpoint | Purpose |
|---|---|
| POST/ordersCreate or update an order, keyed by your external_id | Create or update an order, keyed by your external_id |
| POST/orders/batchUpsert up to 100 orders | Upsert up to 100 orders |
| GET/orders/{external_id}Retrieve an order by your ID | Retrieve an order by your ID |
| POST/eventsAppend up to 100 activity events | Append up to 100 activity events |
| GET/disputesList disputes, newest first | List disputes, newest first |
| POST/disputes/{id}/evidencePush evidence for a dispute (async callback answer) | Push evidence for a dispute (async callback answer) |
| POST/disputes/{id}/filesAttach a PDF, PNG or JPEG (≤ 4 MB) | Attach a PDF, PNG or JPEG (≤ 4 MB) |
| POST/webhook-endpointsRegister an outbound webhook endpoint | Register 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.
| Field | Example | Notes |
|---|---|---|
| processor | stripe | stripe, paypal, square, shopify_payments, braintree, authorize_net, other |
| charge_id | ch_3P… | Stripe charge ID |
| payment_intent_id | pi_3P… | Stripe PaymentIntent ID |
| transaction_id | 8AB12345CD678901E | Generic processor transaction ID |
| customer_id | cus_… | Processor customer ID |
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.
{
"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.
- Compute the HMAC over
{t}.{raw_body}: the raw bytes, not re-serialised JSON. - Compare against each
v1=value in constant time. - Reject if the timestamp is more than 300 seconds from now.
- 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: 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.
| Event | When |
|---|---|
| dispute.createdA new dispute or inquiry was received | A new dispute or inquiry was received |
| dispute.updatedStatus, amount, reason or deadline changed | Status, amount, reason or deadline changed |
| dispute.closedResolved: won, lost, accepted, prevented or inquiry closed | Resolved: won, lost, accepted, prevented or inquiry closed |
| evidence.readyAn evidence packet was built or rebuilt and is ready for review | An evidence packet was built or rebuilt and is ready for review |
| evidence.submittedEvidence was submitted to the processor | Evidence was submitted to the processor |
| dispute.deadline_approaching72h and 24h before evidence is due, if not yet submitted | 72h 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/nodePHP
disputeguard/disputeguard-php
composer require disputeguard/disputeguard-phpYour first synced order is a few minutes away.
Create a source, grab your token, and push an order. Evidence starts accumulating immediately.