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.
Statuses
When the total changes
The AI callscancel_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 topropose_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 topurchase_intent.updated with the purchaseIntentId. After each event, the AI reads the purchase again with get_purchase. See Webhooks.