merchant_of_record. Read it, and your app tells the shopper where to go without asking Agentcard.
Read who charged the card
merchant_of_record has four fields:
The whole field is
null for an order whose payer Agentcard does not know yet. Show nothing about who charged in that case, and send the shopper to Agentcard support if they ask.
The field sits on each order in a read of the whole purchase, on a read of one order, and on the order.placed event. Agentcard sends that event to your webhook endpoint, the address on your server where Agentcard sends a request when something happens.
- SDK
- MCP
- API
agentcard.conversation() reads the whole purchase, and each order in its orders list carries merchant_of_record:orders.ts
merchantOfRecordOf(), which returns the same shape, or null for a value it cannot read:webhooks.ts
Send a return first
A return goes to the party inname first. A DoorDash order with a missing item is DoorDash’s to refund, so the shopper asks DoorDash before they open a dispute. When kind is agentcard, the shopper asks Agentcard support for the return, with the order number.
Send a dispute
A dispute is a request to the shopper’s bank, or to Agentcard, to take a charge back. When a return fails,dispute_with says who handles it.
With card_bank, the shopper paid with their own card, such as the card saved in the Vault, Agentcard’s page where the shopper saves their card and approves a payment. The shopper opens the dispute with their bank. Agentcard keeps the record of what the shopper approved with their passkey, the store and the amount, as evidence for that dispute.
With agentcard, the order was paid from money held in an Agentcard balance, through a card Agentcard issued for that one order. The shopper has no bank to call. Agentcard handles the dispute, so send the shopper to Agentcard support with the order number.
Match the statement line
A shopper who does not recognize a charge compares it withstatement_name. A statement can read Agentcard instead of the store when Agentcard charged the card. An order at a large store such as Amazon, Walmart or Target, whose merchant reads retail, is charged by Agentcard when the shopper pays with their own card. Its statement_name reads AGENTCARD CORPORATION and merchant_of_record.name reads Agentcard, while the order’s merchant_name reads Amazon. Show both, so the shopper links the line on their statement to the order they placed.
Show who sells the product
fulfilled_by names who sells or books a product, and merchant_of_record names who charged the card. The two often differ. A flight is flown by its airline, so its fulfilled_by names Delta, while Agentcard booked it and charged the card, so merchant_of_record.name reads Agentcard.
A product carries fulfilled_by only where the seller is not the store the product already names. A product at Amazon or at a store’s own website carries none. Show the seller’s line beside the product, and merchant_of_record beside the charge.
- SDK
- MCP
- API
On a product card the SDK hands back,
fulfilled_by carries name, kind and line, the words to show, such as flown by Delta. On a raw answer or an event, fulfilledByOf(value) returns the same fields, and null for a party it cannot read.cards.ts