Skip to content
ChargebackStop | DOCS
Dashboard
DeveloperMerchant Integration Guides

Orders API Partial Enrichment Merchant Guide

Use this guide when you already have a payment processor integration, such as Stripe, connected to ChargebackStop and you want to enrich those processor transactions with order, customer, device, product, delivery, and evidence data.

The examples throughout this guide use Stripe, but the same PARTIAL order pattern applies to other existing processor integrations where ChargebackStop already ingests the payment data.

Reference documentation

Section titled “Reference documentation”

What partial enrichment does

Section titled “What partial enrichment does”

With Stripe connected, ChargebackStop already receives the payment record: amount, currency, card details, authorisation data, descriptor, refunds, and disputes where available.

PARTIAL orders add the commerce context that is often missing from the processor record:

Data area Why it matters
Customer identity Helps link repeat legitimate purchases for systematic deflection and digital receipt products.
Device identity Required for PARTIAL orders, First-Party Trust, and CE3.0. Stable device identifiers improve historical evidence quality.
Order details Makes the transaction recognisable and helps answer issuer/cardholder lookup requests.
Products and delivery Strengthens the receipt and evidence package returned for the matched transaction.
Consent and communications Adds dispute context, such as terms accepted, checkout notices, and support communications.

ChargebackStop combines the synced processor transaction with your enriched order record when responding to digital receipt or systematic deflection lookup requests.

Before you start

Section titled “Before you start”

You need:

Requirement Notes
A connected Stripe integration The integration must already be syncing successful Stripe payments.
Orders enrichment enabled ChargebackStop must enable orders enrichment on the Stripe integration. Otherwise PARTIAL order creation returns ENRICHMENT_NOT_ENABLED. Ask support to make sure this is enabled.
API key abilities Use orders:write to create enrichment records, orders:read to verify them, and orders:update if you will PATCH delivery/refund/dispute updates.
Relevant lookup enrolment enabled ChargebackStop must enable the relevant digital receipt or systematic deflection enrolment for the merchant, such as Consumer Clarity, Order Insight, First-Party Trust, or CE3.0.

ID mapping for Stripe

Section titled “ID mapping for Stripe”

The most important implementation decision is which ID you use as reference_id.

For partial enrichment, reference_id should identify the processor transaction that ChargebackStop will match during a lookup. In a typical Stripe setup, use the Stripe PaymentIntent ID, for example pi_3QJ2.... If your Stripe integration syncs legacy charge-only transactions, use the Stripe charge ID, for example ch_3QJ2....

Continue sending your storefront or commerce order number separately as order_number.

Your system value Orders API field Example
ChargebackStop organisation ID organisation_id org_abc123
ChargebackStop Stripe integration ID integration_id int_stripe456
Stripe transaction identifier matched by ChargebackStop reference_id pi_3QJ2KRFSLReU4y0Example
Customer-facing order number order_number SHOP-100045
Stable merchant customer ID customer_account_id cus_internal_789
Checkout email order_email and usually customer_email customer@example.com

ID mapping for PayNovus

Section titled “ID mapping for PayNovus”

ID mapping for PayNovus works the same way as for Stripe, with one difference: the transaction identifier to send as reference_id. For PayNovus, use the connector transaction ID from the ACI payment response, found at resultDetails.connectorId.

All other fields (organisation_id, integration_id, order_number, customer_account_id, order_email) map exactly as described in the Stripe table above.

Minimum valid PARTIAL order

Section titled “Minimum valid PARTIAL order”

Every create request is a JSON array, even when you submit one order.

curl -X POST "https://api.chargebackstop.com/v1/orders/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "type": "PARTIAL",
      "organisation_id": "org_abc123",
      "integration_id": "int_stripe456",
      "reference_id": "pi_3QJ2KRFSLReU4y0Example",
      "order_email": "customer@example.com",
      "customer_account_id": "cus_internal_789",
      "device_ip_address": "216.24.60.17"
    }
  ]'

What to send by product

Section titled “What to send by product”

The Orders API reference defines the exact PARTIAL field sets for each product. This guide shows how to apply those field sets when your payment data is already coming from Stripe.

Product group Lookup type Purpose Add these fields on top of the PARTIAL minimum
Digital receipts ETHOCA_CONSUMER_CLARITY Mastercard Consumer Clarity receipt enrichment order_datetime, order_number, order_subtotal_amount_in_cents, order_currency, order_total_amount_in_cents.
Digital receipts VERIFI_ORDER_INSIGHT Visa Order Insight receipt enrichment At least one items[] entry with name; include product, merchant, delivery, and order details when available.
Systematic deflection ETHOCA_FIRST_PARTY_TRUST Mastercard First-Party Trust customer_email, order_email, and at least one device identifier.
Systematic deflection VERIFI_COMPELLING_EVIDENCE_3 Visa CE3.0 customer_email and at least one device identifier; include historical order, item, delivery, merchant, consent, and communication data.

