The AI fills in the merchant’s checkout. Tuyo issues card details for that one purchase. The AI pays with them in code. The AI needs a client that can run code, keep a key safe and finish the checkout. Without these, the AI must not start a purchase.

Two ways to start

Both tools return the same purchase. After that, the steps are the same.

Steps

1

Fill in the checkout

The AI completes everything the checkout asks for, such as the contact, the shipping address and the delivery options. Then the total is final, with tax and shipping.
2

Start the purchase

The AI calls propose_purchase or prepare_purchase with the final checkoutUrl, the exact total and the currency. For a currency other than USD, the AI also sends an estimate in USD. Nothing is charged yet.
3

Wait until it is ready

The AI calls get_purchase. Each call can wait up to 25 seconds. The AI stops waiting five minutes after the purchase started.
4

Get the card details

When the purchase is active, the AI calls get_purchase_payment_details. It sends an AES key encrypted for cardEncryptionPublicKey from get_purchase. Tuyo returns the card number and CVC encrypted with that key. The MCP server only forwards ciphertext.
5

Pay

The AI decrypts the details in code and submits the checkout once.
The AI must never write the card number, the CVC or a key in a message.

Statuses

When the total changes

The AI calls cancel_purchase and starts a new purchase with the new total. Cancel ends the Tuyo card. It does not cancel or refund an order at the merchant.

When a response is lost

Each call to propose_purchase or prepare_purchase makes a new purchase, even with the same details. If a response is lost, the AI calls list_purchases and then get_purchase. It must not start the purchase again by itself. If a payment times out, it checks the merchant order before it pays again.

Follow a purchase with events

A client that supports MCP Events can subscribe to purchase_intent.updated with the purchaseIntentId. After each event, the AI reads the purchase again with get_purchase. See Webhooks.