AP2 Chargeback Handling, in depth: the network lifecycle, a case state machine, ledger entries and representment built from mandates

What AP2 provides and what it does not

The current AP2 specification defines five roles: the Shopping Agent, which discovers products, builds the checkout and executes the purchase; the Credential Provider, which supplies payment credentials and verifies the agent's authorization; the Merchant; the Merchant Payment Processor; and the Trusted Surface, a non-agentic interface where the user gives consent. It defines two mandates, each in an open and a closed form. The Checkout Mandate captures the user's constraints on what may be bought and, when closed, the authorization for a specific checkout; it is shared with the merchant and bound to a merchant-signed checkout by a hash. The Payment Mandate captures constraints on payment and, when closed, authorization for a specific amount; it goes to the credential provider, the network and the processor. Receipts accompany both. Older AP2 material used different mandate names, so check which version a counterparty implements.

The specification says the two mandates and their receipts can be brought together to give a non-repudiable picture of the transaction, and lists verification steps that must pass first. It says nothing about reason codes, deadlines, fees or who bears a loss; those come from network rules and your acquirer contract.

The chargeback lifecycle

Network terminology differs, but the shape is the same everywhere. The cardholder disputes with the issuer. The issuer raises a chargeback with a reason code, and the network moves the funds from the acquirer to the issuer. The acquirer debits the merchant and notifies it, typically through the processor's API or a webhook. The merchant either accepts, or responds with evidence; Visa calls this a dispute response and Mastercard a second presentment, and both are commonly called representment. The issuer reviews the response and either accepts it, returning the funds, or escalates to pre-arbitration. If the parties still disagree, the network decides in arbitration, and the loser usually pays a significant fee.

Each step has a deadline set by network rules. Your processor will usually put the response due date on the case; store it and treat it as the most important field you have, because a perfect package submitted late loses.

Dispute categories and the evidence that answers them

Visa groups its dispute reasons into four categories: fraud, authorization, processing errors and consumer disputes. Other networks use different codes for similar ideas. AP2 artifacts are strong evidence for some categories and nearly irrelevant for others, so route each case by category before building anything.

The common mistake is to send mandates for everything. A user who says the boots never arrived is not denying authorization, and a perfect signature chain does not show delivery. For fraud claims on authenticated transactions, check first whether a liability shift applies, as described in 3-D Secure for agent payments; if it does, the case may never need representment.

Model each case as a state machine

Chargebacks are long-running, multi-party workflows with deadlines, so model them explicitly rather than as a status column that anyone can update. Every transition is triggered by an event from the processor or by a decision of your own, and every state has a deadline or is terminal.

from dataclasses import dataclass, field
from datetime import datetime, timezone
from enum import Enum

class S(Enum):
    ALERT = "alert"                  # pre-dispute alert, refund still possible
    OPEN = "open"                    # chargeback received, funds withdrawn
    REPRESENTED = "represented"      # evidence submitted
    PRE_ARB = "pre_arbitration"      # issuer rejected our evidence
    ARBITRATION = "arbitration"
    WON = "won"
    LOST = "lost"
    ACCEPTED = "accepted"            # we chose not to fight
    REFUNDED = "refunded"            # resolved at the alert stage

ALLOWED = {
    S.ALERT: {S.REFUNDED, S.OPEN},
    S.OPEN: {S.REPRESENTED, S.ACCEPTED},
    S.REPRESENTED: {S.WON, S.PRE_ARB},
    S.PRE_ARB: {S.ACCEPTED, S.ARBITRATION, S.WON},
    S.ARBITRATION: {S.WON, S.LOST},
}

@dataclass
class Case:
    case_id: str            # processor's dispute id, used as idempotency key
    payment_id: str
    category: str           # fraud, authorization, processing_error, consumer
    amount_minor: int
    currency: str
    state: S
    respond_by: datetime | None
    history: list = field(default_factory=list)

    def transition(self, new: S, event_id: str, respond_by: datetime | None = None):
        if any(h[0] == event_id for h in self.history):
            return                                  # duplicate webhook, ignore
        if new not in ALLOWED.get(self.state, set()):
            raise ValueError(f"{self.case_id}: {self.state} -> {new} not allowed")
        self.history.append((event_id, self.state, new, datetime.now(timezone.utc)))
        self.state, self.respond_by = new, respond_by

Three properties matter. Webhooks are delivered at least once and sometimes out of order, so transitions are idempotent on the event id and invalid jumps are rejected loudly rather than applied. The respond_by field drives a scheduler that escalates to a human well before the deadline. And the history is append-only, because it is itself evidence when you reconcile with the acquirer later.

Ledger entries that match the money

A chargeback moves real money before anyone has decided who is right, so the ledger must show disputed funds separately from both revenue and losses. With double-entry bookkeeping, as in the AP2 double-entry ledger, a typical sequence looks like this:

Keep the case id on every entry. Then the balance of disputed funds receivable equals the total of open cases at any moment, which is a reconciliation check you can run daily against the processor's dispute report. A mismatch means a missed webhook or a double-applied event, and both are much cheaper to find in a day than at month end. Never refund a transaction that already has an open chargeback: the cardholder would be paid twice, and many processors block it for that reason.

Assembling representment from mandates