Digital receipt examples

Section titled “Digital receipt examples”

Digital receipts help cardholders recognise legitimate purchases in issuer experiences. These examples add receipt context to a Stripe PaymentIntent while Stripe remains the source of the payment transaction.

Use this when the merchant is enrolled for Mastercard Consumer Clarity.

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "pi_3QJ2KRFSLReU4y0Example",


    "order_email": "ava.chen@example.com",
    "customer_account_id": "cus_internal_789",
    "device_ip_address": "216.24.60.229",


    "order_datetime": "2026-06-15T10:30:00Z",
    "order_number": "SHOP-100045",
    "order_subtotal_amount_in_cents": 12900,
    "order_tax_amount_in_cents": 1032,
    "order_total_amount_in_cents": 13932,
    "order_currency": "USD",
    "order_status": "CLOSED_COMPLETE",


    "merchant_name": "Example Store Inc.",
    "merchant_store_name": "Example Store",
    "merchant_customer_service_email": "support@example.com",
    "merchant_contact_phone": "+14155551234",
    "merchant_url": "https://store.example.com"
  }
]

Systematic deflection examples

Section titled “Systematic deflection examples”

Systematic deflection products rely on a history of legitimate purchases. Send enrichment continuously for every eligible order, not only after a dispute or lookup happens.

Use this when the merchant is enrolled for Mastercard First-Party Trust.

[
  {
    "type": "PARTIAL",
    "organisation_id": "org_abc123",
    "integration_id": "int_stripe456",
    "reference_id": "pi_3QJ2KRFSLReU4y0Example",


    "customer_email": "ava.chen@example.com",
    "customer_account_id": "cus_internal_789",
    "order_email": "ava.chen@example.com",


    "device_ip_address": "216.24.60.229",
    "device_id": "ios-device-9f4b2a",
    "device_fingerprint": "fp_4e1f6d8c2b9a",


    "order_datetime": "2026-06-15T10:30:00Z",
    "order_number": "SHOP-100045",
    "order_total_amount_in_cents": 13932,
    "order_currency": "USD"
  }
]

Implementation flow

Section titled “Implementation flow”

  1. Confirm the integration

    Section titled “Confirm the integration”

    List integrations and identify the Stripe integration ID.

    curl -X GET "https://api.chargebackstop.com/v1/integrations/?limit=20&offset=0" \
      -H "Authorization: Bearer <api_key>"

    Use an integration with type: "STRIPE" and status: "ENABLED".

  2. Enable enrichment and product enrolments

    Section titled “Enable enrichment and product enrolments”

    Ask ChargebackStop to enable orders enrichment for the Stripe integration. Also confirm the merchant's required digital receipt or systematic deflection enrolments are enabled.

    Until enrichment is enabled, every PARTIAL order is rejected with ENRICHMENT_NOT_ENABLED. An enabled integration shows a green Orders enrichment badge on the Settings → Integrations page of the dashboard — check it there before sending the first order.

  3. Choose the reference_id

    Section titled “Choose the reference_id”

    Use the Stripe PaymentIntent ID for PaymentIntent-based transactions, or the Stripe charge ID for legacy charge-only transactions. Send the customer-facing commerce order ID as order_number.

    Nested reference_ids (items, transactions, deliveries, refunds) are also unique per integration, across all orders — not per order. For items, do not use a product-level identifier such as a SKU or a Stripe price ID (price_...): two orders containing the same product would collide with DUPLICATE_ITEM. Use the Stripe line-item ID or a composite key such as <payment_intent_id>:<price_id>.

  4. Create enrichment at checkout or fulfilment

    Section titled “Create enrichment at checkout or fulfilment”

    POST one or more PARTIAL orders to /v1/orders/. Send up to 100 orders per request.

  5. Store the ChargebackStop order ID

    Section titled “Store the ChargebackStop order ID”

    The create response returns the ChargebackStop ord_... ID. Store it so you can PATCH delivery, refund, dispute, or communication updates later.

  6. Verify the record

    Section titled “Verify the record”

    Use GET /v1/orders?reference_id=<stripe_transaction_id> to confirm the enrichment record exists and contains the expected customer, device, product, and delivery data.

Handling creates, retries, and duplicates

Section titled “Handling creates, retries, and duplicates”

The create endpoint supports partial success within a batch. Some orders can be created while other orders in the same request fail validation.

Response field Meaning
created Number of order records created.
results Created order objects. Store each returned id.
failed Number of order records that failed.
errors Per-order error details, including the array index, reference_id, error code, message, and field.

