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.

Use PARTIAL orders only with existing non-CUSTOM_ORDERS integrations, for example STRIPE. If you do not have a payment processor integration and need to upload complete order and transaction data yourself, use a CUSTOM_ORDERS integration with COMPLETE orders instead.

Reference documentation

• Orders API

• Integrations API

• Lookups API

• Simulations API

• Webhooks

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

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.

PARTIAL orders cannot be created on a CUSTOM_ORDERS integration. If you send type: "PARTIAL" with a CUSTOM_ORDERS integration, the API returns INVALID_ORDER_TYPE.

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	[e-mail]

If you are not sure whether your Stripe integration is matching on PaymentIntent IDs or charge IDs, confirm with ChargebackStop before backfilling. The reference_id must match the processor transaction entity ID ChargebackStop has ingested.

Minimum valid PARTIAL order

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

Request

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": "[e-mail]",
      "customer_account_id": "cus_internal_789",
      "device_ip_address": "216.24.60.17"
    }
  ]'

Required fields

Create the enrichment record as early as possible, ideally at successful checkout or fulfilment. The current PATCH endpoint updates delivery, subscriptions, refunds, disputes, order status, and order_communications; it does not update customer email, account ID, device identifiers, items, transactions, or core order totals after creation.

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.

You can send one enriched PARTIAL order that supports more than one product. For example, a single payload can include Consumer Clarity order totals, Order Insight item data, and CE3.0 customer/device data.

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.

Consumer Clarity

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": "[e-mail]",
    "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": "[e-mail]",
    "merchant_contact_phone": "[phone]",
    "merchant_url": "https://store.example.com"
  }
]

Order Insight

Visa Order Insight responses cap the returned order number to 25 characters. Keep order_number recognisable within that limit where possible.

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.

First-Party Trust

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": "[e-mail]",
    "customer_account_id": "cus_internal_789",
    "order_email": "[e-mail]",

    "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"
  }
]

CE3.0

You usually do not need to submit a transactions array for Stripe partial enrichment because the Stripe integration already supplies the transaction data. If ChargebackStop asks you to supplement payment details, follow the transaction schema in the Orders API reference.

Implementation flow

1

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

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

3

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.

4

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

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

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

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

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

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:

• Lookups API for polling or reconciliation.

• Webhooks for real-time events.

• Simulations API in TEST organisations.

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.

For CE3.0 billing or success metrics, use deflection_status: "SUCCEEDED" on the linked lookup as the positive deflection signal. lookup_status: "SUCCEEDED" means ChargebackStop matched and answered the lookup; it is not the same as a successful deflection.

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.