Enrich a dispute

Enrichment is the process of sending additional evidence and signals to Chargeflow to strengthen a dispute response. Disputes are often vague: they arrive without the full context of a transaction's history and associated entities. By enriching disputes with comprehensive data points, such as order details, user activity logs, customer communications, and fulfillment records, you provide a clearer and more compelling narrative for Chargeflow's AI agents to work with.

Why enrichment matters

• Reduces missing-evidence gaps that weaken the narrative.
• Allows Chargeflow to build a tight, reason-code-specific response.
• Improves automation quality, enabling more effective handling of future disputes.

If you do not see a guide tailored to your business, contact Chargeflow. A risk and fraud analyst will help you identify which artifacts will move the needle.

General recommendations

Regardless of your business model, the following data points are useful for most dispute reasons:

1. Customer identity: Customer name and email add credibility by demonstrating that the business has accurate, comprehensive customer records.
2. Addresses: IP address, shipping address, and billing address prove delivery, verify that shipping and billing locations match, and confirm that the IP address aligns with the customer's location.
3. Order and product information: Product descriptions, prices, discounts, refund records, and images show that the customer had access to clear and accurate information about their purchase.

Start with a gap analysis

Chargeflow already pulls a lot of dispute data from the tools you connect. Build enrichment for what is missing, not for everything:

1. Connect your payment processor and billing platform first in the Chargeflow App. See Integrations.
2. Review what Chargeflow pulled. Fetch a few recent disputes with expand and note which fields are empty.
3. Build enrichment only for the missing fields, following the enrichment integration guide.

What each source typically provides

Coverage varies by provider and by how your account is configured, so treat this as a starting point and confirm it against your own disputes in step 2.

High-value fields to fill first

These four fields matter most on fraud disputes, where the question is whether the cardholder made the purchase.

The update dispute endpoint

Send all dispute-related evidence to Chargeflow with a single call:

PATCH https://api.chargeflow.io/public/2025-04-01/disputes/{disputeId}

Use the Chargeflow dispute ID (dispute.id), available in the dispute.created webhook payload, as the path parameter.

Key ideas

• Upsert semantics: Send only the fields you have. Chargeflow will add new fields or update existing ones. You do not need to resend unchanged data.
• One endpoint for the core payload: Transaction and order data go through this endpoint. Subscription records are a separate call on the same dispute, listed under Disputes: POST /disputes/{disputeId}/subscription. Communications have their own Customer Communication endpoint.
• Override or provide: If Chargeflow has already pulled a signal from a partner provider, you can override it by sending your own value. Chargeflow will adapt the response accordingly.
• Only shared data is used: the dispute response is built from what your connected integrations expose plus what you send here. A field you hold back, or one your integration does not expose, cannot appear in the evidence, so send anything you want argued.

Important: array merge behavior

• To add an item, include the existing items and the new item in the payload.
• If you omit existing items, they will be removed.

Example: appending a product

Current stored value:

"order": {
  "products": [
    {
      "name": "Shoes",
      "id": "123456789",
      "type": "physical_good",
      "quantity": 1,
      "description": "Nice shoes",
      "price": 150
    }
  ]
}

To append a new product, read the current array (or use the dispute.created event payload) and send the full array including the new item:

{
  "order": {
    "products": [
      {
        "name": "Shoes",
        "id": "123456789",
        "type": "physical_good",
        "quantity": 1,
        "description": "Nice shoes",
        "price": 150
      },
      {
        "name": "Socks",
        "id": "987654321",
        "type": "physical_good",
        "quantity": 2,
        "description": "Comfort socks",
        "price": 20
      }
    ]
  }
}

What products represents

order.products[] lists the items the customer purchased in the disputed order: one entry per line item, with the name, description, price, and quantity they paid for. A SaaS plan is a product with type: "digital_good".

Related data that is not a purchased item goes elsewhere:

Example: inline data creation

Use inline creation when the relevant object does not yet exist in Chargeflow, when the dispute is urgent and you need to add evidence in a single step, or when your systems cannot return a Chargeflow object ID.

