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

const { payment, receivingAddress } = 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-v1",    // optional
  expiresInMinutes: 60,            // optional, default 60
});

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 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: "alice@example.com",
  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

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-v1",      # optional
    expires_in_minutes=60,             # optional
)

payment = result["payment"]
receiving_address = result["receivingAddress"]

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
paydirect payments create --token=USDC --amount=50 --wallet=0xABC...

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

# Verify a payment
paydirect payments verify a1b2c3d4-...

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