Suward
TypeScript
TYPESCRIPT SDK

TypeScript SDK

Official Fern-generated TypeScript/JavaScript client for the Suward merchant API. Server-side only — never expose your API key to the browser.

@crylabsorg/suward-sdknpmGitHub

Install

Install · npm
# npm
npm i @crylabsorg/suward-sdk
# pnpm
pnpm add @crylabsorg/suward-sdk
# yarn
yarn add @crylabsorg/suward-sdk

Initialize the client

client.ts
import { SuwardSDKClient } from "@crylabsorg/suward-sdk";
const client = new SuwardSDKClient({ apiKey: process.env.SUWARD_API_KEY! });

Create a payment

createPayment returns a CryptopayPaymentResponse. The address field is the unique deposit address for this payment. Required fields: none — all are optional but you will typically pass amount, asset, externalId, and webhookUrl.

create-payment.ts
import { SuwardSDKClient } from "@crylabsorg/suward-sdk";
const client = new SuwardSDKClient({ apiKey: process.env.SUWARD_API_KEY! });
const payment = await client.payments.createPayment({
// 49.99 USDC — smallest-unit integer string, 6 decimals
amount: "49990000",
// SuwardSDK.CryptopayAssetId
asset: "USDC_BASE",
// idempotency key — your order id
externalId: "order-10472",
webhookUrl: "https://shop.example.com/webhooks/suward",
});
console.log(payment.id, payment.address, payment.status);

Get a payment

get-payment.ts
const p = await client.payments.getPayment({ paymentId: "pay_3Nk8Qd" });
console.log(p.status, p.amount, p.address);

Full method surface

client.payments

  • listPayments(order?, limit?, lastId?)→Promise<ListPaymentsResponse>
  • createPayment(CreatePaymentRequest)→Promise<PaymentResponse>
  • getPayment(paymentId)→Promise<PaymentResponse>
  • activatePayment(paymentId)→Promise<PublicPaymentResponse>
  • cancelPayment(paymentId)→Promise<PaymentResponse>
  • simulatePayment(paymentId, SimulatePaymentRequest)→Promise<PaymentResponse>

client.staticWallets

  • listStaticWallets(order?, limit?, lastId?)→Promise<ListStaticWalletsResponse>
  • createStaticWallet(CreateStaticWalletRequest)→Promise<StaticWalletResponse>
  • getStaticWallet(staticWalletId)→Promise<StaticWalletResponse>
  • deleteStaticWallet(staticWalletId)→Promise<void>
  • updateStaticWallet(staticWalletId, UpdateStaticWalletRequest)→Promise<StaticWalletResponse>
  • listStaticWalletDeposits(staticWalletId, order?, limit?, lastId?)→Promise<ListStaticDepositsResponse>
  • simulateStaticWalletDeposit(staticWalletId, SimulateStaticDepositRequest)→Promise<StaticDepositResponse>

Verify webhooks

The SDK ships a built-in helper. It verifies the Ed25519 signature over the raw body string using the project's webhookPublicKey from the dashboard.

webhook-handler.ts
import { webhooks } from "@crylabsorg/suward-sdk";
app.post("/webhooks/suward", async (req, res) => {
const ok = await webhooks.WebhooksHelper.verifySignature(
// raw request body string
req.rawBody,
// signature header
req.header("X-Suward-Signature"),
// project Ed25519 public key
process.env.SUWARD_WEBHOOK_PUBLIC_KEY!,
// timestamp header
req.header("X-Suward-Timestamp"),
);
if (!ok) return res.status(401).end();
const event = JSON.parse(req.rawBody);
// event.type: "payment.accepted" | "payment.success" | "payment.failed"
if (event.type === "payment.success") { /* mark order paid */ }
// non-2xx responses are retried; dedupe on event.eventId
res.status(200).end();
});
WebhooksHelper.verifySignature(
requestBody: string,
signatureHeader: string,
publicKey: string,
timestampHeader: string,
): Promise<boolean>

Error handling

All SDK errors throw SuwardSDKError. Inspect statusCode (HTTP status), message, and body for details.

error-handling.ts
import { SuwardSDKError } from "@crylabsorg/suward-sdk";
try {
await client.payments.createPayment({ /* ... */ });
} catch (err) {
if (err instanceof SuwardSDKError) {
console.log(err.statusCode, err.message, err.body);
}
}
SDK Reference