{
  "transaction": {
    "payment_method": {
      "checks": {
        "three_d_secure_result": "passed",
        "avs_results": "Y",
        "address_line1_check": "passed",
        "address_zip_check": "passed",
        "cvc_check": "passed"
      },
      "name": "John Doe",
      "type": "card",
      "last4": "4242",
      "expiry_month": "12",
      "expiry_year": "2027",
      "brand": "visa",
      "country": "US"
    },
    "billing_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    },
    "source_id": "trx_1234567890",
    "created_at": "2025-01-27T10:00:00Z",
    "type": "paid",
    "amount": 100,
    "currency": "USD"
  }
}

Example: linking existing objects

If the transaction or order is already stored in Chargeflow, pass the object IDs instead of resending the full payload:

{
  "transaction": "b6acc3e8408d1d6e78797725",
  "order": "e4d0437fb81cb881cc6bc26a"
}

Chargeflow will link those objects to the dispute and reuse their data for enrichment and generation.

Multiple disputes on the same transaction

A single transaction can generate more than one dispute. To avoid duplication, Chargeflow will attempt to reuse enrichment data from previous disputes involving the same transaction. If automatic reuse is not possible or you prefer explicit linking, pass existing Chargeflow object IDs in your PATCH payload. This keeps payloads small and ensures consistent data across related disputes.

Response

When your PATCH request succeeds, Chargeflow returns the updated dispute object. The returned dispute includes the enrichment data you just sent (or linked), so you can confirm the update immediately.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "dis_12345",
  "source_id": "proc_67890",
  "account_id": "act_112233",
  "ext_account_id": "ext_act_445566",
  "created_at": "2025-01-27T10:00:00Z",
  "reason": "fraud",
  "due_by": "2025-02-10T10:00:00Z",
  "source": "stripe",
  "amount": 150,
  "currency": "USD",
  "status": "needs_response",
  "stage": "Chargeback",
  "closed_at": null,
  "evidence": {},
  "transaction": {
    "id": "trx_654321",
    "source_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2025-01-26T15:00:00Z",
    "type": "paid",
    "amount": 150,
    "currency": "USD",
    "payment_method": {
      "name": "John Doe",
      "type": "card",
      "last4": "4242",
      "expiry_month": "12",
      "expiry_year": "2027",
      "brand": "visa",
      "country": "US",
      "checks": {
        "three_d_secure_result": "passed",
        "avs_results": "Y",
        "address_line1_check": "passed",
        "address_zip_check": "passed",
        "cvc_check": "passed"
      }
    },
    "billing_address": {
      "name": "John Doe",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    }
  },
  "order": {
    "id": "ord_98765",
    "source_id": "748e2a7c-4d21-11ee-8c99-0242ac120002",
    "account_id": "act_112233",
    "ext_account_id": "ext_act_445566",
    "created_at": "2025-01-26T14:30:00Z",
    "payment_status": "paid",
    "name": "#ORD-98765",
    "type": "pre_order",
    "amount": 150,
    "currency": "USD",
    "customer": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "customer_since": "2023-06-15T12:00:00Z",
      "order_count": 10,
      "phone_number": "1(123)4567890",
      "ip_address": "192.168.1.1",
      "verified_email": true
    },
    "products": [
      {
        "name": "Wireless Headphones",
        "id": "prod_12345",
        "type": "physical_good",
        "quantity": 1,
        "description": "Noise-canceling wireless headphones with Bluetooth connectivity.",
        "image_url": "https://example.com/images/products/12345.jpg",
        "price": 150
      }
    ],
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "New York",
      "country": "US",
      "state": "NY",
      "zip_code": "10001",
      "phone": "1(123)4567890"
    },
    "fulfillments": [
      {
        "product_id": "prod_12345",
        "shipped_at": "2025-01-26T18:00:00Z",
        "shipping_line_title": "FedEx Air Express Shipping",
        "shipping_method_price": 0,
        "tracking_number": "1Z999AA10123456789",
        "courier": "FedEx"
      }
    ]
  },
  "activity_logs": null,
  "customerCommunication": "ccm_01j92p1x8a6y7t4gz8d9w3n5qk",
  "booking": null
}

Next steps

1. Map your internal data schema to Chargeflow fields. Decide which objects you will link by ID versus send inline.
2. Subscribe to dispute.created so your enrichment flows trigger automatically when a new dispute is ingested.
3. Pick what you want to add to the dispute: