SDKs & CLI

Installation

npm install @paydirect/sdk
# or
pnpm add @paydirect/sdk

Initialization

import { PayDirectClient } from "@paydirect/sdk";

const client = new PayDirectClient({
  apiKey: "pd_test_abc123...",
  baseUrl: "https://www.paydirect.com/api/v1",  // optional, this is the default
  timeoutMs: 30000,                              // optional, default 30s
});

Create a Payment (crypto)

const { payment, receivingAddress, paymentUrl } = await client.createPayment({
  tokenSymbol: "USDC",             // "USDC" | "ETH" | "ADAO"
  amount: "100.00",
  merchantWallet: "0xYourBase...",
  description: "Invoice #1234",    // optional
  metadata: { orderId: "ORD_1" },  // optional
  idempotencyKey: "order-1-crypto", // optional — use per-rail keys for dual checkout
  expiresInMinutes: 60,            // optional, default 60
});
// Share paymentUrl with payer — no API key required on hosted /pay/:id page

Create a Payment (Stripe — REST)

Pass paymentMethod: "stripe" via REST until the SDK adds USD / card support.

const res = await fetch("https://www.paydirect.com/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYDIRECT_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1-stripe",
  },
  body: JSON.stringify({
    paymentMethod: "stripe",
    tokenSymbol: "USD",
    amount: "49.00",
    description: "Pro subscription",
    metadata: { orderId: "ORD_1" },
  }),
});
const { payment, checkoutUrl, paymentUrl, paymentProvider } = await res.json();
// Live: redirect to checkoutUrl. Sandbox: payment.status === "forwarded"

List and Get Payments

// List with filters
const { payments, total } = await client.listPayments({
  status: "forwarded",
  environment: "sandbox",
  limit: 20,
  offset: 0,
});

// Get by ID
const { payment } = await client.getPayment("a1b2c3d4-...");

// Cancel
const { payment: cancelled } = await client.cancelPayment("a1b2c3d4-...");

// Verify settlement
const { verified, payment: p } = await client.verifyPayment("a1b2c3d4-...");

Webhooks

// Create
const { webhook } = await client.createWebhook(
  "https://yourapp.com/webhooks",
  ["payment.forwarded", "payment.failed"]
);
console.log(webhook.signingSecret); // "whsec_..." — store this!

// List
const { webhooks } = await client.listWebhooks();

// Delete
await client.deleteWebhook("7");

Webhook Signature Verification

// Static method — no client instance needed
const isValid = PayDirectClient.verifyWebhookSignature(
  "whsec_...",        // signing secret
  rawRequestBody,     // string
  signatureHeader     // X-PayDirect-Signature value
);

Error Handling

import { PayDirectError } from "@paydirect/sdk";

try {
  await client.createPayment({ ... });
} catch (err) {
  if (err instanceof PayDirectError) {
    console.log(err.message);  // human-readable error
    console.log(err.status);   // HTTP status code (408 = timeout)
    console.log(err.data);     // raw response body
  }
}

const balance = await client.getBalance();

console.log(balance.eth, balance.usdc, balance.adao);
console.log(balance.defaultWalletType);

// Smart wallet balance (if provisioned)
if (balance.smartWallet) {
  console.log(balance.smartWallet.adao);
}

const stats = await client.getWalletStats();

// Cumulative workspace activity (EOA + smart wallet)
console.log(stats.stats.totalActivity);
console.log(stats.stats.tokenVolumes.ADAO?.volume);

// Combined balances including settlement address
console.log(stats.balances.total.adao);

// Per-wallet breakdown
console.log(stats.wallets.smartWallet?.address);
console.log(stats.wallets.smartWallet?.transactions.total);

const result = await client.withdraw({
  tokenSymbol: "USDC",
  amount: "50",             // omit for full balance
  walletType: "smart_wallet",
});

console.log(result.explorerUrl);

// Requires admin secret as apiKey
const admin = new PayDirectClient({
  apiKey: process.env.PAYDIRECT_ADMIN_SECRET!,
});

