> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paynext.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Mastercard Consumer Clarity
> Surface transaction details to cardholders through Mastercard's issuer channels to defuse confusion before a dispute is filed.
Mastercard Consumer Clarity is a Mastercard program that enriches the transaction receipt a cardholder sees—inside their mobile banking app or when they call their bank about a charge. When a cardholder questions a charge, Mastercard queries the transaction and PayNext returns a receipt with the order, merchant, and subscription details, so the cardholder recognizes the charge. It's Mastercard's equivalent of Visa Order Insight, reducing friendly fraud and disputes on Mastercard before they're ever filed.
Like Visa Order Insight, Consumer Clarity is a lookup signal only: the network never reports back what the cardholder did with the receipt, so the payload has no terminal or status field. Each lookup is recorded on the payment as `fraud_prevention.mastercard_consumer_clarity`.
## Lookup channels
The channel that triggered the most recent lookup is recorded as `mastercard_consumer_clarity.type`.
| Channel | Trigger | Where the receipt appears |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------- |
| `DIGITAL` | Cardholder taps "what's this charge?" inside the issuer's banking app | In-app, shown to the cardholder directly |
| `CALL_CENTRE` | Cardholder calls the issuing bank about a charge | Bank agent's screen during the call |
| `MASTERCOM` | The charge is queried through Mastercom, Mastercard's dispute case-management system | Internal—Mastercard's dispute tooling |
| `TRANSACTION_DATA` | Mastercard requests transaction data for the charge | Internal |
| `FIRST_PARTY_TRUST` | A cardholder disputes a charge claiming fraud; Mastercard's First Party Trust assessment looks up the disputed transaction plus two of the cardholder's older undisputed transactions (120–365 days old) to check whether the disputer is the genuine customer | Internal—Mastercard's First Party Trust assessment |
`DIGITAL` accounts for the large majority of lookups. The enum is open—Mastercard may add channels without a version bump, and unrecognized values pass through verbatim.
First Party Trust lookups compare identity fields—device fingerprint, email, phone, billing details—across the three receipts. When enough fields match, the dispute is assessed as first-party fraud and deflected. Each of the three lookups is recorded on its own payment with `type: "FIRST_PARTY_TRUST"`.
## Subscription handling
A Consumer Clarity lookup is informational: it signals that a cardholder is checking a charge, not that a dispute has been filed. PayNext records the lookup on the payment but takes **no automatic action on the subscription**.
This differs from Visa Order Insight, where an `OI` (call-centre) lookup schedules the subscription for cancellation. Consumer Clarity lookups never change subscription state on their own.
## Setup
There is no integration work beyond keeping your Dashboard configuration current. The receipt PayNext serves is built from data you already provide.
### Required fields
| Source | Fields |
| :------------------------------------------ | :---------------------------------------------------------------------------------------------- |
| **Dashboard → Organization** | Merchant name, URL, support email, support phone, product description, terms and conditions URL |
| **Dashboard → Integrations → \[Processor]** | Merchant billing address |
These are required Dashboard fields—if your account is set up, they're already filled in. Keep them current and Consumer Clarity works automatically.
Consumer Clarity enrolls by **statement descriptor**, not by CAID. Contact PayNext support to enroll; PayNext registers your descriptor with Mastercard end-to-end.
### Captured automatically
Device data—IP address, geolocation, user agent—is captured by the [Web SDK](/guides/advanced/device-fingerprinting) at checkout and is included in the receipt where available. No additional code is required.
## `mastercard_consumer_clarity` payload
Written every time Mastercard runs a Consumer Clarity lookup, regardless of channel. The latest lookup overwrites all three fields atomically.
```json theme={"system"}
{
"mastercard_consumer_clarity": {
"type": "DIGITAL",
"insight_id": "0.87161502.1780216058.b9db91c",
"updated_at": "2026-06-03T12:45:51Z"
}
}
```
| Field | Type | Description |
| :----------- | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Channel of the most recent lookup. Open enum: `DIGITAL`, `CALL_CENTRE`, `MASTERCOM`, `TRANSACTION_DATA`, `FIRST_PARTY_TRUST`. New values may be added without a version bump. |
| `insight_id` | string | Identifier for the most recent lookup, assigned by Mastercard. A correlation ID, **not a UUID**—unlike `visa_order_insight.insight_id`. Transient—changes whenever a new lookup arrives. |
| `updated_at` | string (ISO-8601) | Timestamp of the most recent lookup, UTC with `Z` suffix. |
This sub-object has no `status` field. Mastercard never reports back what the cardholder did with the receipt, so there's no terminal state to capture. Presence of `mastercard_consumer_clarity` means at least one lookup happened; `type` and `updated_at` describe the latest one.
## Read the payload
| Payload state | Meaning |
| :------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mastercard_consumer_clarity` absent | No Consumer Clarity lookup has happened on this payment |
| `mastercard_consumer_clarity.type = "DIGITAL"` | Cardholder looked up the charge inside their banking app |
| `mastercard_consumer_clarity.type = "CALL_CENTRE"` | Cardholder called the issuer about the charge |
| `mastercard_consumer_clarity.type = "MASTERCOM"` | The charge was queried through Mastercard's dispute tooling |
| `mastercard_consumer_clarity.type = "FIRST_PARTY_TRUST"` | The payment was looked up as part of a First Party Trust assessment—either as the disputed transaction or as one of the two historical transactions used for identity matching |
Once `mastercard_consumer_clarity` is written, it is never cleared. A later lookup overwrites `type`, `insight_id`, and `updated_at`—last-write-wins.
## Webhook events
Updates to `mastercard_consumer_clarity` are delivered on the `payment_v2.updated` event. See [Webhook event types](/webhooks/introduction/event-types) and the [Payment webhook object](/webhooks/objects/payment/payment) for the full schema.