docs(agent): show the buyer-pays money path in connect-btcpay

Extend the programmatic connect snippet with the checkout + poll steps
(POST /v1/purchase, GET /v1/purchase/{id}) and note the purchased license
carries the policy entitlements, so it unlocks the same gate the worked
example builds. Ties connect, buyer-pays, and gate-unlock together in one
place; previously that money path lived only in the OpenAPI spec.
This commit is contained in:
Keysat
2026-06-17 12:03:16 -05:00
parent 7e6f752462
commit 1d87d6d889
+12 -1
View File
@@ -267,7 +267,18 @@ curl "$KS/v1/btcpay/authorize/callback?state=STATE&apiKey=BTCPAY_STORE_API_KEY"
# 3. Confirm.
curl $KS/v1/admin/btcpay/status -H "Authorization: Bearer ks_..."
# -> { "connected": true, "store_id": "...", "base_url": "...", ... }</pre>
# -> { "connected": true, "store_id": "...", "base_url": "...", ... }
# 4. Create a buyer checkout for one of your paid products (public endpoint, no auth).
curl -X POST $KS/v1/purchase -H "Content-Type: application/json" -d '{
"product": "acme-reports", "policy_slug": "pro", "buyer_email": "buyer@example.com"
}'
# -> { "invoice_id": "...", "checkout_url": "https://btcpay.example/i/...", ... }
# 5. The buyer pays checkout_url; poll until settlement signs a license.
curl $KS/v1/purchase/INVOICE_ID
# -> { "status": "settled", "license_key": "LIC1-..." }</pre>
<p>The <code>license_key</code> a settled purchase returns carries the policy's entitlements, so it unlocks the same gate the <a href="#worked-example">worked example</a> builds. That is the full money path: connect once, then every buyer purchase self-issues a signed license.</p>
<p>Scope the BTCPay key to exactly the store you want to connect: Keysat attaches the first store the key can see. If the store's network cannot be confirmed as non-mainnet (mainnet, a Lightning-only store, or any detection failure), the callback fails closed with a 4xx and nothing is persisted. Disconnect (<code>POST /v1/admin/btcpay/disconnect</code>) is always master-only.</p>
<p><em>Scope required: <code>payment_providers:write</code>, on a sandbox daemon, for a non-mainnet store. The master key may connect any network on any daemon.</em></p>