// Create workspace for a platform user
const ws = await admin.createWorkspace({
  name: "alice-workspace",
  ownerEmail: "[email protected]",
  platform: "myplatform",
  settlementWallet: "0xSettlement...",
});

console.log(ws.workspaceId, ws.apiKeys.live);

// List workspaces
const { workspaces } = await admin.listWorkspaces({ platform: "myplatform" });

// Get workspace details
const info = await admin.getWorkspace(ws.workspaceId);

// Create smart wallet (ERC-4337, gasless)
const result = await client.createSmartWallet(workspaceId, {
  setDefault: true,
});

console.log(result.smartWallet.address);

// Get wallet info
const info = await client.getSmartWallet(workspaceId);
console.log(info.eoa, info.smartWallet, info.defaultWalletType);

// Switch default wallet type
await client.setDefaultWallet(workspaceId, "smart_wallet");

Installation

pip install paydirect

Initialization

from paydirect import PayDirectClient

client = PayDirectClient(
    api_key="pd_test_abc123...",
    base_url="https://www.paydirect.com/api/v1",  # optional default
)

Create a Payment (crypto)

result = client.create_payment(
    token_symbol="USDC",
    amount="100.00",
    merchant_wallet="0xYourBase...",
    description="Invoice #1234",       # optional
    metadata={"orderId": "ORD_1"},     # optional
    idempotency_key="order-1-crypto",  # optional
    expires_in_minutes=60,             # optional
)

payment = result["payment"]
receiving_address = result["receivingAddress"]
payment_url = result.get("paymentUrl")

Create a Payment (Stripe — REST)

import requests

res = requests.post(
    "https://www.paydirect.com/api/v1/payments",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Idempotency-Key": "order-1-stripe",
    },
    json={
        "paymentMethod": "stripe",
        "tokenSymbol": "USD",
        "amount": "49.00",
        "description": "Pro subscription",
        "metadata": {"orderId": "ORD_1"},
    },
)
data = res.json()
checkout_url = data.get("checkoutUrl")  # live Stripe Checkout
payment_url = data.get("paymentUrl")    # hosted PayDirect page

List, Get, Cancel, Verify

# List
result = client.list_payments(status="forwarded", limit=20)

# Get
result = client.get_payment("a1b2c3d4-...")

# Cancel
result = client.cancel_payment("a1b2c3d4-...")

# Verify
result = client.verify_payment("a1b2c3d4-...")
print(result["verified"])  # True

Webhooks

# Create
result = client.create_webhook(
    url="https://yourapp.com/webhooks",
    events=["payment.forwarded", "payment.failed"]
)

# List
result = client.list_webhooks()

# Delete
result = client.delete_webhook("7")

Webhook Signature Verification

from paydirect.webhooks import verify_signature

is_valid = verify_signature(
    secret="whsec_...",
    payload=raw_request_body,
    signature=request.headers["X-PayDirect-Signature"]
)

Error Handling

from paydirect import PayDirectError

try:
    client.create_payment(...)
except PayDirectError as e:
    print(e)          # error message
    print(e.status)   # HTTP status code
    print(e.data)     # raw response body

Installation

npm install -g @paydirect/cli
# or use npx
npx @paydirect/cli <command>

Configuration

# Option 1: Initialize config file
paydirect init pd_test_abc123...

# Option 2: Environment variable
export PAYDIRECT_API_KEY=pd_test_abc123...
export PAYDIRECT_BASE_URL=https://www.paydirect.com/api/v1  # optional

The init command creates a .paydirect.json file in the current directory.

Commands

Examples

# Create a 50 USDC payment (crypto)
paydirect payments create --token=USDC --amount=50 --wallet=0xABC...

# Stripe payments: use curl/REST (CLI stripe flag coming soon)
curl -X POST https://www.paydirect.com/api/v1/payments \
  -H "Authorization: Bearer $PAYDIRECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paymentMethod":"stripe","tokenSymbol":"USD","amount":"25.00"}'

# List pending payments
paydirect payments list --status=pending

# Verify a payment (crypto or Stripe)
paydirect payments verify a1b2c3d4-...

# Register a webhook for forwarded events
paydirect webhooks create https://myapp.com/hooks payment.forwarded,payment.failed