Use an idempotent retry pattern:

  1. Generate the same reference_id for the same Stripe transaction every time.
  2. If the first request times out, query GET /v1/orders?reference_id=<reference_id> before retrying.
  3. If the order exists, treat the create as successful.
  4. If the order does not exist, retry the POST.
  5. If a retry returns DUPLICATE_ORDER, query the order and continue.

Common errors:

Error code Cause Fix
INVALID_INTEGRATION The integration_id does not belong to the organisation or is not accessible to the key. Check organisation_id, integration_id, and API key scope.
INVALID_ORDER_TYPE PARTIAL was sent to a CUSTOM_ORDERS integration, or COMPLETE was sent to a processor integration. Use PARTIAL with Stripe or another existing processor integration.
ENRICHMENT_NOT_ENABLED Orders enrichment is not enabled for the integration. Ask ChargebackStop to enable it.
DUPLICATE_ORDER The same reference_id already exists for the integration. Treat as already created after verifying with the GET endpoint.
MISSING_FIELD A required field is missing, or an enabled product validation rule requires an additional field. Add the field shown in the error.
429 Too Many Requests Rate limit exceeded. Back off and retry. The create endpoint is limited to 100 requests per minute per organisation or partner group.

Updating enriched orders

Section titled “Updating enriched orders”

Use PATCH only for fields the update endpoint supports.

Update Supported by PATCH? Notes
order_status Yes Include order_status_other_description when status is OTHER.
order_communications Yes Useful for late support contact or dispute notes.
Delivery status and tracking Yes Existing deliveries are updated by reference_id.
Refunds Yes New refunds can be created, existing refund status can be updated.
Disputes Yes New disputes can be created, existing stage/status can be updated.
Customer email, account ID, device identifiers No Send these in the original POST.
Items and transactions No Send these in the original POST if needed.

Example delivery completion update:

curl -X PATCH "https://api.chargebackstop.com/v1/orders/ord_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveries": [
      {
        "reference_id": "dlv_SHOP-100045_1",
        "physical_shipping_status": "DELIVERED",
        "physical_shipping_datetime_delivered": "2026-06-18T14:30:00Z"
      }
    ],
    "order_communications": "Order confirmation email sent 2026-06-15. Shipment confirmation sent 2026-06-16. Delivery confirmation sent 2026-06-18."
  }'

Verifying digital receipt and deflection outcomes

Section titled “Verifying digital receipt and deflection outcomes”

Digital receipt and systematic deflection activity is exposed through lookup records and lookup webhooks, not chargeback alert webhooks.

Common lookup types:

Product Lookup type
Mastercard Consumer Clarity ETHOCA_CONSUMER_CLARITY
Mastercard First-Party Trust ETHOCA_FIRST_PARTY_TRUST
Visa Order Insight VERIFI_ORDER_INSIGHT
Visa CE3.0 VERIFI_COMPELLING_EVIDENCE_3

For Visa:

Scheme request source Lookup type Deflection behaviour
OI or OID VERIFI_ORDER_INSIGHT If CE3.0 is enabled and the transaction is matched, deflection_status starts as PENDING. A later CE notice updates it to SUCCEEDED or FAILED.
CE VERIFI_COMPELLING_EVIDENCE_3 Historical evidence lookup. It is not the deflection target, so deflection_status remains NOT_ATTEMPTED.

Verifi CE notice notifications update the linked lookup by linkedInsightId. A caseEvent of NEW marks the linked lookup deflection_status: "SUCCEEDED". FAILED, TIMEOUT, and DELETE mark it FAILED; DELETE can reverse a previous successful deflection.

Subscribe to:

  • lookup.created
  • lookup.updated

Use:

Lookup fields to monitor:

Field Meaning
type One of the lookup types listed above.
lookup_status PENDING, SUCCEEDED, FAILED, or TIMEOUT.
deflection_status NOT_ATTEMPTED, PENDING, SUCCEEDED, or FAILED.
integration_id The matched processor integration.
integration_transaction_id The matched processor transaction ID, for example a Stripe PaymentIntent ID.

Production readiness checklist

Section titled “Production readiness checklist”
  • Stripe integration is connected, enabled, and syncing production payments.
  • Orders enrichment is enabled on the production Stripe integration.
  • Required Consumer Clarity, Order Insight, First-Party Trust, or CE3.0 enrolments are enabled.
  • Production API key has orders:write, orders:read, and optionally orders:update.
  • Webhook endpoint verifies ChargebackStop signatures and handles retries idempotently.
  • reference_id maps to the Stripe transaction entity ChargebackStop ingests.
  • Customer, device, item, and delivery fields are sent at creation time.
  • Backfill strategy is agreed with ChargebackStop before importing historical orders.
  • Monitoring alerts on failed creates, ENRICHMENT_NOT_ENABLED, INVALID_ORDER_TYPE, and webhook delivery failures.
  • Reconciliation job checks recent Stripe transactions against ChargebackStop PARTIAL orders by reference_id.