When a fraud or processing-error case is worth fighting, the evidence builder gathers the artifacts, verifies them, and produces a package in the format the processor accepts. Verification comes first: an artifact that fails a check is worse than useless, because submitting it undermines everything else in the package.

def build_representment(case, store, verifier):
    pay = store.payment(case.payment_id)
    checkout_mandate = store.checkout_mandate(pay.checkout_id)
    payment_mandate = store.payment_mandate(pay.payment_mandate_id)
    receipts = store.receipts(pay.payment_id)

    report = verifier.verify_all(checkout_mandate, payment_mandate, receipts)
    if not report.ok:
        return Decision.ACCEPT, f"evidence failed: {report.failed_checks}"

    exhibits = [
        exhibit("Checkout approved", checkout_mandate.raw_bytes, report.checkout),
        exhibit("Payment approved", payment_mandate.raw_bytes, report.payment),
        exhibit("Mode", "direct" if report.user_signed_closed else "autonomous", None),
    ]
    if case.category == "consumer":
        exhibits += store.fulfilment_evidence(pay.order_id)   # tracking, delivery
    return Decision.REPRESENT, render_for_processor(case, exhibits)

Store the exact signed bytes of every mandate and receipt at payment time, with the keys or key references needed to verify them later. You cannot reconstruct a signature from a database row months later. Put a plain-language summary at the top of the package too, because the reviewer at the issuer will not parse a JSON Web Token.

Direct and autonomous purchases in a dispute

AP2 distinguishes a direct flow, in which the user approves the closed Checkout and Payment Mandates on a Trusted Surface, from an autonomous flow, in which the user approves open mandates with constraints and the Shopping Agent later signs the closed mandates with its own key. The evidence these produce is different, and so is its strength.

In a direct purchase, the user's own signature covers the exact basket and amount, which is close to the strongest authorization evidence available. In an autonomous purchase, the user's signature covers the constraints, and the agent's signature covers the specific purchase. Your package has to show both, and show that the purchase fell within the constraints. Whether a network or issuer treats that chain as cardholder authorization for a fraud claim is decided by network rules and practice, not by AP2, and it may differ by network; confirm with your acquirer before you rely on it. Track win rates for direct and autonomous cases separately so you learn the answer from data.

Prevention, alerts and ratio monitoring

The cheapest chargeback is the one that never happens. Many networks and their partners offer pre-dispute services that tell the merchant about a pending dispute and let it refund first; a refund at that stage avoids the chargeback, its fee and a mark on your dispute ratio. Route these alerts into the same state machine, as the ALERT state above. Clear billing descriptors and receipts that name the agent and what it bought reduce disputes from confused cardholders.

Networks monitor merchants with high dispute and fraud rates. Visa's Acquirer Monitoring Program, VAMP, measures a ratio of reported fraud and disputes to transactions; industry sources report that its merchant threshold for most regions tightened to 1.5% on 1 April 2026. Treat that figure as a guide and confirm the current rules for your region with your acquirer. Compute your own ratio daily, per merchant account, from the case store rather than waiting for a monthly report.

Worked example

A user approves an open Checkout Mandate allowing their agent to buy running shoes under 150 euros from three named merchants, and an open Payment Mandate with the same cap. Two weeks later the agent finds a pair for 129 euros, signs the closed mandates with its agent key, and completes the purchase. Five weeks after that the user's bank raises a fraud chargeback: the user does not remember the purchase.

The processor's webhook creates a case in OPEN with a response deadline. The ledger moves 129 euros to disputed funds receivable and books the dispute fee. The evidence builder loads the stored mandates and receipts and runs the verification checks; all pass, and the closed mandates fall within the open constraints on merchant, product type and amount. Delivery tracking shows the shoes reached the user's address. The package leads with a summary, attaches the artifacts, and is submitted with eight days to spare.

The issuer accepts the response and does not escalate. The case moves to WON, the funds return, and the receivable clears.

Failure modes

• Missed deadline. A case sits unassigned until it expires. Drive escalation from respond_by and alert days before it.
• Unverifiable evidence. Only parsed fields were stored, so signatures cannot be checked. Store raw signed bytes and key references at payment time.
• Wrong evidence for the category. Mandates are sent for a not-received claim. Route by category and attach fulfilment proof.
• Double refund. Support refunds a payment that already has a chargeback. Block refunds on payments with an open case.
• Ledger drift. Duplicate or out-of-order webhooks are applied twice. Make transitions idempotent and reconcile receivables daily.
• Ratio surprise. Disputes from a misbehaving agent integration push a merchant over a monitoring threshold. Compute the ratio daily and alert on trend.

What to do next

1. Read your acquirer agreement and the network rules for your regions, and list the reason codes, response windows and fees that apply to you.
2. Store the raw signed bytes of every Checkout and Payment Mandate and receipt, with key references, and set a retention period longer than the longest dispute window.
3. Implement the case state machine with idempotent, validated transitions and a deadline-driven escalation scheduler.
4. Add the disputed-funds ledger entries and a daily reconciliation of open cases against the processor's dispute report.
5. Build the evidence pipeline: verify first, route by category, add fulfilment evidence where relevant, and lead with a plain-language summary.
6. Subscribe to pre-dispute alerts, refund honest complaints early, and compute your dispute ratio per merchant account every day.
7. Track win rates separately for direct and autonomous purchases, and reconcile disputes with settlement using AP2 reconciliation.