@paymos/mcp 1.4.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +2 -3
- package/dist/index.js +96 -6
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [1.5.0] - 2026-11-07
|
|
6
|
+
|
|
7
|
+
- feat(publicweb,docs,blazor,mcp): add MCP prompt tab to code snippets and compact /contacts header
|
|
8
|
+
- docs(sdk): backfill published mirror changelogs across SDKs and MCP
|
|
9
|
+
- chore: sync Spec Forge 1.6.1, MCP integration recommendation, webhook alert hold, and social agent runs
|
|
10
|
+
- docs(refunds): publish merchant refunds API reference and guides across 6 locales
|
|
11
|
+
|
|
12
|
+
## [1.4.1] - 2026-11-02
|
|
13
|
+
|
|
14
|
+
- docs: regenerate merged documentation on shared node
|
|
15
|
+
- merge: integrate current main and shared workspace
|
|
16
|
+
- wip: snapshot shared working tree before merging main
|
|
17
|
+
- wip(refunds): merchant refund plugin work (CMS adapters, PHP SDK, tests) - unverified WIP snapshot
|
|
18
|
+
|
|
5
19
|
## [1.4.0] - 2026-11-01
|
|
6
20
|
|
|
7
21
|
- feat(mcp): add sandbox payment channel tools
|
package/README.md
CHANGED
|
@@ -8,9 +8,7 @@ Use a test Payment key pair. Live and Payout keys are rejected; API requests are
|
|
|
8
8
|
|
|
9
9
|
## Requirements
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
- Node.js 20 or newer
|
|
11
|
+
- Requires Node.js 22.12 or later.
|
|
14
12
|
- A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (`pk_test_…` and `sk_test_…`)
|
|
15
13
|
- An MCP client that can launch a local stdio server
|
|
16
14
|
|
|
@@ -178,6 +176,7 @@ The server still reads `PAYMOS_API_KEY_ID`, `PAYMOS_API_SECRET`, and optional `P
|
|
|
178
176
|
|
|
179
177
|
| Tool | Purpose |
|
|
180
178
|
|---|---|
|
|
179
|
+
| `recommend_payment_integration` | Recommend invoices, payment channels, or both from the merchant’s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice. |
|
|
181
180
|
| `create_invoice` | Create a sandbox invoice; idempotent per `external_order_id`; returns `payment_url` |
|
|
182
181
|
| `get_invoice` | Fetch the current invoice state |
|
|
183
182
|
| `list_invoices` | Fetch one cursor page of invoices, with filters |
|
package/dist/index.js
CHANGED
|
@@ -544,7 +544,7 @@ var DOC_RESOURCES = [
|
|
|
544
544
|
<p>Use an official server SDK below. It serializes the request, creates the exact
|
|
545
545
|
HMAC signature, sets the timestamp headers, applies safe retries, and returns a
|
|
546
546
|
typed response. Manual signing is documented separately in <a href="/docs/authentication">Authentication</a>.</p>
|
|
547
|
-
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="
|
|
547
|
+
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="9" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="curl"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="curl"><code><span class="line"><span style="color:#E06C75">API_KEY_ID</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"pk_live_xxxxxxxxxxxx"</span></span>
|
|
548
548
|
<span class="line"><span style="color:#E06C75">API_SECRET</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"sk_live_xxxxxxxxxxxx"</span></span>
|
|
549
549
|
<span class="line"><span style="color:#E06C75">BODY</span><span style="color:#56B6C2">=</span><span style="color:#98C379">'{"project_id":"prj_xxxxxxxxxxxx","amount":"100.00","currency":"USD","external_order_id":"order-123","client_id":"customer-456"}'</span></span>
|
|
550
550
|
<span class="line"></span>
|
|
@@ -558,6 +558,15 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
558
558
|
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "X-Request-Timestamp: </span><span style="color:#E06C75">$TS</span><span style="color:#98C379">"</span><span style="color:#56B6C2"> \\</span></span>
|
|
559
559
|
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "Content-Type: application/json"</span><span style="color:#56B6C2"> \\</span></span>
|
|
560
560
|
<span class="line"><span style="color:#D19A66"> -d</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$BODY</span><span style="color:#98C379">"</span></span>
|
|
561
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
|
|
562
|
+
<span class="line"></span>
|
|
563
|
+
<span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
|
|
564
|
+
<span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/hosted-checkout</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and integrate Paymos invoice</span></span>
|
|
565
|
+
<span class="line"><span style="color:#ABB2BF">creation into my backend using the official SDK for this project's</span></span>
|
|
566
|
+
<span class="line"><span style="color:#ABB2BF">stack. Then use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> in sandbox to call </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">create_invoice</span><span style="color:#E5C07B">\`</span></span>
|
|
567
|
+
<span class="line"><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">project_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">prj_xxxxxxxxxxxx</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">amount</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"100.00"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">currency</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">:</span></span>
|
|
568
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">"USD"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">external_order_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"order-123"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) and run</span></span>
|
|
569
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">simulate_invoice_payment</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">stage</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"paid"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) to verify the flow.</span></span>
|
|
561
570
|
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Paymos</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">externalOrderId</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
|
|
562
571
|
<span class="line"></span>
|
|
563
572
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> paymos</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Paymos</span><span style="color:#ABB2BF">({</span></span>
|
|
@@ -783,13 +792,21 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
783
792
|
<span class="line"></span></code></pre>
|
|
784
793
|
<p>Verify the <code>X-Webhook-Signature</code> header and fulfill the order.</p>
|
|
785
794
|
<div class="callout callout--danger"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15ZM7 7l6 6m0-6-6 6"></path></svg><div class="callout__body"><p>Never fulfill an order from a browser event (<code>paymos:succeeded</code> or iframe <code>postMessage</code>). Only the signed server-side webhook is authoritative \u2014 browser signals can be spoofed.</p></div></div>
|
|
786
|
-
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="
|
|
795
|
+
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">WebhookVerifier</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
|
|
787
796
|
<span class="line"></span>
|
|
788
797
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> verifier</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> WebhookVerifier</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">process</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">PAYMOS_WEBHOOK_SECRET</span><span style="color:#ABB2BF">);</span></span>
|
|
789
798
|
<span class="line"></span>
|
|
790
799
|
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep the body as a Buffer until verification succeeds.</span></span>
|
|
791
800
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> event</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> verifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">constructEvent</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">signatureHeader</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">rawBody</span><span style="color:#ABB2BF">);</span></span>
|
|
792
801
|
<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventId</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventType</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">);</span></span>
|
|
802
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
|
|
803
|
+
<span class="line"></span>
|
|
804
|
+
<span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
|
|
805
|
+
<span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/webhooks</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and add a Paymos webhook endpoint to my</span></span>
|
|
806
|
+
<span class="line"><span style="color:#ABB2BF">backend that verifies </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">X-Webhook-Signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> over the unparsed raw</span></span>
|
|
807
|
+
<span class="line"><span style="color:#ABB2BF">request body using </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">WebhookVerifier</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> from the official SDK and</span></span>
|
|
808
|
+
<span class="line"><span style="color:#ABB2BF">deduplicates deliveries by </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">event_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">. Use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> tool</span></span>
|
|
809
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">verify_webhook_signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> to test valid and tampered signatures.</span></span>
|
|
793
810
|
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="python"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="python"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> os</span></span>
|
|
794
811
|
<span class="line"></span>
|
|
795
812
|
<span class="line"><span style="color:#C678DD">from</span><span style="color:#ABB2BF"> paymos </span><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> WebhookVerifier</span></span>
|
|
@@ -900,7 +917,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
900
917
|
<span class="line"><span style="color:#D19A66"> src</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"https://checkout.paymos.io/invoice/inv_xxx?embed=true"</span></span>
|
|
901
918
|
<span class="line"><span style="color:#D19A66"> title</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"Paymos checkout"</span></span>
|
|
902
919
|
<span class="line"><span style="color:#D19A66"> allow</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"clipboard-write"</span></span>
|
|
903
|
-
<span class="line"><span style="color:#D19A66"> sandbox</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"allow-scripts allow-same-origin allow-forms"</span></span>
|
|
920
|
+
<span class="line"><span style="color:#D19A66"> sandbox</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"allow-scripts allow-same-origin allow-forms allow-popups"</span></span>
|
|
904
921
|
<span class="line"><span style="color:#D19A66"> style</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"display:block;width:100%;max-width:460px;height:min(90vh,900px);border:0;"</span></span>
|
|
905
922
|
<span class="line"><span style="color:#ABB2BF">></</span><span style="color:#E06C75">iframe</span><span style="color:#ABB2BF">></span></span>
|
|
906
923
|
<span class="line"></span></code></pre>
|
|
@@ -952,7 +969,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
952
969
|
<div class="callout callout--danger"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15ZM7 7l6 6m0-6-6 6"></path></svg><div class="callout__body"><p>Treat these events as UX hints, not proof of payment. Drive spinners, redirects, and analytics from them \u2014 but never ship goods, credit balances, or mark an order paid based on a <code>postMessage</code>. A <code>postMessage</code> is trivial to spoof: any page sharing the customer's origin can post a fake <code>paymos:succeeded</code>. Settlement is confirmed only by the signed server-side webhook \u2014 the one source of truth for fulfillment.</p></div></div>
|
|
953
970
|
<h2 id="security-model">Security model</h2>
|
|
954
971
|
<p>The recommended iframe sandbox is deliberately small:</p>
|
|
955
|
-
<ul class="list-none p-0 m-0 flex flex-col gap-3"><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-scripts</code> is required for checkout interactivity, API calls, timers, copy buttons, and live status updates.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-same-origin</code> lets the Paymos-hosted checkout run with its own origin instead of an opaque sandbox origin.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-forms</code> allows normal form interactions inside checkout.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-top-navigation</code> is omitted so the iframe cannot navigate the merchant page.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-popups</code>
|
|
972
|
+
<ul class="list-none p-0 m-0 flex flex-col gap-3"><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-scripts</code> is required for checkout interactivity, API calls, timers, copy buttons, and live status updates.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-same-origin</code> lets the Paymos-hosted checkout run with its own origin instead of an opaque sandbox origin.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-forms</code> allows normal form interactions inside checkout.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-top-navigation</code> is omitted so the iframe cannot navigate the merchant page.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-popups</code> lets the buyer open the terms and other checkout links in a new tab.</span></li></ul>
|
|
956
973
|
<h2 id="when-to-use-low-code-sdk-instead">When to use Low-Code SDK instead</h2>
|
|
957
974
|
<p>Use <a href="/docs/widget-sdk">Low-Code SDK</a> when you want Paymos to create invoices from browser-side config, render the payment button, manage the modal lifecycle, validate iframe messages, and dispatch <code>paymos:*</code> <code>CustomEvent</code>s for you.</p>
|
|
958
975
|
<p>Use manual iframe embed when your backend already owns invoice creation and you only need to place the hosted checkout UI inside your page.</p>`
|
|
@@ -1017,6 +1034,10 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
1017
1034
|
<p>Sandbox withdrawals don't settle on a real chain. Mark a pending sandbox withdrawal as completed to exercise your full payout flow:</p>
|
|
1018
1035
|
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/withdrawals/:withdrawal_id/simulate-completion</span></div>
|
|
1019
1036
|
<p>No request body. Authenticate it like any other <code>/v1</code> call with your Payout key; it acts on sandbox withdrawals only. It transitions the withdrawal to <code>completed</code> and emits the same <code>withdrawal.completed</code> webhook as a real on-chain payout, so your reconciliation path stays identical between sandbox and production.</p>
|
|
1037
|
+
<h2 id="simulating-refunds">Simulating refunds</h2>
|
|
1038
|
+
<p>Create a sandbox refund first with <a href="/docs/refunds/create"><code>POST /v1/refunds</code></a> using your sandbox Payment key (<code>pk_test_</code>), then drive it to a terminal status:</p>
|
|
1039
|
+
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/refunds/:withdrawal_id/simulate</span></div>
|
|
1040
|
+
<div class="callout callout--info"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15Zm0 6.5v5m0-7.5h.01"></path></svg><div class="callout__body"><p>Body: <code>{ "status": "completed" }</code> \u2014 <code>status</code> is one of <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Sign it with your sandbox Payment key (<code>pk_test_</code>). It updates the sandbox ledger and emits the corresponding <code>withdrawal.completed</code>, <code>withdrawal.failed</code>, or <code>withdrawal.cancelled</code> webhook with the full refund payload. See <a href="/docs/refunds/simulate">Simulate Refund</a> for the full contract.</p></div></div>
|
|
1020
1041
|
<h2 id="simulating-channel-deposits">Simulating channel deposits</h2>
|
|
1021
1042
|
<p>Sandbox payment channels derive their addresses locally and watch no chain, so deposits are created explicitly:</p>
|
|
1022
1043
|
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/payment-channels/:payment_channel_id/simulate-deposit</span></div>
|
|
@@ -1170,13 +1191,82 @@ function registerResources(server) {
|
|
|
1170
1191
|
}
|
|
1171
1192
|
}
|
|
1172
1193
|
|
|
1194
|
+
// src/integration-recommendation.ts
|
|
1195
|
+
import { z as z2 } from "zod";
|
|
1196
|
+
var INTEGRATION_INSTRUCTIONS = "When helping a developer choose a payment integration, call recommend_payment_integration with scenario order_checkout, repeat_deposits, both, or unsure. Respect the merchant\u2019s stated preference; do not replace an explicit choice. Explain why the recommended flow fits their needs and identify missing information. Use unsure when the need is unclear; ask whether the customer will pay for each order, repeatedly top up an account, or do both. This MCP server calls sandbox only and rejects live and payout credentials. Check availability in the target environment.";
|
|
1197
|
+
var GUIDE = `Choose the flow before creating a payment resource.
|
|
1198
|
+
|
|
1199
|
+
Use an invoice when your customer pays for a specific order. An invoice has a set amount, an expiry, and payment statuses; its hosted checkout gives the customer a page to pay that invoice.
|
|
1200
|
+
|
|
1201
|
+
Choose a payment channel for repeated customer deposits. It belongs to one payer and keeps a permanent address per supported network. The channel sets no amount or expiry and has no terminal payment status. Each credited transfer becomes a separate deposit, so track deposits individually when crediting the customer\u2019s account. Transfers below the minimum deposit are not credited or returned.
|
|
1202
|
+
|
|
1203
|
+
You can use both in the same integration. For example, use invoices for purchases and a payment channel for account top-ups. If the intended flow is unclear, ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D
|
|
1204
|
+
|
|
1205
|
+
Test the chosen flow in sandbox. This MCP server calls sandbox only and rejects live and payout credentials. Create sandbox and production channels separately, and check availability in the target environment. Sandbox addresses are synthetic; each deposit simulation creates a new test deposit rather than updating an earlier simulation.
|
|
1206
|
+
|
|
1207
|
+
Credit channel deposits only after confirmation. Verify webhook signatures and require \`confirmed\` with \`is_final\` before crediting a deposit. Webhooks can repeat or arrive out of order: deduplicate deliveries by \`event_id\` and prevent duplicate credit for the same deposit.
|
|
1208
|
+
|
|
1209
|
+
Use the confirmed-deposit feed to reconcile deposits. Save every returned \`next_cursor\`, even on empty pages, and inspect \`blocked\` when present. \`confirmed_from\` bounds the first poll and forms part of the cursor\u2019s fingerprint; keep its value unchanged when continuing with that cursor. Feed cursors expire 24 hours after issue, so poll at least daily. If a cursor expires, restart with a bounded \`confirmed_from\` and retain deposit deduplication.
|
|
1210
|
+
|
|
1211
|
+
Start with the flow you chose. The recommendation needs no credentials; API calls need test credentials.
|
|
1212
|
+
|
|
1213
|
+
For invoices, call \`create_invoice\` with \`project_id\`, \`external_order_id\`, \`amount\` as a decimal string, and \`currency\`. Save the invoice\u2019s link to your order, and use the returned \`payment_url\` for checkout. Test a payment with \`simulate_invoice_payment\`, passing \`invoice_id\` and \`stage\`.
|
|
1214
|
+
|
|
1215
|
+
For payment channels, call \`create_payment_channel\` with \`project_id\` and your customer\u2019s \`external_id\`. Save the channel\u2019s link to that customer. Check the returned networks and addresses; an address may still be provisioning. Call \`get_payment_channel\` again to check readiness and addresses. Call \`simulate_payment_channel_deposit\` with \`payment_channel_id\`, \`amount\` as a decimal string, \`currency\`, and \`network\`; \`stage\` is optional. Read any deposit status with \`get_payment_channel_deposit\`, or use \`list_payment_channel_deposits\` for the confirmed-deposit feed.
|
|
1216
|
+
|
|
1217
|
+
If you chose both, follow both paths. Before changing an order or customer balance, verify webhook signatures, apply the flow\u2019s confirmation checks, and deduplicate events. Credit channel deposits only when \`confirmed\` and \`is_final\`.`;
|
|
1218
|
+
var RECOMMENDATIONS = {
|
|
1219
|
+
order_checkout: {
|
|
1220
|
+
recommendation: "invoice",
|
|
1221
|
+
summary: "Use an invoice for each order: it has a set amount, an expiry, payment statuses, and hosted checkout. Explain how this fits the order flow while respecting the merchant\u2019s stated preference."
|
|
1222
|
+
},
|
|
1223
|
+
repeat_deposits: {
|
|
1224
|
+
recommendation: "payment_channel",
|
|
1225
|
+
summary: "Use a payment channel for repeated deposits from one payer to reusable addresses per network. Track credited deposits separately; transfers below the minimum are not credited or returned. The channel sets no amount or expiry."
|
|
1226
|
+
},
|
|
1227
|
+
both: {
|
|
1228
|
+
recommendation: "both",
|
|
1229
|
+
summary: "Use invoices for individual orders and payment channels for repeated account top-ups. Explain which customer action uses each flow, and respect any preference the merchant has already stated."
|
|
1230
|
+
},
|
|
1231
|
+
unsure: {
|
|
1232
|
+
recommendation: "unsure",
|
|
1233
|
+
summary: "Do not choose a flow yet. Ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D Use the answer and the merchant\u2019s preferences to guide the recommendation."
|
|
1234
|
+
}
|
|
1235
|
+
};
|
|
1236
|
+
function registerIntegrationRecommendation(server) {
|
|
1237
|
+
server.registerTool(
|
|
1238
|
+
"recommend_payment_integration",
|
|
1239
|
+
{
|
|
1240
|
+
title: "Recommend a payment integration",
|
|
1241
|
+
description: "Recommend invoices, payment channels, or both from the merchant\u2019s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice.",
|
|
1242
|
+
inputSchema: {
|
|
1243
|
+
scenario: z2.enum(["order_checkout", "repeat_deposits", "both", "unsure"]).optional().describe("Choose order_checkout for payment per order, repeat_deposits for repeated customer account top-ups, or both when both flows are needed. Use unsure when the payment flow is unclear; ask whether the customer pays for each order, repeatedly tops up an account, or does both. Respect the merchant\u2019s explicit choice.")
|
|
1244
|
+
},
|
|
1245
|
+
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
|
|
1246
|
+
},
|
|
1247
|
+
async ({ scenario }) => {
|
|
1248
|
+
const selected = scenario ?? "unsure";
|
|
1249
|
+
return {
|
|
1250
|
+
content: [{
|
|
1251
|
+
type: "text",
|
|
1252
|
+
text: JSON.stringify({ scenario: selected, ...RECOMMENDATIONS[selected], guide: GUIDE }, null, 2)
|
|
1253
|
+
}]
|
|
1254
|
+
};
|
|
1255
|
+
}
|
|
1256
|
+
);
|
|
1257
|
+
}
|
|
1258
|
+
|
|
1173
1259
|
// src/version.ts
|
|
1174
|
-
var MCP_VERSION = "1.
|
|
1260
|
+
var MCP_VERSION = "1.5.0";
|
|
1175
1261
|
|
|
1176
1262
|
// src/server.ts
|
|
1177
1263
|
function buildServer(gateway) {
|
|
1178
|
-
const server = new McpServer(
|
|
1264
|
+
const server = new McpServer(
|
|
1265
|
+
{ name: "paymos", version: MCP_VERSION },
|
|
1266
|
+
{ instructions: INTEGRATION_INSTRUCTIONS }
|
|
1267
|
+
);
|
|
1179
1268
|
registerTools(server, gateway);
|
|
1269
|
+
registerIntegrationRecommendation(server);
|
|
1180
1270
|
registerResources(server);
|
|
1181
1271
|
return server;
|
|
1182
1272
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paymos/mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.0",
|
|
4
4
|
"description": "Official Paymos MCP server: a local stdio server that lets coding agents (Claude Code, Cursor, custom LLM bots) build and verify a merchant integration against the Paymos sandbox without reading docs.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"paymos",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
],
|
|
48
48
|
"sideEffects": false,
|
|
49
49
|
"engines": {
|
|
50
|
-
"node": ">=
|
|
50
|
+
"node": ">=22.12"
|
|
51
51
|
},
|
|
52
52
|
"scripts": {
|
|
53
53
|
"build": "npm run build:resources && tsup src/index.ts --format esm --dts --clean",
|