@paymos/mcp 0.0.0-stage → 1.0.2
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 +25 -0
- package/LICENSE +21 -0
- package/README.md +198 -2
- package/dist/index.d.ts +10 -0
- package/dist/index.js +990 -0
- package/package.json +72 -4
package/dist/index.js
ADDED
|
@@ -0,0 +1,990 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// src/index.ts
|
|
4
|
+
import { realpathSync } from "fs";
|
|
5
|
+
import { pathToFileURL } from "url";
|
|
6
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
7
|
+
|
|
8
|
+
// src/config.ts
|
|
9
|
+
var FLAG_NAMES = /* @__PURE__ */ new Map([
|
|
10
|
+
["--api-key-id", "apiKeyId"],
|
|
11
|
+
["--api-secret", "apiSecret"]
|
|
12
|
+
]);
|
|
13
|
+
function parseFlags(argv) {
|
|
14
|
+
const flags = {};
|
|
15
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
16
|
+
const token = argv[index];
|
|
17
|
+
if (token === void 0 || token === "--") break;
|
|
18
|
+
const equals = token.indexOf("=");
|
|
19
|
+
const head = equals < 0 ? token : token.slice(0, equals);
|
|
20
|
+
const field = FLAG_NAMES.get(head);
|
|
21
|
+
if (!field) continue;
|
|
22
|
+
const value = equals < 0 ? argv[index + 1] : token.slice(equals + 1);
|
|
23
|
+
if (value === void 0) break;
|
|
24
|
+
flags[field] = value;
|
|
25
|
+
if (equals < 0) index += 1;
|
|
26
|
+
}
|
|
27
|
+
return flags;
|
|
28
|
+
}
|
|
29
|
+
function loadCredentials(env, flags) {
|
|
30
|
+
const apiKeyId = (env.PAYMOS_API_KEY_ID ?? flags.apiKeyId ?? "").trim();
|
|
31
|
+
const apiSecret = (env.PAYMOS_API_SECRET ?? flags.apiSecret ?? "").trim();
|
|
32
|
+
const webhookSecret = (env.PAYMOS_WEBHOOK_SECRET ?? "").trim();
|
|
33
|
+
return webhookSecret === "" ? { apiKeyId, apiSecret } : { apiKeyId, apiSecret, webhookSecret };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// src/gateway.ts
|
|
37
|
+
import { Paymos } from "@paymos/sdk";
|
|
38
|
+
|
|
39
|
+
// src/gate.ts
|
|
40
|
+
var SANDBOX_ONLY_CODE = "paymos/sandbox-only";
|
|
41
|
+
var SANDBOX_ONLY_MESSAGE = "Live keys arrive in phase 2. Create a test key pair in Dashboard \u2192 Developers \u2192 API keys.";
|
|
42
|
+
var MISSING_CREDENTIALS_CODE = "paymos/missing-credentials";
|
|
43
|
+
var MISSING_CREDENTIALS_MESSAGE = "No Paymos credentials found. Set the env pair PAYMOS_API_KEY_ID (pk_test_\u2026) and PAYMOS_API_SECRET (sk_test_\u2026) from Dashboard \u2192 Developers \u2192 API keys, or pass --api-key-id / --api-secret.";
|
|
44
|
+
var INVALID_CREDENTIALS_CODE = "paymos/invalid-credentials";
|
|
45
|
+
var INVALID_CREDENTIALS_MESSAGE = "Credentials do not look like a Paymos test pair. Expected PAYMOS_API_KEY_ID to start with pk_test_ and PAYMOS_API_SECRET to start with sk_test_ (Dashboard \u2192 Developers \u2192 API keys).";
|
|
46
|
+
var TEST_KEY_PREFIX = "pk_test_";
|
|
47
|
+
var TEST_SECRET_PREFIX = "sk_test_";
|
|
48
|
+
var FORBIDDEN_PREFIXES = ["pk_live_", "sk_live_", "rk_"];
|
|
49
|
+
function checkCredentials(credentials) {
|
|
50
|
+
if (credentials.apiKeyId === "" && credentials.apiSecret === "") {
|
|
51
|
+
return { ok: false, code: MISSING_CREDENTIALS_CODE, message: MISSING_CREDENTIALS_MESSAGE };
|
|
52
|
+
}
|
|
53
|
+
for (const prefix of FORBIDDEN_PREFIXES) {
|
|
54
|
+
if (credentials.apiKeyId.startsWith(prefix) || credentials.apiSecret.startsWith(prefix)) {
|
|
55
|
+
return { ok: false, code: SANDBOX_ONLY_CODE, message: SANDBOX_ONLY_MESSAGE };
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
if (!credentials.apiKeyId.startsWith(TEST_KEY_PREFIX) || !credentials.apiSecret.startsWith(TEST_SECRET_PREFIX)) {
|
|
59
|
+
return { ok: false, code: INVALID_CREDENTIALS_CODE, message: INVALID_CREDENTIALS_MESSAGE };
|
|
60
|
+
}
|
|
61
|
+
return { ok: true };
|
|
62
|
+
}
|
|
63
|
+
function startupLine(check, apiKeyId) {
|
|
64
|
+
return check.ok ? `[paymos-mcp] sandbox session ready (${apiKeyId.slice(0, TEST_KEY_PREFIX.length + 4)}\u2026)` : `[paymos-mcp] ${check.code}: ${check.message}`;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
// src/errors.ts
|
|
68
|
+
import { ApiError } from "@paymos/sdk";
|
|
69
|
+
var ToolError = class extends Error {
|
|
70
|
+
code;
|
|
71
|
+
constructor(code, message) {
|
|
72
|
+
super(message);
|
|
73
|
+
this.name = "ToolError";
|
|
74
|
+
this.code = code;
|
|
75
|
+
}
|
|
76
|
+
};
|
|
77
|
+
function toolErrorFrom(error) {
|
|
78
|
+
if (error instanceof ToolError) return error;
|
|
79
|
+
if (error instanceof ApiError) {
|
|
80
|
+
const code = error.code === "" ? "api_error" : error.code;
|
|
81
|
+
return new ToolError(`paymos/${code}`, error.message);
|
|
82
|
+
}
|
|
83
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
84
|
+
return new ToolError("paymos/sdk_error", message);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
// src/gateway.ts
|
|
88
|
+
var PaymosGateway = class {
|
|
89
|
+
credentials;
|
|
90
|
+
overrides;
|
|
91
|
+
constructor(credentials, overrides = {}) {
|
|
92
|
+
this.credentials = credentials;
|
|
93
|
+
this.overrides = overrides;
|
|
94
|
+
}
|
|
95
|
+
check() {
|
|
96
|
+
return checkCredentials(this.credentials);
|
|
97
|
+
}
|
|
98
|
+
/** Webhook signing secret for the local `verify_webhook_signature` tool. */
|
|
99
|
+
webhookSecret() {
|
|
100
|
+
return this.credentials.webhookSecret;
|
|
101
|
+
}
|
|
102
|
+
invoices() {
|
|
103
|
+
const check = this.check();
|
|
104
|
+
if (!check.ok) throw new ToolError(check.code, check.message);
|
|
105
|
+
const client = new Paymos({
|
|
106
|
+
apiKey: this.credentials.apiKeyId,
|
|
107
|
+
apiSecret: this.credentials.apiSecret,
|
|
108
|
+
...this.overrides.fetch ? { fetch: this.overrides.fetch } : {}
|
|
109
|
+
});
|
|
110
|
+
return client.invoices;
|
|
111
|
+
}
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
// src/server.ts
|
|
115
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
116
|
+
|
|
117
|
+
// src/tools.ts
|
|
118
|
+
import { z } from "zod";
|
|
119
|
+
import { TimestampSkewError, WebhookVerifier } from "@paymos/sdk";
|
|
120
|
+
|
|
121
|
+
// src/wire-shape.ts
|
|
122
|
+
function toWireShape(value) {
|
|
123
|
+
if (Array.isArray(value)) return value.map(toWireShape);
|
|
124
|
+
if (value === null || typeof value !== "object") return value;
|
|
125
|
+
const out = {};
|
|
126
|
+
for (const [key, item] of Object.entries(value)) {
|
|
127
|
+
out[key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`)] = toWireShape(item);
|
|
128
|
+
}
|
|
129
|
+
return out;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
// src/tools.ts
|
|
133
|
+
var NETWORKS = "TRC20, ERC20, BEP20, POLYGON, ARBITRUM, OPTIMISM, BASE, TON, AVAX, SOL, NEAR, SUI, PLASMA";
|
|
134
|
+
var INVOICE_STATUSES = [
|
|
135
|
+
"awaiting_client",
|
|
136
|
+
"awaiting_payment",
|
|
137
|
+
"confirming",
|
|
138
|
+
"underpaid_waiting",
|
|
139
|
+
"paid",
|
|
140
|
+
"paid_over",
|
|
141
|
+
"underpaid",
|
|
142
|
+
"expired",
|
|
143
|
+
"cancelled"
|
|
144
|
+
];
|
|
145
|
+
var INVOICE_RESULT_HINT = "Returns the invoice in wire form: invoice_id, status, payment_url, order, payment (expected, address, transfers), expires_at. status: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled.";
|
|
146
|
+
function textJson(value) {
|
|
147
|
+
return {
|
|
148
|
+
content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
function failure(error) {
|
|
152
|
+
const toolError = toolErrorFrom(error);
|
|
153
|
+
return {
|
|
154
|
+
isError: true,
|
|
155
|
+
content: [{ type: "text", text: JSON.stringify({ code: toolError.code, message: toolError.message }, null, 2) }]
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
async function guarded(run) {
|
|
159
|
+
try {
|
|
160
|
+
return await run();
|
|
161
|
+
} catch (error) {
|
|
162
|
+
return failure(error);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
function registerTools(server, gateway) {
|
|
166
|
+
server.registerTool(
|
|
167
|
+
"create_invoice",
|
|
168
|
+
{
|
|
169
|
+
title: "Create a sandbox invoice",
|
|
170
|
+
description: "Create a Paymos invoice and get a hosted payment_url the customer opens. Idempotent per project: reuse the same external_order_id and you get the existing invoice back instead of a duplicate. " + INVOICE_RESULT_HINT,
|
|
171
|
+
inputSchema: {
|
|
172
|
+
project_id: z.string().min(1).describe("Project receiving the invoice (prj_\u2026)"),
|
|
173
|
+
amount: z.string().min(1).describe('Decimal string, e.g. "50.00" \u2014 amounts are strings, never floats'),
|
|
174
|
+
currency: z.string().min(2).describe("Fiat code (USD, EUR\u2026) or stablecoin symbol (USDT, USDC\u2026)"),
|
|
175
|
+
network: z.string().optional().describe(
|
|
176
|
+
`Locks the crypto invoice to one network: ${NETWORKS}. Omit to let the customer choose on the payment page`
|
|
177
|
+
),
|
|
178
|
+
external_order_id: z.string().min(1).max(128).describe("Your order identifier (\u2264128 chars); idempotency key per project"),
|
|
179
|
+
allow_multiple_payments: z.boolean().optional().describe("Allow the customer to pay an invoice in several transfers (default true)"),
|
|
180
|
+
customer_fee_percent: z.number().int().min(0).max(100).optional().describe("0\u2013100 service fee percent charged to the customer; overrides the project setting"),
|
|
181
|
+
client_id: z.string().max(200).optional().describe("Your customer reference (\u2264200 chars)")
|
|
182
|
+
}
|
|
183
|
+
},
|
|
184
|
+
async ({
|
|
185
|
+
project_id,
|
|
186
|
+
amount,
|
|
187
|
+
currency,
|
|
188
|
+
network,
|
|
189
|
+
external_order_id,
|
|
190
|
+
allow_multiple_payments,
|
|
191
|
+
customer_fee_percent,
|
|
192
|
+
client_id
|
|
193
|
+
}) => guarded(async () => {
|
|
194
|
+
const invoice = await gateway.invoices().create({
|
|
195
|
+
projectId: project_id,
|
|
196
|
+
amount,
|
|
197
|
+
currency,
|
|
198
|
+
externalOrderId: external_order_id,
|
|
199
|
+
...network !== void 0 ? { network } : {},
|
|
200
|
+
...allow_multiple_payments !== void 0 ? { allowMultiplePayments: allow_multiple_payments } : {},
|
|
201
|
+
...customer_fee_percent !== void 0 ? { customerFeePercent: customer_fee_percent } : {},
|
|
202
|
+
...client_id !== void 0 ? { clientId: client_id } : {}
|
|
203
|
+
});
|
|
204
|
+
return textJson(toWireShape(invoice));
|
|
205
|
+
})
|
|
206
|
+
);
|
|
207
|
+
server.registerTool(
|
|
208
|
+
"get_invoice",
|
|
209
|
+
{
|
|
210
|
+
title: "Read an invoice",
|
|
211
|
+
description: "Fetch the current state of one Paymos invoice by invoice_id. " + INVOICE_RESULT_HINT,
|
|
212
|
+
inputSchema: {
|
|
213
|
+
invoice_id: z.string().min(1).describe("Invoice identifier (inv_\u2026)")
|
|
214
|
+
}
|
|
215
|
+
},
|
|
216
|
+
async ({ invoice_id }) => guarded(async () => {
|
|
217
|
+
const invoice = await gateway.invoices().get(invoice_id);
|
|
218
|
+
return textJson(toWireShape(invoice));
|
|
219
|
+
})
|
|
220
|
+
);
|
|
221
|
+
server.registerTool(
|
|
222
|
+
"list_invoices",
|
|
223
|
+
{
|
|
224
|
+
title: "List invoices",
|
|
225
|
+
description: "Read one cursor-paginated page of invoices for a project. Filters: status (repeatable), external_order_id, created_from/created_to (Unix seconds). The result carries items[] and next_cursor \u2014 next_cursor is absent on the last page. Poll with the returned cursor; do not guess offsets.",
|
|
226
|
+
inputSchema: {
|
|
227
|
+
project_id: z.string().min(1).describe("Project whose invoices to list (prj_\u2026)"),
|
|
228
|
+
limit: z.number().int().positive().optional().describe("Page size; the server default and maximum apply"),
|
|
229
|
+
cursor: z.string().optional().describe("Cursor from a previous list_invoices response"),
|
|
230
|
+
status: z.array(z.enum(INVOICE_STATUSES)).optional().describe(
|
|
231
|
+
"Repeatable status filter: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled"
|
|
232
|
+
),
|
|
233
|
+
external_order_id: z.string().optional().describe("Filter by your order identifier"),
|
|
234
|
+
created_from: z.number().int().optional().describe("Unix seconds, inclusive lower bound"),
|
|
235
|
+
created_to: z.number().int().optional().describe("Unix seconds, inclusive upper bound")
|
|
236
|
+
}
|
|
237
|
+
},
|
|
238
|
+
async ({ project_id, limit, cursor, status, external_order_id, created_from, created_to }) => guarded(async () => {
|
|
239
|
+
const page = await gateway.invoices().list({
|
|
240
|
+
projectId: project_id,
|
|
241
|
+
...limit !== void 0 ? { limit } : {},
|
|
242
|
+
...cursor !== void 0 ? { cursor } : {},
|
|
243
|
+
...status !== void 0 ? { status } : {},
|
|
244
|
+
...external_order_id !== void 0 ? { externalOrderId: external_order_id } : {},
|
|
245
|
+
...created_from !== void 0 ? { createdFrom: created_from } : {},
|
|
246
|
+
...created_to !== void 0 ? { createdTo: created_to } : {}
|
|
247
|
+
});
|
|
248
|
+
return textJson(toWireShape(page));
|
|
249
|
+
})
|
|
250
|
+
);
|
|
251
|
+
server.registerTool(
|
|
252
|
+
"cancel_invoice",
|
|
253
|
+
{
|
|
254
|
+
title: "Cancel an invoice",
|
|
255
|
+
description: "Cancel an invoice that has not been paid yet; the reason is stored on the record. Invoices in a final status (paid, paid_over, underpaid, expired, cancelled) cannot be cancelled. " + INVOICE_RESULT_HINT,
|
|
256
|
+
inputSchema: {
|
|
257
|
+
invoice_id: z.string().min(1).describe("Invoice identifier (inv_\u2026)"),
|
|
258
|
+
reason: z.string().min(1).max(500).describe("Why the invoice is cancelled (1\u2013500 chars, stored)")
|
|
259
|
+
}
|
|
260
|
+
},
|
|
261
|
+
async ({ invoice_id, reason }) => guarded(async () => {
|
|
262
|
+
const invoice = await gateway.invoices().cancel(invoice_id, reason);
|
|
263
|
+
return textJson(toWireShape(invoice));
|
|
264
|
+
})
|
|
265
|
+
);
|
|
266
|
+
server.registerTool(
|
|
267
|
+
"simulate_invoice_payment",
|
|
268
|
+
{
|
|
269
|
+
title: "Simulate a sandbox payment",
|
|
270
|
+
description: "Sandbox only: drive a test invoice through a payment outcome without touching a blockchain. The server derives the amounts \u2014 never compute money client-side. stage=paid marks it fully paid; overpaid pays more than expected; underpay pays less (invoice lands in underpaid waiting for a top-up); cancel voids it. " + INVOICE_RESULT_HINT,
|
|
271
|
+
inputSchema: {
|
|
272
|
+
invoice_id: z.string().min(1).describe("Test invoice identifier (is_test=true)"),
|
|
273
|
+
stage: z.enum(["paid", "overpaid", "underpay", "cancel"]).describe("Outcome to simulate: paid | overpaid | underpay | cancel")
|
|
274
|
+
}
|
|
275
|
+
},
|
|
276
|
+
async ({ invoice_id, stage }) => guarded(async () => {
|
|
277
|
+
const invoice = await gateway.invoices().simulatePayment(invoice_id, stage);
|
|
278
|
+
return textJson(toWireShape(invoice));
|
|
279
|
+
})
|
|
280
|
+
);
|
|
281
|
+
server.registerTool(
|
|
282
|
+
"verify_webhook_signature",
|
|
283
|
+
{
|
|
284
|
+
title: "Verify a webhook signature",
|
|
285
|
+
description: 'Verify the X-Webhook-Signature header of a Paymos webhook against its raw body, locally (no API call). Header format: t={unix},v1={hmac_hex("{unix}.{payload}")}; during secret rotation two v1= values are present and either may match. Use the raw request body byte-for-byte \u2014 re-serialized JSON breaks the signature.',
|
|
286
|
+
inputSchema: {
|
|
287
|
+
payload: z.string().min(1).describe("The raw webhook body exactly as received"),
|
|
288
|
+
signature_header: z.string().describe("The X-Webhook-Signature header value, e.g. t=1760000000,v1=9f2c\u2026"),
|
|
289
|
+
secret: z.string().optional().describe("Webhook secret (whsec_\u2026); defaults to PAYMOS_WEBHOOK_SECRET"),
|
|
290
|
+
tolerance_seconds: z.number().int().min(0).optional().describe("Max age of the t= timestamp (default 300); older headers are rejected as expired")
|
|
291
|
+
}
|
|
292
|
+
},
|
|
293
|
+
async ({ payload, signature_header, secret, tolerance_seconds }) => {
|
|
294
|
+
const effectiveSecret = secret ?? gateway.webhookSecret();
|
|
295
|
+
if (effectiveSecret === void 0) {
|
|
296
|
+
return textJson({ valid: false, reason: "missing_secret" });
|
|
297
|
+
}
|
|
298
|
+
const verifier = new WebhookVerifier(
|
|
299
|
+
effectiveSecret,
|
|
300
|
+
tolerance_seconds === void 0 ? 300 : tolerance_seconds
|
|
301
|
+
);
|
|
302
|
+
try {
|
|
303
|
+
verifier.assertValid(signature_header, payload);
|
|
304
|
+
return textJson({ valid: true });
|
|
305
|
+
} catch (error) {
|
|
306
|
+
if (error instanceof TimestampSkewError) return textJson({ valid: false, reason: "expired" });
|
|
307
|
+
return textJson({ valid: false, reason: "bad_signature" });
|
|
308
|
+
}
|
|
309
|
+
}
|
|
310
|
+
);
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
// src/generated/resources.ts
|
|
314
|
+
var DOC_RESOURCES = [
|
|
315
|
+
{
|
|
316
|
+
"name": "quick-start",
|
|
317
|
+
"slug": "quick-start",
|
|
318
|
+
"uri": "paymos://docs/quick-start",
|
|
319
|
+
"description": "Paymos quick start: create a test key pair, issue the first invoice, take the first payment.",
|
|
320
|
+
"mimeType": "text/html",
|
|
321
|
+
"text": `<h2 id="create-an-account">Create an account</h2>
|
|
322
|
+
<p>Sign in at <a href="/">paymos.io</a> with an email magic link (or Google / passkey) \u2014 no password to set.</p>
|
|
323
|
+
<h2 id="create-a-project">Create a project</h2>
|
|
324
|
+
<p>Open <a href="/projects/create"><strong>Dashboard \u2192 Projects \u2192 New project</strong></a>, name the project, and enable the asset and network pairs your customers will use.</p>
|
|
325
|
+
<h2 id="get-your-test-api-keys">Get your test API keys</h2>
|
|
326
|
+
<p>Navigate to <a href="/developers/api"><strong>Dashboard \u2192 Developer \u2192 API Keys</strong></a> and generate a test key pair:</p>
|
|
327
|
+
<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><strong>Payment Key</strong> (<code>pk_test_\u2026</code>) \u2014 used to create test invoices and read invoice status</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><strong>API Secret</strong> (<code>sk_test_\u2026</code>) \u2014 used to compute the HMAC-SHA256 request signature (see the warning below)</span></li></ul>
|
|
328
|
+
<div class="callout callout--warning"><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 3 1.7 17h16.6L10 3Zm0 5v4m0 3h.01"></path></svg><div class="callout__body"><p>API Secret never leaves your server. Never send it in headers, query strings, or client code. Never commit it to git \u2014 rotate immediately if it leaks.</p></div></div>
|
|
329
|
+
<h2 id="register-a-test-webhook-endpoint">Register a test webhook endpoint</h2>
|
|
330
|
+
<p>Expose your server's webhook handler at an HTTPS URL, then open <a href="/developers/webhooks"><strong>Dashboard \u2192 Developer \u2192 Webhooks</strong></a> in Sandbox and create an endpoint. Enter the HTTPS callback URL, select the <code>Invoice</code> category and your project, then create the endpoint. Copy the one-time <code>whsec_test_\u2026</code> secret to your server; it is separate from the API key pair and signs test webhook deliveries.</p>
|
|
331
|
+
<h2 id="create-a-test-invoice">Create a test invoice</h2>
|
|
332
|
+
<p>Use an official server SDK below. It serializes the request, creates the exact
|
|
333
|
+
HMAC signature, sets the timestamp headers, applies safe retries, and returns a
|
|
334
|
+
typed response. Manual signing is documented separately in <a href="/docs/authentication">Authentication</a>.</p>
|
|
335
|
+
<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="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="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>
|
|
336
|
+
<span class="line"><span style="color:#E06C75">API_SECRET</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"sk_live_xxxxxxxxxxxx"</span></span>
|
|
337
|
+
<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>
|
|
338
|
+
<span class="line"></span>
|
|
339
|
+
<span class="line"><span style="color:#E06C75">TS</span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF">$(</span><span style="color:#61AFEF">date</span><span style="color:#98C379"> +%s</span><span style="color:#ABB2BF">)</span></span>
|
|
340
|
+
<span class="line"><span style="color:#E06C75">BODY_HASH</span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF">$(</span><span style="color:#56B6C2">printf</span><span style="color:#98C379"> '%s'</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$BODY</span><span style="color:#98C379">"</span><span style="color:#ABB2BF"> | </span><span style="color:#61AFEF">openssl</span><span style="color:#98C379"> dgst</span><span style="color:#D19A66"> -sha256</span><span style="color:#D19A66"> -hex</span><span style="color:#ABB2BF"> | </span><span style="color:#61AFEF">sed</span><span style="color:#98C379"> 's/^.* //'</span><span style="color:#ABB2BF">)</span></span>
|
|
341
|
+
<span class="line"><span style="color:#E06C75">SIGNATURE</span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF">$(</span><span style="color:#56B6C2">printf</span><span style="color:#98C379"> '%s\\n%s\\n%s\\n%s\\n%s'</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$TS</span><span style="color:#98C379">"</span><span style="color:#98C379"> POST</span><span style="color:#98C379"> /v1/invoices</span><span style="color:#98C379"> ''</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$BODY_HASH</span><span style="color:#98C379">"</span><span style="color:#56B6C2"> \\</span></span>
|
|
342
|
+
<span class="line"><span style="color:#ABB2BF"> | </span><span style="color:#61AFEF">openssl</span><span style="color:#98C379"> dgst</span><span style="color:#D19A66"> -sha256</span><span style="color:#D19A66"> -hmac</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$API_SECRET</span><span style="color:#98C379">"</span><span style="color:#D19A66"> -binary</span><span style="color:#ABB2BF"> | </span><span style="color:#61AFEF">base64</span><span style="color:#ABB2BF">)</span></span>
|
|
343
|
+
<span class="line"></span>
|
|
344
|
+
<span class="line"><span style="color:#61AFEF">curl</span><span style="color:#D19A66"> -sS</span><span style="color:#98C379"> https://api.paymos.io/v1/invoices</span><span style="color:#56B6C2"> \\</span></span>
|
|
345
|
+
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "Authorization: HMAC-SHA256 </span><span style="color:#E06C75">$API_KEY_ID</span><span style="color:#98C379">:</span><span style="color:#E06C75">$SIGNATURE</span><span style="color:#98C379">"</span><span style="color:#56B6C2"> \\</span></span>
|
|
346
|
+
<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>
|
|
347
|
+
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "Content-Type: application/json"</span><span style="color:#56B6C2"> \\</span></span>
|
|
348
|
+
<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>
|
|
349
|
+
<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>
|
|
350
|
+
<span class="line"></span>
|
|
351
|
+
<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>
|
|
352
|
+
<span class="line"><span style="color:#E06C75"> apiKey</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_API_KEY</span><span style="color:#ABB2BF">,</span></span>
|
|
353
|
+
<span class="line"><span style="color:#E06C75"> apiSecret</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_API_SECRET</span><span style="color:#ABB2BF">,</span></span>
|
|
354
|
+
<span class="line"><span style="color:#ABB2BF">});</span></span>
|
|
355
|
+
<span class="line"></span>
|
|
356
|
+
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> invoice</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> await</span><span style="color:#E5C07B"> paymos</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">invoices</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">({</span></span>
|
|
357
|
+
<span class="line"><span style="color:#E06C75"> projectId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'prj_xxxxxxxxxxxx'</span><span style="color:#ABB2BF">,</span></span>
|
|
358
|
+
<span class="line"><span style="color:#E06C75"> amount</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'100.00'</span><span style="color:#ABB2BF">,</span></span>
|
|
359
|
+
<span class="line"><span style="color:#E06C75"> currency</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'USD'</span><span style="color:#ABB2BF">,</span></span>
|
|
360
|
+
<span class="line"><span style="color:#E06C75"> externalOrderId</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">externalOrderId</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'order'</span><span style="color:#ABB2BF">),</span></span>
|
|
361
|
+
<span class="line"><span style="color:#E06C75"> clientId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">'customer-456'</span><span style="color:#ABB2BF">,</span></span>
|
|
362
|
+
<span class="line"><span style="color:#ABB2BF">});</span></span>
|
|
363
|
+
<span class="line"></span>
|
|
364
|
+
<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">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">invoiceId</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">paymentUrl</span><span style="color:#ABB2BF">);</span></span>
|
|
365
|
+
<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>
|
|
366
|
+
<span class="line"></span>
|
|
367
|
+
<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"> Paymos</span></span>
|
|
368
|
+
<span class="line"></span>
|
|
369
|
+
<span class="line"><span style="color:#ABB2BF">paymos </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> Paymos</span><span style="color:#ABB2BF">(</span></span>
|
|
370
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> api_key</span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF">os.environ[</span><span style="color:#98C379">"PAYMOS_API_KEY"</span><span style="color:#ABB2BF">],</span></span>
|
|
371
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> api_secret</span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF">os.environ[</span><span style="color:#98C379">"PAYMOS_API_SECRET"</span><span style="color:#ABB2BF">],</span></span>
|
|
372
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
373
|
+
<span class="line"><span style="color:#ABB2BF">invoice </span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF"> paymos.invoices.</span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">(</span></span>
|
|
374
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> project_id</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"prj_xxxxxxxxxxxx"</span><span style="color:#ABB2BF">,</span></span>
|
|
375
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> amount</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
376
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> currency</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">,</span></span>
|
|
377
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> external_order_id</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">,</span></span>
|
|
378
|
+
<span class="line"><span style="color:#E06C75;font-style:italic"> client_id</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">,</span></span>
|
|
379
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
380
|
+
<span class="line"></span>
|
|
381
|
+
<span class="line"><span style="color:#56B6C2">print</span><span style="color:#ABB2BF">(invoice[</span><span style="color:#98C379">"invoice_id"</span><span style="color:#ABB2BF">], invoice[</span><span style="color:#98C379">"payment_url"</span><span style="color:#ABB2BF">])</span></span>
|
|
382
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="php"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="php"><code><span class="line"><span style="color:#56B6C2"><</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">php</span></span>
|
|
383
|
+
<span class="line"><span style="color:#C678DD">use</span><span style="color:#ABB2BF"> Paymos\\</span><span style="color:#E5C07B">Client</span><span style="color:#ABB2BF">;</span></span>
|
|
384
|
+
<span class="line"><span style="color:#C678DD">use</span><span style="color:#ABB2BF"> Paymos\\</span><span style="color:#E5C07B">ClientConfig</span><span style="color:#ABB2BF">;</span></span>
|
|
385
|
+
<span class="line"><span style="color:#C678DD">use</span><span style="color:#ABB2BF"> Paymos\\</span><span style="color:#E5C07B">IdempotencyKey</span><span style="color:#ABB2BF">;</span></span>
|
|
386
|
+
<span class="line"></span>
|
|
387
|
+
<span class="line"><span style="color:#E06C75">$paymos</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#E5C07B"> Client</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">new</span><span style="color:#E5C07B"> ClientConfig</span><span style="color:#ABB2BF">(</span></span>
|
|
388
|
+
<span class="line"><span style="color:#56B6C2"> getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_API_KEY'</span><span style="color:#ABB2BF">),</span></span>
|
|
389
|
+
<span class="line"><span style="color:#56B6C2"> getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_API_SECRET'</span><span style="color:#ABB2BF">)</span></span>
|
|
390
|
+
<span class="line"><span style="color:#ABB2BF">));</span></span>
|
|
391
|
+
<span class="line"><span style="color:#E06C75">$invoice</span><span style="color:#56B6C2"> =</span><span style="color:#E06C75"> $paymos</span><span style="color:#ABB2BF">-></span><span style="color:#61AFEF">invoices</span><span style="color:#ABB2BF">()-></span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">(</span><span style="color:#56B6C2">array</span><span style="color:#ABB2BF">(</span></span>
|
|
392
|
+
<span class="line"><span style="color:#98C379"> 'project_id'</span><span style="color:#ABB2BF"> => </span><span style="color:#98C379">'prj_xxxxxxxxxxxx'</span><span style="color:#ABB2BF">,</span></span>
|
|
393
|
+
<span class="line"><span style="color:#98C379"> 'amount'</span><span style="color:#ABB2BF"> => </span><span style="color:#98C379">'100.00'</span><span style="color:#ABB2BF">,</span></span>
|
|
394
|
+
<span class="line"><span style="color:#98C379"> 'currency'</span><span style="color:#ABB2BF"> => </span><span style="color:#98C379">'USD'</span><span style="color:#ABB2BF">,</span></span>
|
|
395
|
+
<span class="line"><span style="color:#98C379"> 'external_order_id'</span><span style="color:#ABB2BF"> => </span><span style="color:#E5C07B">IdempotencyKey</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">externalOrderId</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'order'</span><span style="color:#ABB2BF">),</span></span>
|
|
396
|
+
<span class="line"><span style="color:#98C379"> 'client_id'</span><span style="color:#ABB2BF"> => </span><span style="color:#98C379">'customer-456'</span><span style="color:#ABB2BF">,</span></span>
|
|
397
|
+
<span class="line"><span style="color:#ABB2BF">));</span></span>
|
|
398
|
+
<span class="line"></span>
|
|
399
|
+
<span class="line"><span style="color:#56B6C2">echo</span><span style="color:#E06C75"> $invoice</span><span style="color:#ABB2BF">[</span><span style="color:#98C379">'invoice_id'</span><span style="color:#ABB2BF">] </span><span style="color:#ABB2BF">.</span><span style="color:#98C379"> ' '</span><span style="color:#ABB2BF"> .</span><span style="color:#E06C75"> $invoice</span><span style="color:#ABB2BF">[</span><span style="color:#98C379">'payment_url'</span><span style="color:#ABB2BF">];</span></span>
|
|
400
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="go"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="go"><code><span class="line"><span style="color:#C678DD">package</span><span style="color:#E5C07B"> main</span></span>
|
|
401
|
+
<span class="line"></span>
|
|
402
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> (</span></span>
|
|
403
|
+
<span class="line"><span style="color:#98C379"> "context"</span></span>
|
|
404
|
+
<span class="line"><span style="color:#98C379"> "fmt"</span></span>
|
|
405
|
+
<span class="line"><span style="color:#98C379"> "os"</span></span>
|
|
406
|
+
<span class="line"></span>
|
|
407
|
+
<span class="line"><span style="color:#E06C75"> paymos</span><span style="color:#98C379"> "github.com/Paymos-labs/go-sdk/v2"</span></span>
|
|
408
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
409
|
+
<span class="line"></span>
|
|
410
|
+
<span class="line"><span style="color:#C678DD">func</span><span style="color:#61AFEF"> main</span><span style="color:#ABB2BF">() {</span></span>
|
|
411
|
+
<span class="line"><span style="color:#E06C75"> client</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">err</span><span style="color:#E5C07B"> :=</span><span style="color:#E06C75"> paymos</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">NewClient</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">os</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_KEY"</span><span style="color:#ABB2BF">), </span><span style="color:#E06C75">os</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_SECRET"</span><span style="color:#ABB2BF">))</span></span>
|
|
412
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#E06C75"> err</span><span style="color:#56B6C2"> !=</span><span style="color:#D19A66"> nil</span><span style="color:#ABB2BF"> {</span></span>
|
|
413
|
+
<span class="line"><span style="color:#61AFEF"> panic</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">err</span><span style="color:#ABB2BF">)</span></span>
|
|
414
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
415
|
+
<span class="line"><span style="color:#E06C75"> invoice</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">err</span><span style="color:#E5C07B"> :=</span><span style="color:#E06C75"> client</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">Invoices</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Create</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">context</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Background</span><span style="color:#ABB2BF">(), </span><span style="color:#E5C07B">paymos</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">CreateInvoiceParams</span><span style="color:#ABB2BF">{</span></span>
|
|
416
|
+
<span class="line"><span style="color:#E06C75"> ProjectID</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"prj_xxxxxxxxxxxx"</span><span style="color:#ABB2BF">,</span></span>
|
|
417
|
+
<span class="line"><span style="color:#E06C75"> Amount</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
418
|
+
<span class="line"><span style="color:#E06C75"> Currency</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">,</span></span>
|
|
419
|
+
<span class="line"><span style="color:#E06C75"> ExternalOrderID</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">,</span></span>
|
|
420
|
+
<span class="line"><span style="color:#E06C75"> ClientID</span><span style="color:#ABB2BF">: </span><span style="color:#61AFEF">stringPointer</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">),</span></span>
|
|
421
|
+
<span class="line"><span style="color:#ABB2BF"> })</span></span>
|
|
422
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#E06C75"> err</span><span style="color:#56B6C2"> !=</span><span style="color:#D19A66"> nil</span><span style="color:#ABB2BF"> {</span></span>
|
|
423
|
+
<span class="line"><span style="color:#61AFEF"> panic</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">err</span><span style="color:#ABB2BF">)</span></span>
|
|
424
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
425
|
+
<span class="line"><span style="color:#E06C75"> fmt</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Println</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">InvoiceID</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">PaymentURL</span><span style="color:#ABB2BF">)</span></span>
|
|
426
|
+
<span class="line"><span style="color:#ABB2BF">}</span></span>
|
|
427
|
+
<span class="line"></span>
|
|
428
|
+
<span class="line"><span style="color:#C678DD">func</span><span style="color:#61AFEF"> stringPointer</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">value</span><span style="color:#C678DD"> string</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">*</span><span style="color:#C678DD">string</span><span style="color:#ABB2BF"> { </span><span style="color:#C678DD">return</span><span style="color:#C678DD"> &</span><span style="color:#E06C75">value</span><span style="color:#ABB2BF"> }</span></span>
|
|
429
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="csharp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="csharp"><code><span class="line"><span style="color:#C678DD">using</span><span style="color:#E5C07B"> Paymos</span><span style="color:#ABB2BF">;</span></span>
|
|
430
|
+
<span class="line"></span>
|
|
431
|
+
<span class="line"><span style="color:#C678DD">using</span><span style="color:#C678DD"> var</span><span style="color:#E06C75"> paymos</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> new </span><span style="color:#E5C07B">PaymosClient</span><span style="color:#ABB2BF">(</span></span>
|
|
432
|
+
<span class="line"><span style="color:#E5C07B"> Environment</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">GetEnvironmentVariable</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_KEY"</span><span style="color:#ABB2BF">)</span><span style="color:#56B6C2">!</span><span style="color:#ABB2BF">,</span></span>
|
|
433
|
+
<span class="line"><span style="color:#E5C07B"> Environment</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">GetEnvironmentVariable</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_SECRET"</span><span style="color:#ABB2BF">)</span><span style="color:#56B6C2">!</span><span style="color:#ABB2BF">);</span></span>
|
|
434
|
+
<span class="line"></span>
|
|
435
|
+
<span class="line"><span style="color:#C678DD">var</span><span style="color:#E06C75"> invoice</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> await </span><span style="color:#E5C07B">paymos</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">Invoices</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">CreateAsync</span><span style="color:#ABB2BF">(new </span><span style="color:#E5C07B">CreateInvoiceRequest</span><span style="color:#ABB2BF">(</span></span>
|
|
436
|
+
<span class="line"><span style="color:#E5C07B"> ProjectId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"prj_xxxxxxxxxxxx"</span><span style="color:#ABB2BF">,</span></span>
|
|
437
|
+
<span class="line"><span style="color:#E5C07B"> Amount</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
438
|
+
<span class="line"><span style="color:#E5C07B"> Currency</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">,</span></span>
|
|
439
|
+
<span class="line"><span style="color:#E5C07B"> ExternalOrderId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">,</span></span>
|
|
440
|
+
<span class="line"><span style="color:#E5C07B"> ClientId</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">));</span></span>
|
|
441
|
+
<span class="line"></span>
|
|
442
|
+
<span class="line"><span style="color:#E5C07B">Console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">WriteLine</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">$"</span><span style="color:#ABB2BF">{</span><span style="color:#E5C07B">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">InvoiceId</span><span style="color:#ABB2BF">}</span><span style="color:#ABB2BF"> {</span><span style="color:#E5C07B">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">PaymentUrl</span><span style="color:#ABB2BF">}</span><span style="color:#98C379">"</span><span style="color:#ABB2BF">);</span></span>
|
|
443
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="java"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="java"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> io.paymos.CreateInvoiceRequest</span><span style="color:#ABB2BF">;</span></span>
|
|
444
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> io.paymos.Invoice</span><span style="color:#ABB2BF">;</span></span>
|
|
445
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> io.paymos.PaymosClient</span><span style="color:#ABB2BF">;</span></span>
|
|
446
|
+
<span class="line"></span>
|
|
447
|
+
<span class="line"><span style="color:#E5C07B">PaymosClient</span><span style="color:#E06C75"> paymos </span><span style="color:#56B6C2">=</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> PaymosClient</span><span style="color:#E06C75">(</span></span>
|
|
448
|
+
<span class="line"><span style="color:#E5C07B"> System</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_KEY"</span><span style="color:#ABB2BF">),</span></span>
|
|
449
|
+
<span class="line"><span style="color:#E5C07B"> System</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_SECRET"</span><span style="color:#ABB2BF">)</span><span style="color:#E06C75">)</span><span style="color:#ABB2BF">;</span></span>
|
|
450
|
+
<span class="line"></span>
|
|
451
|
+
<span class="line"><span style="color:#E5C07B">Invoice</span><span style="color:#E06C75"> invoice </span><span style="color:#56B6C2">=</span><span style="color:#E5C07B"> paymos</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">invoices</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">(</span></span>
|
|
452
|
+
<span class="line"><span style="color:#E5C07B"> CreateInvoiceRequest</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">builder</span><span style="color:#ABB2BF">()</span></span>
|
|
453
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">projectId</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"prj_xxxxxxxxxxxx"</span><span style="color:#ABB2BF">)</span></span>
|
|
454
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">amount</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">)</span></span>
|
|
455
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">currency</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">)</span></span>
|
|
456
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">externalOrderId</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">)</span></span>
|
|
457
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">clientId</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">)</span></span>
|
|
458
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">build</span><span style="color:#ABB2BF">());</span></span>
|
|
459
|
+
<span class="line"></span>
|
|
460
|
+
<span class="line"><span style="color:#E5C07B">System</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">out</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">println</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">invoice</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">invoiceId</span><span style="color:#ABB2BF">() </span><span style="color:#56B6C2">+</span><span style="color:#98C379"> " "</span><span style="color:#56B6C2"> +</span><span style="color:#E5C07B"> invoice</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">paymentUrl</span><span style="color:#ABB2BF">());</span></span>
|
|
461
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="ruby"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="ruby"><code><span class="line"><span style="color:#61AFEF">require </span><span style="color:#98C379">'paymos'</span></span>
|
|
462
|
+
<span class="line"></span>
|
|
463
|
+
<span class="line"><span style="color:#E06C75">paymos</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> Paymos</span><span style="color:#ABB2BF">::</span><span style="color:#E5C07B">Client</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">new</span><span style="color:#ABB2BF">(</span></span>
|
|
464
|
+
<span class="line"><span style="color:#56B6C2"> api_key</span><span style="color:#D19A66">:</span><span style="color:#E5C07B"> ENV</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">fetch</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_API_KEY'</span><span style="color:#ABB2BF">),</span></span>
|
|
465
|
+
<span class="line"><span style="color:#56B6C2"> api_secret</span><span style="color:#D19A66">:</span><span style="color:#E5C07B"> ENV</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">fetch</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_API_SECRET'</span><span style="color:#ABB2BF">)</span></span>
|
|
466
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
467
|
+
<span class="line"><span style="color:#E06C75">invoice</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> paymos.</span><span style="color:#61AFEF">invoices</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">(</span></span>
|
|
468
|
+
<span class="line"><span style="color:#56B6C2"> project_id</span><span style="color:#D19A66">:</span><span style="color:#98C379"> 'prj_xxxxxxxxxxxx'</span><span style="color:#ABB2BF">,</span></span>
|
|
469
|
+
<span class="line"><span style="color:#56B6C2"> amount</span><span style="color:#D19A66">:</span><span style="color:#98C379"> '100.00'</span><span style="color:#ABB2BF">,</span></span>
|
|
470
|
+
<span class="line"><span style="color:#56B6C2"> currency</span><span style="color:#D19A66">:</span><span style="color:#98C379"> 'USD'</span><span style="color:#ABB2BF">,</span></span>
|
|
471
|
+
<span class="line"><span style="color:#56B6C2"> external_order_id</span><span style="color:#D19A66">:</span><span style="color:#98C379"> 'order-123'</span><span style="color:#ABB2BF">,</span></span>
|
|
472
|
+
<span class="line"><span style="color:#56B6C2"> client_id</span><span style="color:#D19A66">:</span><span style="color:#98C379"> 'customer-456'</span></span>
|
|
473
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
474
|
+
<span class="line"></span>
|
|
475
|
+
<span class="line"><span style="color:#56B6C2">puts</span><span style="color:#98C379"> "</span><span style="color:#C678DD">#{</span><span style="color:#ABB2BF">invoice.</span><span style="color:#61AFEF">invoice_id</span><span style="color:#C678DD">}</span><span style="color:#C678DD"> #{</span><span style="color:#ABB2BF">invoice.</span><span style="color:#61AFEF">payment_url</span><span style="color:#C678DD">}</span><span style="color:#98C379">"</span></span>
|
|
476
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="rust"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="rust"><code><span class="line"><span style="color:#C678DD">use</span><span style="color:#E5C07B"> paymos</span><span style="color:#ABB2BF">::{</span><span style="color:#E5C07B">CreateInvoiceRequest</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">PaymosClient</span><span style="color:#ABB2BF">};</span></span>
|
|
477
|
+
<span class="line"></span>
|
|
478
|
+
<span class="line"><span style="color:#C678DD">let</span><span style="color:#E06C75"> paymos</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> PaymosClient</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">new</span><span style="color:#ABB2BF">(</span></span>
|
|
479
|
+
<span class="line"><span style="color:#E5C07B"> std</span><span style="color:#ABB2BF">::</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">var</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_KEY"</span><span style="color:#ABB2BF">)?,</span></span>
|
|
480
|
+
<span class="line"><span style="color:#E5C07B"> std</span><span style="color:#ABB2BF">::</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">var</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_API_SECRET"</span><span style="color:#ABB2BF">)?,</span></span>
|
|
481
|
+
<span class="line"><span style="color:#ABB2BF">)?;</span></span>
|
|
482
|
+
<span class="line"><span style="color:#C678DD">let</span><span style="color:#E06C75"> invoice</span><span style="color:#56B6C2"> =</span><span style="color:#E06C75"> paymos</span></span>
|
|
483
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">invoices</span><span style="color:#ABB2BF">()</span></span>
|
|
484
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#61AFEF">create</span><span style="color:#ABB2BF">(&</span><span style="color:#E5C07B">CreateInvoiceRequest</span><span style="color:#ABB2BF"> {</span></span>
|
|
485
|
+
<span class="line"><span style="color:#E06C75"> project_id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"prj_xxxxxxxxxxxx"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
486
|
+
<span class="line"><span style="color:#E06C75"> amount</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
487
|
+
<span class="line"><span style="color:#E06C75"> currency</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
488
|
+
<span class="line"><span style="color:#E06C75"> external_order_id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
489
|
+
<span class="line"><span style="color:#E06C75"> network</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
490
|
+
<span class="line"><span style="color:#E06C75"> allow_multiple_payments</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
491
|
+
<span class="line"><span style="color:#E06C75"> customer_fee_percent</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
492
|
+
<span class="line"><span style="color:#E06C75"> client_id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Some</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">()),</span></span>
|
|
493
|
+
<span class="line"><span style="color:#ABB2BF"> })</span></span>
|
|
494
|
+
<span class="line"><span style="color:#ABB2BF"> .</span><span style="color:#C678DD">await</span><span style="color:#ABB2BF">?;</span></span>
|
|
495
|
+
<span class="line"></span>
|
|
496
|
+
<span class="line"><span style="color:#61AFEF">println!</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"{} {}"</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">invoice</span><span style="color:#ABB2BF">.invoice_id, </span><span style="color:#E06C75">invoice</span><span style="color:#ABB2BF">.payment_url);</span></span>
|
|
497
|
+
<span class="line"></span></code></pre></div></div>
|
|
498
|
+
<h2 id="open-checkout">Open checkout</h2>
|
|
499
|
+
<p>The response includes a <code>payment_url</code>. Redirect your customer there or embed the same URL with <code>?embed=true</code>:</p>
|
|
500
|
+
<pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
|
|
501
|
+
<span class="line"><span style="color:#E06C75"> "invoice_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
|
|
502
|
+
<span class="line"><span style="color:#E06C75"> "project_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"prj_xFukZuAJZR06pLVBh3uwzv"</span><span style="color:#ABB2BF">,</span></span>
|
|
503
|
+
<span class="line"><span style="color:#E06C75"> "status"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"awaiting_client"</span><span style="color:#ABB2BF">,</span></span>
|
|
504
|
+
<span class="line"><span style="color:#E06C75"> "is_final"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">false</span><span style="color:#ABB2BF">,</span></span>
|
|
505
|
+
<span class="line"><span style="color:#E06C75"> "is_test"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">,</span></span>
|
|
506
|
+
<span class="line"><span style="color:#E06C75"> "payment_url"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
|
|
507
|
+
<span class="line"><span style="color:#E06C75"> "order"</span><span style="color:#ABB2BF">: {</span></span>
|
|
508
|
+
<span class="line"><span style="color:#E06C75"> "external_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">,</span></span>
|
|
509
|
+
<span class="line"><span style="color:#E06C75"> "client_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">,</span></span>
|
|
510
|
+
<span class="line"><span style="color:#E06C75"> "amount"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
511
|
+
<span class="line"><span style="color:#E06C75"> "currency"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span></span>
|
|
512
|
+
<span class="line"><span style="color:#ABB2BF"> },</span></span>
|
|
513
|
+
<span class="line"><span style="color:#E06C75"> "created_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1743594000</span><span style="color:#ABB2BF">,</span></span>
|
|
514
|
+
<span class="line"><span style="color:#E06C75"> "updated_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1743594000</span><span style="color:#ABB2BF">,</span></span>
|
|
515
|
+
<span class="line"><span style="color:#E06C75"> "expires_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1743597600</span></span>
|
|
516
|
+
<span class="line"><span style="color:#ABB2BF">}</span></span>
|
|
517
|
+
<span class="line"></span></code></pre>
|
|
518
|
+
<p>The customer sees a payment page with the wallet address, QR code, and countdown timer. They can pay with any asset + network enabled on the project \u2014 see <a href="/docs/supported-currencies">Supported Currencies</a>.</p>
|
|
519
|
+
<p>On a Telegram-bot project that same <code>payment_url</code> opens the Paymos bot instead. The payer picks the asset and network there, gets the address and QR code, and follows the status without leaving Telegram \u2014 and without a Paymos account.</p>
|
|
520
|
+
<p>See <a href="/docs/hosted-checkout">Hosted Checkout</a> for redirect mode, iframe embed mode, and browser event handling.</p>
|
|
521
|
+
<h2 id="handle-the-webhook">Handle the webhook</h2>
|
|
522
|
+
<p>When the payment is confirmed, Paymos sends a POST to your registered webhook URL:</p>
|
|
523
|
+
<pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
|
|
524
|
+
<span class="line"><span style="color:#E06C75"> "event_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"evt_J7EEYeL9pZJukfj2c5OQ44"</span><span style="color:#ABB2BF">,</span></span>
|
|
525
|
+
<span class="line"><span style="color:#E06C75"> "event_type"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"invoice.paid"</span><span style="color:#ABB2BF">,</span></span>
|
|
526
|
+
<span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">,</span></span>
|
|
527
|
+
<span class="line"><span style="color:#E06C75"> "occurred_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span><span style="color:#ABB2BF">,</span></span>
|
|
528
|
+
<span class="line"><span style="color:#E06C75"> "data"</span><span style="color:#ABB2BF">: {</span></span>
|
|
529
|
+
<span class="line"><span style="color:#E06C75"> "invoice_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
|
|
530
|
+
<span class="line"><span style="color:#E06C75"> "project_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"prj_xFukZuAJZR06pLVBh3uwzv"</span><span style="color:#ABB2BF">,</span></span>
|
|
531
|
+
<span class="line"><span style="color:#E06C75"> "status"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"paid"</span><span style="color:#ABB2BF">,</span></span>
|
|
532
|
+
<span class="line"><span style="color:#E06C75"> "is_final"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">true</span><span style="color:#ABB2BF">,</span></span>
|
|
533
|
+
<span class="line"><span style="color:#E06C75"> "is_test"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">false</span><span style="color:#ABB2BF">,</span></span>
|
|
534
|
+
<span class="line"><span style="color:#E06C75"> "payment_url"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
|
|
535
|
+
<span class="line"><span style="color:#E06C75"> "order"</span><span style="color:#ABB2BF">: {</span></span>
|
|
536
|
+
<span class="line"><span style="color:#E06C75"> "external_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-12345"</span><span style="color:#ABB2BF">,</span></span>
|
|
537
|
+
<span class="line"><span style="color:#E06C75"> "client_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"customer-67890"</span><span style="color:#ABB2BF">,</span></span>
|
|
538
|
+
<span class="line"><span style="color:#E06C75"> "amount"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"100.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
539
|
+
<span class="line"><span style="color:#E06C75"> "currency"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span></span>
|
|
540
|
+
<span class="line"><span style="color:#ABB2BF"> },</span></span>
|
|
541
|
+
<span class="line"><span style="color:#E06C75"> "payment"</span><span style="color:#ABB2BF">: {</span></span>
|
|
542
|
+
<span class="line"><span style="color:#E06C75"> "currency"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USDT"</span><span style="color:#ABB2BF">,</span></span>
|
|
543
|
+
<span class="line"><span style="color:#E06C75"> "network"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"TRC20"</span><span style="color:#ABB2BF">,</span></span>
|
|
544
|
+
<span class="line"><span style="color:#E06C75"> "chain_id"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">728126428</span><span style="color:#ABB2BF">,</span></span>
|
|
545
|
+
<span class="line"><span style="color:#E06C75"> "contract_address"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"</span><span style="color:#ABB2BF">,</span></span>
|
|
546
|
+
<span class="line"><span style="color:#E06C75"> "expected"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"50.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
547
|
+
<span class="line"><span style="color:#E06C75"> "address"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"</span><span style="color:#ABB2BF">,</span></span>
|
|
548
|
+
<span class="line"><span style="color:#E06C75"> "exchange_rate"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"2.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
549
|
+
<span class="line"><span style="color:#E06C75"> "paid"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"50.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
550
|
+
<span class="line"><span style="color:#E06C75"> "remaining"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"0"</span><span style="color:#ABB2BF">,</span></span>
|
|
551
|
+
<span class="line"><span style="color:#E06C75"> "fee"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"0.50"</span><span style="color:#ABB2BF">,</span></span>
|
|
552
|
+
<span class="line"><span style="color:#E06C75"> "net"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"49.50"</span><span style="color:#ABB2BF">,</span></span>
|
|
553
|
+
<span class="line"><span style="color:#E06C75"> "transfers"</span><span style="color:#ABB2BF">: [</span></span>
|
|
554
|
+
<span class="line"><span style="color:#ABB2BF"> {</span></span>
|
|
555
|
+
<span class="line"><span style="color:#E06C75"> "tx_hash"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"</span><span style="color:#ABB2BF">,</span></span>
|
|
556
|
+
<span class="line"><span style="color:#E06C75"> "amount"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"50.00"</span><span style="color:#ABB2BF">,</span></span>
|
|
557
|
+
<span class="line"><span style="color:#E06C75"> "status"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"confirmed"</span><span style="color:#ABB2BF">,</span></span>
|
|
558
|
+
<span class="line"><span style="color:#E06C75"> "created_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281020</span><span style="color:#ABB2BF">,</span></span>
|
|
559
|
+
<span class="line"><span style="color:#E06C75"> "confirmed_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span><span style="color:#ABB2BF">,</span></span>
|
|
560
|
+
<span class="line"><span style="color:#E06C75"> "required_confirmations"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">19</span><span style="color:#ABB2BF">,</span></span>
|
|
561
|
+
<span class="line"><span style="color:#E06C75"> "estimated_confirmation_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281080</span><span style="color:#ABB2BF">,</span></span>
|
|
562
|
+
<span class="line"><span style="color:#E06C75"> "explorer_url"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"</span></span>
|
|
563
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
564
|
+
<span class="line"><span style="color:#ABB2BF"> ]</span></span>
|
|
565
|
+
<span class="line"><span style="color:#ABB2BF"> },</span></span>
|
|
566
|
+
<span class="line"><span style="color:#E06C75"> "expires_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739284200</span><span style="color:#ABB2BF">,</span></span>
|
|
567
|
+
<span class="line"><span style="color:#E06C75"> "completed_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span><span style="color:#ABB2BF">,</span></span>
|
|
568
|
+
<span class="line"><span style="color:#E06C75"> "created_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739277600</span><span style="color:#ABB2BF">,</span></span>
|
|
569
|
+
<span class="line"><span style="color:#E06C75"> "updated_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span></span>
|
|
570
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
571
|
+
<span class="line"><span style="color:#ABB2BF">}</span></span>
|
|
572
|
+
<span class="line"></span></code></pre>
|
|
573
|
+
<p>Verify the <code>X-Webhook-Signature</code> header and fulfill the order.</p>
|
|
574
|
+
<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>
|
|
575
|
+
<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="2" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="7" 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>
|
|
576
|
+
<span class="line"></span>
|
|
577
|
+
<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>
|
|
578
|
+
<span class="line"></span>
|
|
579
|
+
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep the body as a Buffer until verification succeeds.</span></span>
|
|
580
|
+
<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>
|
|
581
|
+
<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>
|
|
582
|
+
<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>
|
|
583
|
+
<span class="line"></span>
|
|
584
|
+
<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>
|
|
585
|
+
<span class="line"></span>
|
|
586
|
+
<span class="line"><span style="color:#ABB2BF">verifier </span><span style="color:#56B6C2">=</span><span style="color:#61AFEF"> WebhookVerifier</span><span style="color:#ABB2BF">(os.environ[</span><span style="color:#98C379">"PAYMOS_WEBHOOK_SECRET"</span><span style="color:#ABB2BF">])</span></span>
|
|
587
|
+
<span class="line"></span>
|
|
588
|
+
<span class="line"><span style="color:#7F848E;font-style:italic"># Keep raw_body as bytes until verification succeeds.</span></span>
|
|
589
|
+
<span class="line"><span style="color:#ABB2BF">event </span><span style="color:#56B6C2">=</span><span style="color:#ABB2BF"> verifier.</span><span style="color:#61AFEF">construct_event</span><span style="color:#ABB2BF">(signature_header, raw_body)</span></span>
|
|
590
|
+
<span class="line"><span style="color:#56B6C2">print</span><span style="color:#ABB2BF">(event[</span><span style="color:#98C379">"event_id"</span><span style="color:#ABB2BF">], event[</span><span style="color:#98C379">"event_type"</span><span style="color:#ABB2BF">], event[</span><span style="color:#98C379">"data"</span><span style="color:#ABB2BF">])</span></span>
|
|
591
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="php"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="php"><code><span class="line"><span style="color:#56B6C2"><</span><span style="color:#C678DD">?</span><span style="color:#ABB2BF">php</span></span>
|
|
592
|
+
<span class="line"><span style="color:#C678DD">use</span><span style="color:#ABB2BF"> Paymos\\Webhook\\</span><span style="color:#E5C07B">WebhookEvent</span><span style="color:#ABB2BF">;</span></span>
|
|
593
|
+
<span class="line"><span style="color:#C678DD">use</span><span style="color:#ABB2BF"> Paymos\\Webhook\\</span><span style="color:#E5C07B">WebhookVerifier</span><span style="color:#ABB2BF">;</span></span>
|
|
594
|
+
<span class="line"></span>
|
|
595
|
+
<span class="line"><span style="color:#E06C75">$verifier</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#E5C07B"> WebhookVerifier</span><span style="color:#ABB2BF">(</span><span style="color:#56B6C2">getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_WEBHOOK_SECRET'</span><span style="color:#ABB2BF">));</span></span>
|
|
596
|
+
<span class="line"></span>
|
|
597
|
+
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep $rawBody unchanged until verification succeeds.</span></span>
|
|
598
|
+
<span class="line"><span style="color:#E06C75">$payload</span><span style="color:#56B6C2"> =</span><span style="color:#E06C75"> $verifier</span><span style="color:#ABB2BF">-></span><span style="color:#61AFEF">decodeVerifiedPayload</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>
|
|
599
|
+
<span class="line"><span style="color:#E06C75">$event</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#E5C07B"> WebhookEvent</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">$payload</span><span style="color:#ABB2BF">);</span></span>
|
|
600
|
+
<span class="line"><span style="color:#56B6C2">echo</span><span style="color:#E06C75"> $event</span><span style="color:#ABB2BF">-></span><span style="color:#61AFEF">id</span><span style="color:#ABB2BF">() </span><span style="color:#ABB2BF">.</span><span style="color:#98C379"> ' '</span><span style="color:#ABB2BF"> .</span><span style="color:#E06C75"> $event</span><span style="color:#ABB2BF">-></span><span style="color:#61AFEF">type</span><span style="color:#ABB2BF">();</span></span>
|
|
601
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="go"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="go"><code><span class="line"><span style="color:#C678DD">package</span><span style="color:#E5C07B"> main</span></span>
|
|
602
|
+
<span class="line"></span>
|
|
603
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> (</span></span>
|
|
604
|
+
<span class="line"><span style="color:#98C379"> "fmt"</span></span>
|
|
605
|
+
<span class="line"><span style="color:#98C379"> "os"</span></span>
|
|
606
|
+
<span class="line"><span style="color:#98C379"> "time"</span></span>
|
|
607
|
+
<span class="line"></span>
|
|
608
|
+
<span class="line"><span style="color:#E06C75"> paymos</span><span style="color:#98C379"> "github.com/Paymos-labs/go-sdk/v2"</span></span>
|
|
609
|
+
<span class="line"><span style="color:#ABB2BF">)</span></span>
|
|
610
|
+
<span class="line"></span>
|
|
611
|
+
<span class="line"><span style="color:#C678DD">type</span><span style="color:#E5C07B"> invoiceEventData</span><span style="color:#C678DD"> struct</span><span style="color:#ABB2BF"> {</span></span>
|
|
612
|
+
<span class="line"><span style="color:#E06C75"> InvoiceID</span><span style="color:#C678DD"> string</span><span style="color:#98C379"> \`json:"invoice_id"\`</span></span>
|
|
613
|
+
<span class="line"><span style="color:#ABB2BF">}</span></span>
|
|
614
|
+
<span class="line"></span>
|
|
615
|
+
<span class="line"><span style="color:#C678DD">func</span><span style="color:#61AFEF"> handleWebhook</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75;font-style:italic">signatureHeader</span><span style="color:#C678DD"> string</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75;font-style:italic">rawBody</span><span style="color:#ABB2BF"> []</span><span style="color:#C678DD">byte</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">error</span><span style="color:#ABB2BF"> {</span></span>
|
|
616
|
+
<span class="line"><span style="color:#E06C75"> verifier</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">err</span><span style="color:#E5C07B"> :=</span><span style="color:#E06C75"> paymos</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">NewWebhookVerifier</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">os</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_WEBHOOK_SECRET"</span><span style="color:#ABB2BF">), </span><span style="color:#D19A66">5</span><span style="color:#C678DD">*</span><span style="color:#E06C75">time</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">Minute</span><span style="color:#ABB2BF">)</span></span>
|
|
617
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#E06C75"> err</span><span style="color:#56B6C2"> !=</span><span style="color:#D19A66"> nil</span><span style="color:#ABB2BF"> {</span></span>
|
|
618
|
+
<span class="line"><span style="color:#C678DD"> return</span><span style="color:#E06C75"> err</span></span>
|
|
619
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
620
|
+
<span class="line"><span style="color:#C678DD"> var</span><span style="color:#E06C75"> event</span><span style="color:#E5C07B"> paymos</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">WebhookEvent</span><span style="color:#ABB2BF">[</span><span style="color:#E5C07B">invoiceEventData</span><span style="color:#ABB2BF">]</span></span>
|
|
621
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#E06C75"> err</span><span style="color:#E5C07B"> :=</span><span style="color:#E06C75"> 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 style="color:#E06C75">time</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Now</span><span style="color:#ABB2BF">(), </span><span style="color:#C678DD">&</span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">); </span><span style="color:#E06C75">err</span><span style="color:#56B6C2"> !=</span><span style="color:#D19A66"> nil</span><span style="color:#ABB2BF"> {</span></span>
|
|
622
|
+
<span class="line"><span style="color:#C678DD"> return</span><span style="color:#E06C75"> err</span></span>
|
|
623
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
624
|
+
<span class="line"><span style="color:#E06C75"> fmt</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">Println</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">EventID</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">EventType</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">Data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">InvoiceID</span><span style="color:#ABB2BF">)</span></span>
|
|
625
|
+
<span class="line"><span style="color:#C678DD"> return</span><span style="color:#D19A66"> nil</span></span>
|
|
626
|
+
<span class="line"><span style="color:#ABB2BF">}</span></span>
|
|
627
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="csharp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="csharp"><code><span class="line"><span style="color:#C678DD">using</span><span style="color:#E5C07B"> Paymos</span><span style="color:#ABB2BF">;</span></span>
|
|
628
|
+
<span class="line"></span>
|
|
629
|
+
<span class="line"><span style="color:#C678DD">var</span><span style="color:#E06C75"> verifier</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> new </span><span style="color:#E5C07B">WebhookVerifier</span><span style="color:#ABB2BF">(</span></span>
|
|
630
|
+
<span class="line"><span style="color:#E5C07B"> Environment</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">GetEnvironmentVariable</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_WEBHOOK_SECRET"</span><span style="color:#ABB2BF">)</span><span style="color:#56B6C2">!</span><span style="color:#ABB2BF">);</span></span>
|
|
631
|
+
<span class="line"></span>
|
|
632
|
+
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep rawBody as ReadOnlySpan<byte> until verification succeeds.</span></span>
|
|
633
|
+
<span class="line"><span style="color:#C678DD">var</span><span style="color:#E06C75"> webhook</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:#E5C07B">InvoiceEventData</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>
|
|
634
|
+
<span class="line"><span style="color:#E5C07B">Console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">WriteLine</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">$"</span><span style="color:#ABB2BF">{</span><span style="color:#E5C07B">webhook</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">EventId</span><span style="color:#ABB2BF">}</span><span style="color:#ABB2BF"> {</span><span style="color:#E5C07B">webhook</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">EventType</span><span style="color:#ABB2BF">}</span><span style="color:#ABB2BF"> {</span><span style="color:#E5C07B">webhook</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">Data</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">InvoiceId</span><span style="color:#ABB2BF">}</span><span style="color:#98C379">"</span><span style="color:#ABB2BF">);</span></span>
|
|
635
|
+
<span class="line"></span>
|
|
636
|
+
<span class="line"><span style="color:#C678DD">public</span><span style="color:#C678DD"> sealed</span><span style="color:#C678DD"> record</span><span style="color:#E5C07B"> InvoiceEventData</span><span style="color:#ABB2BF">(</span><span style="color:#C678DD">string</span><span style="color:#E5C07B"> InvoiceId</span><span style="color:#ABB2BF">);</span></span>
|
|
637
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="java"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="java"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> com.fasterxml.jackson.databind.JsonNode</span><span style="color:#ABB2BF">;</span></span>
|
|
638
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> io.paymos.WebhookEvent</span><span style="color:#ABB2BF">;</span></span>
|
|
639
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> io.paymos.WebhookVerifier</span><span style="color:#ABB2BF">;</span></span>
|
|
640
|
+
<span class="line"><span style="color:#C678DD">import</span><span style="color:#E5C07B"> java.time.Instant</span><span style="color:#ABB2BF">;</span></span>
|
|
641
|
+
<span class="line"></span>
|
|
642
|
+
<span class="line"><span style="color:#E5C07B">WebhookVerifier</span><span style="color:#E06C75"> verifier </span><span style="color:#56B6C2">=</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> WebhookVerifier</span><span style="color:#E06C75">(</span><span style="color:#E5C07B">System</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">getenv</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_WEBHOOK_SECRET"</span><span style="color:#ABB2BF">)</span><span style="color:#E06C75">)</span><span style="color:#ABB2BF">;</span></span>
|
|
643
|
+
<span class="line"></span>
|
|
644
|
+
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep rawBody as byte[] until verification succeeds.</span></span>
|
|
645
|
+
<span class="line"><span style="color:#E5C07B">WebhookEvent</span><span style="color:#ABB2BF"><</span><span style="color:#E5C07B">JsonNode</span><span style="color:#ABB2BF">></span><span style="color:#E06C75"> event </span><span style="color:#56B6C2">=</span></span>
|
|
646
|
+
<span class="line"><span style="color:#E5C07B"> verifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">constructEvent</span><span style="color:#ABB2BF">(signatureHeader, rawBody, </span><span style="color:#E5C07B">Instant</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">now</span><span style="color:#ABB2BF">());</span></span>
|
|
647
|
+
<span class="line"><span style="color:#E5C07B">System</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">out</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">println</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">eventId</span><span style="color:#ABB2BF">() </span><span style="color:#56B6C2">+</span><span style="color:#98C379"> " "</span><span style="color:#56B6C2"> +</span><span style="color:#E5C07B"> event</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">eventType</span><span style="color:#ABB2BF">() </span><span style="color:#56B6C2">+</span><span style="color:#98C379"> " "</span><span style="color:#56B6C2"> +</span><span style="color:#E5C07B"> event</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">data</span><span style="color:#ABB2BF">());</span></span>
|
|
648
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="ruby"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="ruby"><code><span class="line"><span style="color:#61AFEF">require </span><span style="color:#98C379">'paymos'</span></span>
|
|
649
|
+
<span class="line"></span>
|
|
650
|
+
<span class="line"><span style="color:#E06C75">verifier</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> Paymos</span><span style="color:#ABB2BF">::</span><span style="color:#E5C07B">WebhookVerifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">new</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">ENV</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">fetch</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'PAYMOS_WEBHOOK_SECRET'</span><span style="color:#ABB2BF">))</span></span>
|
|
651
|
+
<span class="line"></span>
|
|
652
|
+
<span class="line"><span style="color:#7F848E;font-style:italic"># Keep raw_body as the original String until verification succeeds.</span></span>
|
|
653
|
+
<span class="line"><span style="color:#E06C75">event</span><span style="color:#56B6C2"> =</span><span style="color:#ABB2BF"> verifier.</span><span style="color:#61AFEF">construct_event</span><span style="color:#ABB2BF">(signature_header, raw_body)</span></span>
|
|
654
|
+
<span class="line"><span style="color:#56B6C2">puts</span><span style="color:#98C379"> "</span><span style="color:#C678DD">#{</span><span style="color:#ABB2BF">event.</span><span style="color:#61AFEF">event_id</span><span style="color:#C678DD">}</span><span style="color:#C678DD"> #{</span><span style="color:#ABB2BF">event.</span><span style="color:#61AFEF">event_type</span><span style="color:#C678DD">}</span><span style="color:#C678DD"> #{</span><span style="color:#ABB2BF">event.</span><span style="color:#61AFEF">data</span><span style="color:#C678DD">}</span><span style="color:#98C379">"</span></span>
|
|
655
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="rust"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="rust"><code><span class="line"><span style="color:#C678DD">use</span><span style="color:#E5C07B"> paymos</span><span style="color:#ABB2BF">::{</span><span style="color:#E5C07B">Invoice</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">WebhookEvent</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">WebhookVerifier</span><span style="color:#ABB2BF">};</span></span>
|
|
656
|
+
<span class="line"></span>
|
|
657
|
+
<span class="line"><span style="color:#C678DD">let</span><span style="color:#E06C75"> verifier</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> WebhookVerifier</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">new</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">std</span><span style="color:#ABB2BF">::</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">::</span><span style="color:#61AFEF">var</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"PAYMOS_WEBHOOK_SECRET"</span><span style="color:#ABB2BF">)?)?;</span></span>
|
|
658
|
+
<span class="line"></span>
|
|
659
|
+
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep raw_body as &[u8] until verification succeeds.</span></span>
|
|
660
|
+
<span class="line"><span style="color:#C678DD">let</span><span style="color:#E06C75"> event</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">WebhookEvent</span><span style="color:#ABB2BF"><</span><span style="color:#E5C07B">Invoice</span><span style="color:#ABB2BF">> </span><span style="color:#56B6C2">=</span><span style="color:#E06C75"> verifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">construct_event</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">signature_header</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">raw_body</span><span style="color:#ABB2BF">)?;</span></span>
|
|
661
|
+
<span class="line"><span style="color:#61AFEF">println!</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"{} {} {}"</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.event_id, </span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.event_type, </span><span style="color:#E06C75">event</span><span style="color:#ABB2BF">.data.invoice_id);</span></span>
|
|
662
|
+
<span class="line"></span></code></pre></div></div>
|
|
663
|
+
<h2 id="simulate-the-test-payment">Simulate the test payment</h2>
|
|
664
|
+
<p>Use the <a href="/docs/invoices/simulate-payment">payment simulator</a> to mark the test invoice paid. Do not send real assets to a test invoice. Confirm that your registered endpoint receives the signed event and that your server verifies it with <code>whsec_test_\u2026</code> before fulfilling the order.</p>
|
|
665
|
+
<h2 id="move-to-production">Move to Production</h2>
|
|
666
|
+
<p>Once the Sandbox request and signed webhook work, switch to Production in the dashboard. There is no manual approval step. Switching the environment does not create keys: open <strong>Dashboard \u2192 Developer \u2192 API Keys</strong> and create separate live credentials (<code>pk_live_\u2026</code> and <code>sk_live_\u2026</code>). Register the live webhook endpoint separately and store its <code>whsec_live_\u2026</code> secret apart from the test secret.</p>
|
|
667
|
+
<h2 id="accept-your-first-real-mainnet-payment">Accept your first real mainnet payment</h2>
|
|
668
|
+
<p>Repeat the invoice request with the live credentials, open the returned <code>payment_url</code> \u2014 the checkout page, or the Paymos bot on a Telegram-bot project \u2014 and send a supported asset on an enabled mainnet network. Paymos detects the transfer and sends the signed live webhook after the required confirmations.</p>
|
|
669
|
+
<p>The normal self-serve flow from sign-up to a first real mainnet payment takes about 10 minutes. This is an onboarding benchmark, not an SLA: confirmation time still depends on the network, amount, and current blockchain conditions.</p>
|
|
670
|
+
<h2 id="next-steps">Next steps</h2>
|
|
671
|
+
<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><a href="/docs/api-keys">API Keys</a> \u2014 credential types, scope, lifecycle</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><a href="/docs/server-sdks">Server SDKs</a> \u2014 official clients for eight language ecosystems</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><a href="/docs/hosted-checkout">Hosted Checkout</a> \u2014 redirect and iframe embed options</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><a href="/docs/testing">Testing</a> \u2014 how to test in sandbox</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><a href="/docs/webhooks">Webhooks</a> \u2014 signature verification and retry policy</span></li></ul>`
|
|
672
|
+
},
|
|
673
|
+
{
|
|
674
|
+
"name": "hosted-checkout",
|
|
675
|
+
"slug": "hosted-checkout",
|
|
676
|
+
"uri": "paymos://docs/hosted-checkout",
|
|
677
|
+
"description": "Hosted checkout: the payment_url flow, invoice lifecycle and redirect handling.",
|
|
678
|
+
"mimeType": "text/html",
|
|
679
|
+
"text": `<p>Use the <code>payment_url</code> returned by <code>POST /v1/invoices</code> as the canonical checkout URL. The same URL supports two presentation modes \u2014 full-page redirect and embedded iframe.</p>
|
|
680
|
+
<p>Both modes work on any project except a Telegram-bot one. There the same <code>payment_url</code> is a deep link into the Paymos bot \u2014 no hosted page to redirect to or embed.</p>
|
|
681
|
+
<h2 id="redirect-mode">Redirect mode</h2>
|
|
682
|
+
<p>Redirect mode is the simplest integration. Send the customer to <code>payment_url</code> after your server creates the invoice:</p>
|
|
683
|
+
<pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="html"><code><span class="line"><span style="color:#ABB2BF"><</span><span style="color:#E06C75">a</span><span style="color:#D19A66"> href</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"https://checkout.paymos.io/invoice/inv_xxx"</span><span style="color:#ABB2BF">>Pay invoice</</span><span style="color:#E06C75">a</span><span style="color:#ABB2BF">></span></span>
|
|
684
|
+
<span class="line"></span></code></pre>
|
|
685
|
+
<p>The customer completes the payment on the Paymos-hosted page. Your server fulfills the order only after receiving and verifying the signed webhook event.</p>
|
|
686
|
+
<h2 id="embed-mode">Embed mode</h2>
|
|
687
|
+
<p>Embed mode uses the same <code>payment_url</code> with <code>?embed=true</code>. Use this when your server already creates invoices and you only want the hosted checkout UI inside your own page:</p>
|
|
688
|
+
<pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="html"><code><span class="line"><span style="color:#ABB2BF"><</span><span style="color:#E06C75">iframe</span></span>
|
|
689
|
+
<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>
|
|
690
|
+
<span class="line"><span style="color:#D19A66"> title</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"Paymos checkout"</span></span>
|
|
691
|
+
<span class="line"><span style="color:#D19A66"> allow</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"clipboard-write"</span></span>
|
|
692
|
+
<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>
|
|
693
|
+
<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>
|
|
694
|
+
<span class="line"><span style="color:#ABB2BF">></</span><span style="color:#E06C75">iframe</span><span style="color:#ABB2BF">></span></span>
|
|
695
|
+
<span class="line"></span></code></pre>
|
|
696
|
+
<h2 id="embed-events">Embed events</h2>
|
|
697
|
+
<p>The checkout iframe sends <code>postMessage</code> transport events to the parent page:</p>
|
|
698
|
+
<table>
|
|
699
|
+
<thead>
|
|
700
|
+
<tr>
|
|
701
|
+
<th>Event</th>
|
|
702
|
+
<th>Meaning</th>
|
|
703
|
+
</tr>
|
|
704
|
+
</thead>
|
|
705
|
+
<tbody>
|
|
706
|
+
<tr>
|
|
707
|
+
<td><code>paymos:succeeded</code></td>
|
|
708
|
+
<td>Checkout reached <code>paid</code> or <code>paid_over</code>.</td>
|
|
709
|
+
</tr>
|
|
710
|
+
<tr>
|
|
711
|
+
<td><code>paymos:failed</code></td>
|
|
712
|
+
<td>Checkout reached a terminal failure state such as <code>underpaid</code>, <code>expired</code>, or <code>cancelled</code>.</td>
|
|
713
|
+
</tr>
|
|
714
|
+
<tr>
|
|
715
|
+
<td><code>paymos:close</code></td>
|
|
716
|
+
<td>Customer clicked a close/back action inside the embedded checkout.</td>
|
|
717
|
+
</tr>
|
|
718
|
+
</tbody>
|
|
719
|
+
</table>
|
|
720
|
+
<p>Parent pages must validate both the sender origin and the iframe source:</p>
|
|
721
|
+
<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">const</span><span style="color:#E5C07B"> iframe</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> document</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">querySelector</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'#paymos-checkout'</span><span style="color:#ABB2BF">);</span></span>
|
|
722
|
+
<span class="line"></span>
|
|
723
|
+
<span class="line"><span style="color:#E5C07B">window</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">addEventListener</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'message'</span><span style="color:#ABB2BF">, (</span><span style="color:#E06C75;font-style:italic">event</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">=></span><span style="color:#ABB2BF"> {</span></span>
|
|
724
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">origin</span><span style="color:#56B6C2"> !==</span><span style="color:#98C379"> 'https://checkout.paymos.io'</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF">;</span></span>
|
|
725
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">source</span><span style="color:#56B6C2"> !==</span><span style="color:#E5C07B"> iframe</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">contentWindow</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF">;</span></span>
|
|
726
|
+
<span class="line"><span style="color:#C678DD"> if</span><span style="color:#ABB2BF"> (</span><span style="color:#56B6C2">!</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#56B6C2"> ||</span><span style="color:#C678DD"> typeof</span><span style="color:#E5C07B"> event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#56B6C2"> !==</span><span style="color:#98C379"> 'object'</span><span style="color:#ABB2BF">) </span><span style="color:#C678DD">return</span><span style="color:#ABB2BF">;</span></span>
|
|
727
|
+
<span class="line"></span>
|
|
728
|
+
<span class="line"><span style="color:#C678DD"> switch</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">type</span><span style="color:#ABB2BF">) {</span></span>
|
|
729
|
+
<span class="line"><span style="color:#C678DD"> case</span><span style="color:#98C379"> 'paymos:succeeded'</span><span style="color:#ABB2BF">:</span></span>
|
|
730
|
+
<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:#98C379">'Payment UI succeeded:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">invoice_id</span><span style="color:#ABB2BF">);</span></span>
|
|
731
|
+
<span class="line"><span style="color:#C678DD"> break</span><span style="color:#ABB2BF">;</span></span>
|
|
732
|
+
<span class="line"><span style="color:#C678DD"> case</span><span style="color:#98C379"> 'paymos:failed'</span><span style="color:#ABB2BF">:</span></span>
|
|
733
|
+
<span class="line"><span style="color:#E5C07B"> console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">warn</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">'Payment UI failed:'</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">data</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">reason</span><span style="color:#ABB2BF">);</span></span>
|
|
734
|
+
<span class="line"><span style="color:#C678DD"> break</span><span style="color:#ABB2BF">;</span></span>
|
|
735
|
+
<span class="line"><span style="color:#C678DD"> case</span><span style="color:#98C379"> 'paymos:close'</span><span style="color:#ABB2BF">:</span></span>
|
|
736
|
+
<span class="line"><span style="color:#E5C07B"> iframe</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">remove</span><span style="color:#ABB2BF">();</span></span>
|
|
737
|
+
<span class="line"><span style="color:#C678DD"> break</span><span style="color:#ABB2BF">;</span></span>
|
|
738
|
+
<span class="line"><span style="color:#ABB2BF"> }</span></span>
|
|
739
|
+
<span class="line"><span style="color:#ABB2BF">});</span></span>
|
|
740
|
+
<span class="line"></span></code></pre>
|
|
741
|
+
<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>
|
|
742
|
+
<h2 id="security-model">Security model</h2>
|
|
743
|
+
<p>The recommended iframe sandbox is deliberately small:</p>
|
|
744
|
+
<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> is omitted because the checkout does not need to open extra browser windows.</span></li></ul>
|
|
745
|
+
<h2 id="when-to-use-low-code-sdk-instead">When to use Low-Code SDK instead</h2>
|
|
746
|
+
<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>
|
|
747
|
+
<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>`
|
|
748
|
+
},
|
|
749
|
+
{
|
|
750
|
+
"name": "webhooks",
|
|
751
|
+
"slug": "webhooks",
|
|
752
|
+
"uri": "paymos://docs/webhooks",
|
|
753
|
+
"description": "Webhooks: event types, payloads, retries and signature verification.",
|
|
754
|
+
"mimeType": "text/html",
|
|
755
|
+
"text": '<p>Paymos sends an HTTPS <code>POST</code> when an invoice, a withdrawal, or a payment-channel deposit changes state. Webhooks are the authoritative asynchronous signal for your backend: API responses start an operation, while webhook events tell you what happened after blockchain processing.</p>\n<h2 id="integration-flow">Integration flow</h2>\n<ol>\n<li>Create a webhook endpoint in <strong>Dashboard \u2192 Developer \u2192 Webhooks</strong>.</li>\n<li>Choose one or more event categories: <code>Invoice</code>, <code>Withdrawal</code>, <code>Payment channel</code>.</li>\n<li>Optionally restrict invoice and payment-channel events to selected projects \u2014 one filter covers both. Withdrawal events are merchant-wide and ignore it.</li>\n<li>Store the displayed <code>whsec_\u2026</code> secret on your server.</li>\n<li>Verify every delivery against the unchanged raw request body.</li>\n<li>Persist <code>event_id</code>, acknowledge with <code>2xx</code>, and process the event asynchronously.</li>\n</ol>\n<p>Production and Sandbox have separate endpoints, secrets, and events. A sandbox event is never delivered to a production endpoint.</p>\n<h2 id="endpoint-rules">Endpoint rules</h2>\n<ul>\n<li>The URL must use HTTPS.</li>\n<li>The URL may name port 443 \u2014 what a URL without a port uses \u2014 or any port from 1024 up. Other ports are refused when you save, and an endpoint that already has one gets no deliveries.</li>\n<li>Up to 10 endpoints can be configured per merchant and environment.</li>\n<li>The same active URL cannot be registered twice in one environment.</li>\n<li>An endpoint must subscribe to at least one category.</li>\n<li>No project filter means every project is included.</li>\n<li>Suspending or deleting an endpoint stops new deliveries to it.</li>\n</ul>\n<h2 id="delivery-headers">Delivery headers</h2>\n<table>\n<thead>\n<tr>\n<th>Header</th>\n<th>Contract</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>Content-Type</code></td>\n<td><code>application/json; charset=utf-8</code></td>\n</tr>\n<tr>\n<td><code>X-Webhook-Id</code></td>\n<td>Same <code>evt_\u2026</code> value as <code>event_id</code> in the body; not covered by the signature</td>\n</tr>\n<tr>\n<td><code>X-Webhook-Timestamp</code></td>\n<td>Unix seconds for this delivery attempt</td>\n</tr>\n<tr>\n<td><code>X-Webhook-Signature</code></td>\n<td><code>t={timestamp},v1={hmac_hex}</code>; may contain two <code>v1</code> values during rotation</td>\n</tr>\n</tbody>\n</table>\n<p>Delivery is at-least-once and ordering is not guaranteed. Deduplicate on <code>event_id</code> from the verified body, then apply the resource state from <code>data</code> instead of counting events or assuming arrival order.</p>\n<p><code>X-Webhook-Id</code> is there for your logs, not for deduplication. The signature covers only the timestamp and the body, so a captured delivery can be resent with a different <code>X-Webhook-Id</code> and still verify while its timestamp passes your check \u2014 and a handler keyed on the header processes that copy a second time.</p>\n<h2 id="webhook-documentation">Webhook documentation</h2>\n<ul>\n<li><a href="/docs/webhooks/events">Event catalog</a> \u2014 every invoice, withdrawal, and payment-channel event type</li>\n<li><a href="/docs/webhooks/payloads">Payload contract</a> \u2014 envelope and resource snapshots</li>\n<li><a href="/docs/webhooks/verify">Verify signatures</a> \u2014 raw-body HMAC verification and secret rotation</li>\n<li><a href="/docs/webhooks/retry">Delivery and retries</a> \u2014 timeout, backoff, idempotency, and replay</li>\n<li><a href="/docs/webhooks/testing">Test webhooks</a> \u2014 sandbox prerequisites and the interactive playground</li>\n</ul>'
|
|
756
|
+
},
|
|
757
|
+
{
|
|
758
|
+
"name": "testing-sandbox",
|
|
759
|
+
"slug": "testing",
|
|
760
|
+
"uri": "paymos://docs/testing-sandbox",
|
|
761
|
+
"description": "Testing in the sandbox: simulate payments, test key pairs, the go-live checklist.",
|
|
762
|
+
"mimeType": "text/html",
|
|
763
|
+
"text": `<p>Test your integration end-to-end in sandbox. Same API surface as production, simulated blockchain, signed webhooks, no real money at risk.</p>
|
|
764
|
+
<h2 id="sandbox-vs-production">Sandbox vs production</h2>
|
|
765
|
+
<table>
|
|
766
|
+
<thead>
|
|
767
|
+
<tr>
|
|
768
|
+
<th>Feature</th>
|
|
769
|
+
<th>Sandbox</th>
|
|
770
|
+
<th>Production</th>
|
|
771
|
+
</tr>
|
|
772
|
+
</thead>
|
|
773
|
+
<tbody>
|
|
774
|
+
<tr>
|
|
775
|
+
<td>Base URL</td>
|
|
776
|
+
<td><code>api.paymos.io/v1</code></td>
|
|
777
|
+
<td><code>api.paymos.io/v1</code></td>
|
|
778
|
+
</tr>
|
|
779
|
+
<tr>
|
|
780
|
+
<td>API Keys</td>
|
|
781
|
+
<td><code>pk_test_</code> / <code>rk_test_</code> IDs with <code>sk_test_</code> secrets</td>
|
|
782
|
+
<td><code>pk_live_</code> / <code>rk_live_</code> IDs with <code>sk_live_</code> secrets</td>
|
|
783
|
+
</tr>
|
|
784
|
+
<tr>
|
|
785
|
+
<td>Transactions</td>
|
|
786
|
+
<td>Simulated</td>
|
|
787
|
+
<td>Real blockchain</td>
|
|
788
|
+
</tr>
|
|
789
|
+
<tr>
|
|
790
|
+
<td>Webhooks</td>
|
|
791
|
+
<td>Sent normally</td>
|
|
792
|
+
<td>Sent normally</td>
|
|
793
|
+
</tr>
|
|
794
|
+
<tr>
|
|
795
|
+
<td>Funds</td>
|
|
796
|
+
<td>No real value</td>
|
|
797
|
+
<td>Real crypto</td>
|
|
798
|
+
</tr>
|
|
799
|
+
</tbody>
|
|
800
|
+
</table>
|
|
801
|
+
<h2 id="simulating-payments">Simulating payments</h2>
|
|
802
|
+
<p>Sandbox payments are not auto-confirmed by a timer. Trigger them explicitly:</p>
|
|
803
|
+
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/invoices/:invoice_id/simulate-payment</span></div>
|
|
804
|
+
<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>{ "stage": "paid" }</code> \u2014 <code>stage</code> is one of <code>paid</code>, <code>overpaid</code>, <code>underpay</code>, or <code>cancel</code>. Authenticate it like any other signed <code>/v1</code> call; it acts on sandbox invoices only, so a production key is rejected with <code>403 not_sandbox</code>. It fires the same lifecycle and webhook events as a real on-chain payment, so your verification path stays identical between sandbox and production.</p></div></div>
|
|
805
|
+
<h2 id="simulating-withdrawals">Simulating withdrawals</h2>
|
|
806
|
+
<p>Sandbox withdrawals don't settle on a real chain. Mark a pending sandbox withdrawal as completed to exercise your full payout flow:</p>
|
|
807
|
+
<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>
|
|
808
|
+
<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>
|
|
809
|
+
<h2 id="simulating-channel-deposits">Simulating channel deposits</h2>
|
|
810
|
+
<p>Sandbox payment channels derive their addresses locally and watch no chain, so deposits are created explicitly:</p>
|
|
811
|
+
<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>
|
|
812
|
+
<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>{ "amount": "100", "currency": "USDT", "network": "TRC20", "stage": "confirmed" }</code> \u2014 <code>stage</code> is one of <code>confirming</code>, <code>reorged</code> or <code>confirmed</code> and defaults to <code>confirmed</code>. Sign it with your sandbox Payment key; a production key is rejected before anything is created. Every call emits <code>payment_channel.deposit.confirming</code> first, then the terminal event for the stage you asked for, so your webhook path is identical between sandbox and production. See <a href="/docs/payment-channels/simulate-deposit">Simulate Channel Deposit</a> for the full contract.</p></div></div>
|
|
813
|
+
<h2 id="testing-webhooks-locally">Testing webhooks locally</h2>
|
|
814
|
+
<p>Expose your local server through a tunnel:</p>
|
|
815
|
+
<pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="bash"><code><span class="line"><span style="color:#61AFEF">ngrok</span><span style="color:#98C379"> http</span><span style="color:#D19A66"> 3000</span></span>
|
|
816
|
+
<span class="line"></span></code></pre>
|
|
817
|
+
<p>Set the webhook URL in <a href="/developers/webhooks"><strong>Dashboard \u2192 Developer \u2192 Webhooks</strong></a>:</p>
|
|
818
|
+
<p><code>https://abc123.ngrok.io/api/paymos-webhook</code></p>
|
|
819
|
+
<h2 id="webhook-playground">Webhook playground</h2>
|
|
820
|
+
<p>The documentation includes a sandbox-only <strong>Webhook Playground</strong> that runs the real delivery path: it creates a sandbox invoice, drives it to the outcome you picked, and lets the delivery worker call your registered endpoint. Nothing is posted straight to your URL, so signature handling is verified against the same signing and retry code production uses.</p>
|
|
821
|
+
<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">01</span><span>Go to <strong>Dashboard \u2192 Developer \u2192 Documentation</strong> in the sandbox environment</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">02</span><span>Open <a href="/docs/webhooks/testing"><strong>Webhooks \u2192 Testing</strong></a>, then select <strong>Playground</strong></span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">03</span><span>Pick an event type (<code>invoice.paid</code>, <code>invoice.paid_over</code>, <code>invoice.underpaid</code>, or <code>invoice.cancelled</code>), set the amount and currency, then <strong>Simulate</strong></span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">04</span><span>Check your server logs for the received event and the <code>X-Webhook-Signature</code> header</span></li></ul>
|
|
822
|
+
<p>It needs an active sandbox webhook endpoint and a sandbox Payment key. Production sending is disabled there by design.</p>
|
|
823
|
+
<h2 id="checklist-before-going-live">Checklist before going live</h2>
|
|
824
|
+
<ul class="list-none p-0 m-0 flex flex-col gap-3"><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Webhook signature verification works</span></li><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Invoice creation returns correct data</span></li><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Payment flow redirects properly</span></li><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Error handling covers non-2xx responses (4xx validation, 409 conflicts)</span></li><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Idempotency with <code>external_order_id</code> works</span></li><li class="flex gap-3"><span class="text-gray-300 shrink-0">\u2610</span><span>Switch API key IDs from <code>pk_test_</code> / <code>rk_test_</code> to <code>pk_live_</code> / <code>rk_live_</code>, and secrets from <code>sk_test_</code> to <code>sk_live_</code></span></li></ul>`
|
|
825
|
+
},
|
|
826
|
+
{
|
|
827
|
+
"name": "server-sdks",
|
|
828
|
+
"slug": "server-sdks",
|
|
829
|
+
"uri": "paymos://docs/server-sdks",
|
|
830
|
+
"description": "Server SDKs: pick the SDK for your stack.",
|
|
831
|
+
"mimeType": "text/html",
|
|
832
|
+
"text": `<p>Paymos maintains official server-side SDKs for eight language ecosystems. Every
|
|
833
|
+
SDK covers the same invoices, withdrawals, payment channels, channel deposits,
|
|
834
|
+
balances, server-time, cursor pagination, error, retry, request-signing, and
|
|
835
|
+
webhook-verification contract.</p>
|
|
836
|
+
<p>All eight are published to their ecosystem's package registry. Install from
|
|
837
|
+
there; the repository stays the place to read the source.</p>
|
|
838
|
+
<table>
|
|
839
|
+
<thead>
|
|
840
|
+
<tr>
|
|
841
|
+
<th>Language</th>
|
|
842
|
+
<th>Registry</th>
|
|
843
|
+
<th>Install</th>
|
|
844
|
+
<th>Official source</th>
|
|
845
|
+
</tr>
|
|
846
|
+
</thead>
|
|
847
|
+
<tbody>
|
|
848
|
+
<tr>
|
|
849
|
+
<td>JavaScript / TypeScript</td>
|
|
850
|
+
<td>npm</td>
|
|
851
|
+
<td><code>npm i @paymos/sdk</code></td>
|
|
852
|
+
<td><a href="https://github.com/Paymos-labs/typescript-sdk">Paymos-labs/typescript-sdk</a></td>
|
|
853
|
+
</tr>
|
|
854
|
+
<tr>
|
|
855
|
+
<td>Python</td>
|
|
856
|
+
<td>PyPI</td>
|
|
857
|
+
<td><code>pip install paymos-sdk</code></td>
|
|
858
|
+
<td><a href="https://github.com/Paymos-labs/python-sdk">Paymos-labs/python-sdk</a></td>
|
|
859
|
+
</tr>
|
|
860
|
+
<tr>
|
|
861
|
+
<td>PHP</td>
|
|
862
|
+
<td>Packagist</td>
|
|
863
|
+
<td><code>composer require paymos/php-sdk</code></td>
|
|
864
|
+
<td><a href="https://github.com/Paymos-labs/php-sdk">Paymos-labs/php-sdk</a></td>
|
|
865
|
+
</tr>
|
|
866
|
+
<tr>
|
|
867
|
+
<td>Go</td>
|
|
868
|
+
<td>Go modules</td>
|
|
869
|
+
<td><code>go get github.com/Paymos-labs/go-sdk/v2</code></td>
|
|
870
|
+
<td><a href="https://github.com/Paymos-labs/go-sdk">Paymos-labs/go-sdk</a></td>
|
|
871
|
+
</tr>
|
|
872
|
+
<tr>
|
|
873
|
+
<td>.NET</td>
|
|
874
|
+
<td>NuGet</td>
|
|
875
|
+
<td><code>dotnet add package Paymos</code></td>
|
|
876
|
+
<td><a href="https://github.com/Paymos-labs/dotnet-sdk">Paymos-labs/dotnet-sdk</a></td>
|
|
877
|
+
</tr>
|
|
878
|
+
<tr>
|
|
879
|
+
<td>Java</td>
|
|
880
|
+
<td>Maven Central</td>
|
|
881
|
+
<td><code>io.paymos:paymos-java</code></td>
|
|
882
|
+
<td><a href="https://github.com/Paymos-labs/java-sdk">Paymos-labs/java-sdk</a></td>
|
|
883
|
+
</tr>
|
|
884
|
+
<tr>
|
|
885
|
+
<td>Ruby</td>
|
|
886
|
+
<td>RubyGems</td>
|
|
887
|
+
<td><code>gem install paymos</code></td>
|
|
888
|
+
<td><a href="https://github.com/Paymos-labs/ruby-sdk">Paymos-labs/ruby-sdk</a></td>
|
|
889
|
+
</tr>
|
|
890
|
+
<tr>
|
|
891
|
+
<td>Rust</td>
|
|
892
|
+
<td>crates.io</td>
|
|
893
|
+
<td><code>cargo add paymos</code></td>
|
|
894
|
+
<td><a href="https://github.com/Paymos-labs/rust-sdk">Paymos-labs/rust-sdk</a></td>
|
|
895
|
+
</tr>
|
|
896
|
+
</tbody>
|
|
897
|
+
</table>
|
|
898
|
+
<p>Java resolves by coordinates rather than a one-line command: add the
|
|
899
|
+
<code>io.paymos:paymos-java</code> dependency to your <code>pom.xml</code> or your Gradle build.</p>
|
|
900
|
+
<p>Use an immutable <code>vMAJOR.MINOR.PATCH</code> release tag. Each repository's release page
|
|
901
|
+
contains the supported runtime, the changelog, and the source commit from which
|
|
902
|
+
the release was produced.</p>
|
|
903
|
+
<h2 id="shared-api-surface">Shared API surface</h2>
|
|
904
|
+
<p>All clients expose six resources:</p>
|
|
905
|
+
<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>system</code> \u2014 fetch server time for request-clock alignment</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>invoices</code> \u2014 create, get, list, cancel, confirm payment, and sandbox simulation</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>withdrawals</code> \u2014 create, get, list, cancel, and sandbox completion simulation</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>paymentChannels</code> \u2014 create, get, list, block, unblock, and sandbox deposit simulation</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>paymentChannelDeposits</code> \u2014 get one deposit, and poll the confirmed-deposit feed</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>balances</code> \u2014 list available balances grouped by currency</span></li></ul>
|
|
906
|
+
<p>Each client spells the two channel resources in its own language's convention:
|
|
907
|
+
<code>paymentChannels</code> in TypeScript, PHP and Java, <code>payment_channels</code> in Python,
|
|
908
|
+
Ruby and Rust, <code>PaymentChannels</code> in Go and .NET.</p>
|
|
909
|
+
<p>List helpers use cursor pagination with a maximum-page bound and reject a cursor
|
|
910
|
+
returned twice. Automatic retries honor <code>Retry-After</code>; mutating requests are not
|
|
911
|
+
retried on transport errors or generic server errors. A rate-limited request may
|
|
912
|
+
be retried because the API did not accept it for processing.</p>
|
|
913
|
+
<h2 id="one-contract-eight-languages">One contract, eight languages</h2>
|
|
914
|
+
<p>The eight are held to a shared behavioural contract, not only to a shared endpoint
|
|
915
|
+
list. A single language-neutral conformance suite fixes the bytes that go into a
|
|
916
|
+
request signature, the retry rules above, the cursor iterators and the webhook
|
|
917
|
+
verifier, and a release ships only once its own tests run against that suite.</p>
|
|
918
|
+
<p>The practical consequence: an integration ported from one of these languages to
|
|
919
|
+
another keeps its signing, paging, retry and webhook semantics. Two SDKs building
|
|
920
|
+
the same filtered list request sign identical bytes.</p>
|
|
921
|
+
<h2 id="what-php-adds">What PHP adds</h2>
|
|
922
|
+
<p>The PHP SDK carries a plugin-integration layer that exists in no other client:
|
|
923
|
+
reverse verification of a webhook against a fresh read of the API, an amount and
|
|
924
|
+
currency guard before an order is released, replay deduplication behind a
|
|
925
|
+
pluggable event store, a verifier that holds the Sandbox and Live secrets at
|
|
926
|
+
once, a reconciler, a mapper from event to order action, and encrypted credential
|
|
927
|
+
storage.</p>
|
|
928
|
+
<p>That layer is why the CMS plugins are thin \u2014 the order-state logic sits once in
|
|
929
|
+
the SDK underneath them instead of eight times above it. None of it applies to
|
|
930
|
+
the other seven: they are client, signing, resources, pagination and webhook
|
|
931
|
+
verification, and building on more than that will find nothing there.</p>
|
|
932
|
+
<h2 id="security-rules">Security rules</h2>
|
|
933
|
+
<div class="callout callout--warning"><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 3 1.7 17h16.6L10 3Zm0 5v4m0 3h.01"></path></svg><div class="callout__body"><p>These SDKs are server-side only. Never put an API secret in browser JavaScript,
|
|
934
|
+
a mobile application, a public repository, a URL, or a log.</p></div></div>
|
|
935
|
+
<p>Request authentication and webhook authentication use different signatures.
|
|
936
|
+
API requests use base64 HMAC-SHA256 over the canonical request. Webhooks use a
|
|
937
|
+
hex HMAC-SHA256 over <code>{timestamp}.{exact raw body}</code>. Pass the unparsed request
|
|
938
|
+
bytes to the SDK verifier before decoding JSON. The verifier refuses a timestamp
|
|
939
|
+
more than five minutes away from now by default, and accepts a header carrying
|
|
940
|
+
two <code>v1</code> values, so a <a href="/docs/webhooks/verify">secret rotation</a> costs you no code
|
|
941
|
+
change.</p>
|
|
942
|
+
<p>For endpoint schemas and examples, continue with <a href="/docs/authentication">Authentication</a>,
|
|
943
|
+
<a href="/docs/invoices/create">Invoices</a>, <a href="/docs/withdrawals/create">Withdrawals</a>,
|
|
944
|
+
<a href="/docs/balances/get">Balances</a>, and <a href="/docs/webhooks">Webhooks</a>.</p>`
|
|
945
|
+
}
|
|
946
|
+
];
|
|
947
|
+
|
|
948
|
+
// src/resources.ts
|
|
949
|
+
function registerResources(server) {
|
|
950
|
+
for (const resource of DOC_RESOURCES) {
|
|
951
|
+
server.registerResource(
|
|
952
|
+
resource.name,
|
|
953
|
+
resource.uri,
|
|
954
|
+
{ description: resource.description, mimeType: resource.mimeType },
|
|
955
|
+
async (uri) => ({
|
|
956
|
+
contents: [{ uri: uri.href, mimeType: resource.mimeType, text: resource.text }]
|
|
957
|
+
})
|
|
958
|
+
);
|
|
959
|
+
}
|
|
960
|
+
}
|
|
961
|
+
|
|
962
|
+
// src/version.ts
|
|
963
|
+
var MCP_VERSION = "1.0.2";
|
|
964
|
+
|
|
965
|
+
// src/server.ts
|
|
966
|
+
function buildServer(gateway) {
|
|
967
|
+
const server = new McpServer({ name: "paymos", version: MCP_VERSION });
|
|
968
|
+
registerTools(server, gateway);
|
|
969
|
+
registerResources(server);
|
|
970
|
+
return server;
|
|
971
|
+
}
|
|
972
|
+
|
|
973
|
+
// src/index.ts
|
|
974
|
+
async function main(env = process.env, argv = process.argv.slice(2)) {
|
|
975
|
+
const credentials = loadCredentials(env, parseFlags(argv));
|
|
976
|
+
const gateway = new PaymosGateway(credentials);
|
|
977
|
+
console.error(startupLine(gateway.check(), credentials.apiKeyId));
|
|
978
|
+
const server = buildServer(gateway);
|
|
979
|
+
await server.connect(new StdioServerTransport());
|
|
980
|
+
}
|
|
981
|
+
var isDirectRun = process.argv[1] !== void 0 && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
|
|
982
|
+
if (isDirectRun) {
|
|
983
|
+
main().catch((error) => {
|
|
984
|
+
console.error(`[paymos-mcp] fatal: ${error instanceof Error ? error.message : String(error)}`);
|
|
985
|
+
process.exit(1);
|
|
986
|
+
});
|
|
987
|
+
}
|
|
988
|
+
export {
|
|
989
|
+
main
|
|
990
|
+
};
|