Skip to main content
A shopper who wants their money back asks two things: who charged me, and who do I talk to. Each placed order answers both in merchant_of_record. Read it, and your app tells the shopper where to go without asking Agentcard. The SDK’s BuyOrder does not carry the field yet, so read it off raw, the answer as Agentcard sent it, under a type of your own.
orders.ts

​
Read who charged the card

merchant_of_record sits on each order in the conversation read’s raw.orders, on the order read GET /buy/orders/:order_id, and on the order.placed event. In a webhook handler it is event.data.merchant_of_record, in the same shape. The whole field is null for an order Agentcard cannot answer for yet. Show nothing about who charged in that case, and send the shopper to Agentcard support if they ask.

​
Send a return first

A return goes to the party in name 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

When a return fails, dispute_with says who handles the dispute. With card_bank, the shopper paid with their own card, such as the card in their Vault. The shopper opens the dispute with their bank. Agentcard keeps the record of the shopper’s approval, the store and the amount they approved with their passkey, as evidence for that dispute. With agentcard, the shopper paid from a 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 with statement_name. A statement can read Agentcard, not the store, when Agentcard charged the card: a retail order paid with the shopper’s own card on Agentcard’s checkout is charged by Agentcard, and 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.

​
Compare with fulfilled_by

fulfilled_by names who sells or books the 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 is { name: 'Delta', kind: 'airline' }, while Agentcard booked it and charged the card, so merchant_of_record.name reads Agentcard. On a product card the SDK hands back, fulfilled_by also carries line, the words to show: flown by Delta. On a raw answer or an event, fulfilledByOf(value) returns the same line, and null for a party it cannot read. Show that line beside the product and merchant_of_record beside the charge.