Industry Enrichment

PATCH /public/2025-04-01/disputes/{disputeId}

You are a merchant enriching a dispute for your industry. Every dispute is a story: the cardholder tells theirs to the issuer, and your job is to give Chargeflow the data to tell yours. Send all your evidence in one universal_order block matched to your vertical, and Chargeflow builds reason-code-aware evidence automatically. No explicit type declaration is needed, just include the right block.

How enrichment works

1. Your API call - send a PATCH with universal_order containing your order data and the relevant industry block.
2. Field analysis - Chargeflow reads the industry fields and identifies the commercial story.
3. Evidence builder - Chargeflow crafts a narrative from your data, optimized for the dispute's reason code.
4. Submission - the completed evidence package is submitted to the issuer on your behalf.

Quick start

Enrich an accommodation dispute in under five minutes. Swap the accommodation block for your industry's block (see Choose your block), keeping customer and order as the anchors.

curl -X PATCH https://api.chargeflow.io/public/2025-04-01/disputes/dp_01HXYZ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "universal_order": {
      "customer": {
        "email": "sarah.chen@example.com",
        "name": "Sarah Chen"
      },
      "order": {
        "external_id": "BK-20260315-8842",
        "currency": "USD",
        "amount": 847.50,
        "ordered_at": "2026-02-10T14:23:00Z",
        "status": "completed"
      },
      "accommodation": {
        "property_name": "The Oceanview Hotel",
        "property_type": "hotel",
        "booked_check_in": "2026-03-15",
        "booked_check_out": "2026-03-18",
        "actual_check_in": "2026-03-15T16:02:00Z"
      }
    }
  }'

Once the request succeeds, Chargeflow detects the industry from the block, analyzes the fields against the reason code, builds a tailored narrative, and submits it to the issuer.

Universal fields

Every universal_order payload shares the same outer envelope. The industry block (accommodation, flight, dining, etc.) tells Chargeflow the commercial story; the envelope carries the cross-industry data. You never specify the type explicitly.

The order object also supports confirmation fields that strengthen evidence:

Recommended data points

A few data points help win most dispute reasons across every industry:

1. Customer identity - name and email show you hold accurate records of your customers.
2. Addresses - ip_address, shipping, and billing addresses prove delivery, verify billing/shipping match, and confirm the buyer's location.
3. Order and product information - descriptions, prices, discounts, refunds, and images show the customer had clear information about the purchase.

Choose your block

Search your industry or pick a card. Each block opens with what it covers, the fields that win disputes, and a full payload you can copy. If your platform spans several domains, send the block that matches the specific transaction being disputed: an OTA uses Accommodation for hotel bookings and Flights for air tickets, from the same platform.

Sending data: upsert, arrays, and linking

Call PATCH /{api_version}/disputes/{disputeId} with the Chargeflow dispute ID to add or update enrichment. The endpoint uses upsert semantics: send only the fields you have.

• Arrays are replace-in-full. When you update an array field (for example products or fulfillments), the passed array is stored exactly as sent. To add an item, include the existing items and the new one; omitted items are removed. To append safely, read the current array (or use the dispute.created event), then PATCH with the full array.
• Inline vs. linked objects. Send full payloads, or pass IDs of objects already stored in Chargeflow to avoid duplication, e.g. { "transaction": "b6acc3e8408d1d6e78797725", "order": "e4d0437fb81cb881cc6bc26a" }. Chargeflow links them and reuses their data.
• Multiple disputes on one transaction. Chargeflow reuses enrichment from earlier disputes on the same transaction when possible; pass existing object IDs to force explicit linking.

Error responses

For the full error reference, see Error handling.

Next step