From ab5983fe4e881d02d6f8a266d96d24084cd73b80 Mon Sep 17 00:00:00 2001 From: nvp Date: Thu, 21 May 2026 19:23:44 +0000 Subject: [PATCH 1/2] update SKILL.md --- skills/create-payment-credential/SKILL.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/skills/create-payment-credential/SKILL.md b/skills/create-payment-credential/SKILL.md index 11f0f2c..0535fe5 100644 --- a/skills/create-payment-credential/SKILL.md +++ b/skills/create-payment-credential/SKILL.md @@ -122,6 +122,16 @@ What you find determines which credential type to use: | HTTP 402 with `method="stripe"` in `www-authenticate` | `shared_payment_token` | Shared payment token (SPT) | | HTTP 402 without `method="stripe"` in `www-authenticate` | not supported | Do not continue | +**If the merchant site returns 403 (bot protection):** + +Some merchants use Cloudflare or Vercel bot protection that blocks automated requests. If you receive a 403 when browsing the merchant site, use `web-bot-auth sign` to obtain signed headers: + +```bash +link-cli web-bot-auth sign +``` + +Attach the returned `Signature` and `Signature-Input` headers to your HTTP requests to the merchant. The headers are valid for ~10 minutes and are scoped to the merchant's domain. + **For 402 responses:** The `www-authenticate` header may contain **multiple** payment challenges (e.g. `tempo`, `stripe`) in a single header value. Do not try to decode the payload manually. Pass the **full raw `WWW-Authenticate` header value** to Link CLI and let `mpp decode` select and validate the `method="stripe"` challenge. To derive `network_id`, use Link CLI's challenge decoder: @@ -190,7 +200,7 @@ link-cli spend-request retrieve --include card --output-file /tmp/link-card link-cli mpp pay --spend-request-id [--method POST] [--data '{"amount":100}'] [--header 'Name: Value'] ``` -`mpp pay` handles the full 402 flow automatically: probes the URL, parses the `www-authenticate` header, builds the `Authorization: Payment` credential using the SPT, and retries. +`mpp pay` handles the full flow automatically: if the merchant returns **403** (bot protection), it fetches Web Bot Auth headers and retries transparently; if it then returns **402**, it parses the `www-authenticate` header, builds the `Authorization: Payment` credential using the SPT, and retries. No manual `web-bot-auth sign` call is needed when using `mpp pay`. ## Important @@ -213,6 +223,8 @@ All errors are output as JSON with `code` and `message` fields, with exit code 1 | API rejects `merchant_name` or `merchant_url` | These fields are forbidden when `credential_type` is `shared_payment_token` | Remove both fields from the request; SPT flows identify the merchant via `network_id` instead | | Spend request approved but payment fails immediately | Wrong credential type for the merchant (e.g. `card` on a 402-only endpoint) | Go back to Step 2, re-evaluate the merchant, create a new spend request with the correct `credential_type` | | Auth token expired mid-session (exit code 1 during approval polling) | Token refresh failure during background polling | Re-authenticate with `auth login`, then retrieve the existing spend request or resume polling. Only create a new spend request if the original one expired, was denied, was canceled, or its shared payment token was already consumed | +| 403 when browsing merchant site in Step 2 | Bot protection (Cloudflare/Vercel) blocking automated requests | Run `link-cli web-bot-auth sign ` and attach the returned `Signature` and `Signature-Input` headers to your browsing requests | +| `Received 403 before and after Web Bot Auth retry` from `mpp pay` | Merchant returns 403 for a reason unrelated to bot protection (auth, geo-block, etc.) | Cannot proceed with this URL — report to the user that the merchant is blocking access | ## Further docs From bd11e0d1b2a9915180c6ba0a67af4f508a4989fb Mon Sep 17 00:00:00 2001 From: nvp Date: Fri, 22 May 2026 01:39:46 +0000 Subject: [PATCH 2/2] update skill --- skills/create-payment-credential/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/skills/create-payment-credential/SKILL.md b/skills/create-payment-credential/SKILL.md index 0535fe5..9ee5d6f 100644 --- a/skills/create-payment-credential/SKILL.md +++ b/skills/create-payment-credential/SKILL.md @@ -200,7 +200,7 @@ link-cli spend-request retrieve --include card --output-file /tmp/link-card link-cli mpp pay --spend-request-id [--method POST] [--data '{"amount":100}'] [--header 'Name: Value'] ``` -`mpp pay` handles the full flow automatically: if the merchant returns **403** (bot protection), it fetches Web Bot Auth headers and retries transparently; if it then returns **402**, it parses the `www-authenticate` header, builds the `Authorization: Payment` credential using the SPT, and retries. No manual `web-bot-auth sign` call is needed when using `mpp pay`. +`mpp pay` handles the full 402 flow automatically: probes the URL, parses the `www-authenticate` header, builds the `Authorization: Payment` credential using the SPT, and retries. ## Important @@ -224,7 +224,6 @@ All errors are output as JSON with `code` and `message` fields, with exit code 1 | Spend request approved but payment fails immediately | Wrong credential type for the merchant (e.g. `card` on a 402-only endpoint) | Go back to Step 2, re-evaluate the merchant, create a new spend request with the correct `credential_type` | | Auth token expired mid-session (exit code 1 during approval polling) | Token refresh failure during background polling | Re-authenticate with `auth login`, then retrieve the existing spend request or resume polling. Only create a new spend request if the original one expired, was denied, was canceled, or its shared payment token was already consumed | | 403 when browsing merchant site in Step 2 | Bot protection (Cloudflare/Vercel) blocking automated requests | Run `link-cli web-bot-auth sign ` and attach the returned `Signature` and `Signature-Input` headers to your browsing requests | -| `Received 403 before and after Web Bot Auth retry` from `mpp pay` | Merchant returns 403 for a reason unrelated to bot protection (auth, geo-block, etc.) | Cannot proceed with this URL — report to the user that the merchant is blocking access | ## Further docs