fmb_ + funded wallet: payment wallet and download_url. 402 includes wallet_url. Else checkout_url.
3. Deliver
GET https://filemarket.app/api/v1/checkout/{id}
status paid, then download_url.
What success and errors look like
Read the status, then the JSON. Never invent a download_url.
Status
Meaning
What to do
201 wallet
payment: wallet and download_url
Give the human the file. Done.
201 checkout
payment: stripe_checkout and checkout_url
Hand the URL to the human. Poll status_url. Never enter a card.
201 free
payment: free and download_url
Same as a paid wallet buy. No Stripe.
402 underfunded
wallet_url is present
Ask the human to top up Agentic Pay, then retry.
402 cap
Daily agent spend cap
The human can still buy on the site. Do not retry until tomorrow.
400
Bad slug, gift email, or coupon
Show the error string. Do not guess a new slug.
403
Token or CSRF refused
Ask the human to mint a fresh fmb_ or fmk_.
404
Unknown slug or shop
search_catalog again. Do not invent listings.
409
Holiday mode or sold out
Tell the human. Waitlists are on the listing page.
429
Rate limited (this isolate)
Read X-RateLimit-Reset. Back off.
200 ping
Test webhook delivered
Read delivery. Host only. No signing secret.
400 ping
No webhook endpoint saved
Human sets notify_url on /account.
502 ping
Endpoint failed
Check last_failure_status. Do not retry in a loop.
Sellers: seller_list_listings, seller_update_listing, seller_publish_version, seller_webhook_status, and seller_webhook_ping. GET /api/v1/me/listings and POST /api/v1/me/webhooks/ping. Host only. No signing secret.
Pay on Stripe
Checkout uses automatic payment methods. No PayPal.
Cards and Link can appear when those methods are on in the Stripe Dashboard. Apple Pay and Google Pay appear only if Stripe has verified the domain and the buyer's device supports them. File Market does not claim Apple Pay is live. ACH (US bank) if you enable us_bank_account there. Apple Pay on Stripe hosted Checkout uses checkout.stripe.com, so no Apple domain file is needed on filemarket.app for that path. Register the domain in Stripe if you later serve Apple Pay on filemarket.app itself. Destination charges do not support PayPal.