TypeScript/JavaScript SDK

Official ZynPay SDK for TypeScript and JavaScript applications. Accept USDC payments with MetaMask, WalletConnect, and other web3 wallets.

v1.1.2Testnet

Key Features

  • 💳 Accept USDC payments with MetaMask integration
  • 🔁 Refunds: Full and partial refunds, enforced by smart contract
  • 📊 Payment logs: Fetch on-chain payment history for dashboards & analytics
  • 🔒 Non-custodial: Payments go directly to your wallet
  • ⚡ Zero backend complexity: No API keys or servers required

Installation

npm install @zyntrialabs/zynpay-sdk

Quick Start

import { ZynPayClient, Environment } from '@zyntrialabs/zynpay-sdk';
import { BrowserProvider } from 'ethers';

// Connect customer's wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();

// Initialize with your merchant wallet
const client = new ZynPayClient({
  merchantWallet: '0xYourBusinessWallet',
  environment: Environment.TESTNET,
  defaultChain: 'base',
});

// Create and process payment
const payment = client.createPayment(49.99);
const txHash = await client.pay(payment, signer);

API Reference

new ZynPayClient(config)
Initialize the SDK client
new ZynPayClient({
  merchantWallet: '0x...',
  environment: Environment.TESTNET,
  defaultChain: 'base'
})
createPayment(amount, chain?)
Create a new payment request
const payment = client.createPayment(49.99, 'base');
pay(payment, signer, waitForConfirmation?)
Execute payment using customer's wallet
const provider = new BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const txHash = await client.pay(payment, signer);
getBalance(wallet, chain?)
Check USDC and native token balance
const balance = await client.getBalance('0x...');
estimateGas(amount, chain?)
Estimate gas cost for payment
const gas = await client.estimateGas(10.0);
client.payments.listPayments(options?)
Payment log (on-chain history)

Fetch an on-chain payment log for a merchant. Under the hood, this reads 

PaymentSplit
events from the router contract using 
getLogs
.

// All payments for your merchant wallet
const payments = await client.payments.listPayments();

// With filters
const filtered = await client.payments.listPayments({
  merchantAddress: "0xMerchantAddress...",
  network: "base-sepolia",
  fromBlock: 34_000_000,
  toBlock: "latest",
});

for (const p of filtered) {
  const amount = Number(p.amountTotal) / 1e6;
  const merchantAmount = Number(p.amountToMerchant) / 1e6;
  const fee = Number(p.amountToPlatform) / 1e6;

  console.log(`Payment: $${amount.toFixed(2)} USDC`);
  console.log(`  You receive: $${merchantAmount.toFixed(2)} USDC`);
  console.log(`  Platform fee: $${fee.toFixed(2)} USDC`);
  console.log(`  TX: ${p.txHash}`);
  console.log(`  Payer: ${p.payer}`);
  if (p.metadata) {
    console.log(`  Metadata: ${JSON.stringify(p.metadata)}`);
  }
}

Use cases:

  • Build a merchant dashboard (revenue, average order value, etc.)
  • Export payments to your own database / BI tool
  • Reconcile off-chain orders with on-chain payments using metadata (e.g. order_id)
client.payments.refund(options)
Refund a payment (merchant-only)

Refunds are initiated by the merchant wallet that originally received the funds. Refunds are on-chain and can be full or partial.

// In a backend script or admin tool
const refundTx = await client.payments.refund({
  paymentId: "PAYMENT_REQUEST_ID_FROM_BACKEND",
  amount: 5.0,             // in USDC
  chain: "base",
});

console.log("✅ Refund sent:", refundTx.hash);

How refunds work:

  • Refunds are merchant-driven: Only the merchant (the wallet that received the payment) can initiate a refund.
  • Refunds are on-chain: The merchant sends USDC back to the payer via the router contract.
  • Supports: ✅ Full refunds (up to 100% of the original amount) ✅ Multiple partial refunds
  • The smart contract guarantees: You can never refund more than the original amount (cumulative limit). Platform fee is not automatically refunded – if you refund 100%, that extra few % comes from your balance.

🔐 The SDK handles the on-chain call for you. You just decide which payment and how much to refund.

Supported Networks

Base Sepolia (Recommended)

chain: 'base'

Get free testnet tokens

Arc Testnet

chain: 'arc'

Get free USDC

Resources