Testing Your Integration

PayDirect includes three test suites you can run to verify everything works correctly. All tests use the sandbox environment so no real transactions occur.

Available Test Suites

Suite	What It Tests	Command
API Integration	All v1 HTTP endpoints (payments, webhooks, keys, usage, auth, rate limits, fees)	pnpm test:api
Service Layer	Internal services (FeeEngine, SettlementService, WebhookEngine, UsageService, SpendingCaps)	pnpm test:services
Wallet Services	CDP wallet creation, gas funding, treasury bootstrap	pnpm test:wallets

Prerequisites

What you need before running tests

Database migrated. Run npx tsx scripts/migrate-fresh.ts to create all tables.
Environment variables set. Ensure .env has DATABASE_URL and other required variables.
A workspace with API key. Complete the onboarding to create a workspace and sandbox key.
For API tests: Dev server running (pnpm dev).

API Integration Tests

12 test groups covering all v1 HTTP endpoints

This suite makes real HTTP requests to your running server using a sandbox API key. It verifies every endpoint returns the correct status codes, response shapes, and error handling.

Setup

# 1. Start the dev server
pnpm dev

# 2. Set your sandbox API key
export TEST_API_KEY=pd_test_your_sandbox_key_here

# 3. Run the tests
pnpm test:api

# Or run directly:
npx tsx scripts/tests/test-api-endpoints.ts

What It Tests

#	Test Group	Checks
1	Authentication	Valid key (200), missing key (401), invalid key (401)
2	Create Payment	USDC/ETH/ADAO creation, fee calculation, validation errors (missing fields, bad token, bad wallet, negative amount)
3	Idempotency	Same key returns same payment, no duplicates
4	List Payments	Pagination, status filter, limit parameter
5	Get Payment	Retrieve by ID, 404 for non-existent
6	Cancel Payment	Cancel pending, reject re-cancel, reject cancel on forwarded
7	Verify Payment	Verified boolean, payment object, missing paymentId error
8	Webhooks API	Create (with signing secret), list, delete, invalid URL/events validation
9	Keys API	List, create (pd_test_ prefix), revoke
10	Usage API	Metrics, limits check, plan info
11	Rate Limit Headers	X-RateLimit-Limit and X-RateLimit-Remaining headers present
12	Fee Accuracy	USDC 0.5%, ETH 0.5%, ADAO 0.25% calculations verified

Example Output

═══════════════════════════════════════════════════════
  PayDirect v1 API Integration Tests
═══════════════════════════════════════════════════════
  Server:  http://localhost:3000/api/v1
  API Key: pd_test_abc1...
═══════════════════════════════════════════════════════

[1] Authentication Tests
  ✓ Valid API key returns 200
  ✓ Missing API key returns 401
  ✓ Invalid API key returns 401

[2] Create Payment (POST /payments)
  ✓ Returns 201 Created (got 201)
  ✓ Response contains payment object
  ✓ Payment has ID: a1b2c3d4-...
  ...

═══════════════════════════════════════════════════════
  Results: 47 passed, 0 failed
═══════════════════════════════════════════════════════

Service Layer Tests

7 test groups for internal business logic

Tests the internal service classes directly (no HTTP server needed). Requires database access via DATABASE_URL.

# Run service tests (no dev server needed)
pnpm test:services

# Or directly:
npx tsx scripts/tests/test-mvp-services.ts

Test Groups

[1] Schema Tests -- Verifies all tables exist with required columns
[2] FeeEngine -- USDC/ETH/ADAO fee rates, overrides, invalid input handling
[3] SettlementService -- Full payment lifecycle (create, detect, confirm, forward, cancel, expire), idempotency, stats
[4] WebhookEngine -- HMAC-SHA256 signature generation and verification
[5] UsageService -- Metric increment, current usage, limit checks
[6] API Auth -- Key generation format (pd_live_, pd_test_), uniqueness
[7] SpendingCaps -- Cap retrieval, spending checks

Wallet Service Tests

CDP wallet creation and gas funding

Tests the Coinbase CDP integration for wallet management. Requires CDP credentials in .env.

# Run wallet tests (requires CDP credentials)
pnpm test:wallets

# Or directly:
npx tsx scripts/tests/test-wallet-services.ts

Note: Wallet tests interact with Coinbase CDP and may create real wallets on Base mainnet. Run these only when you need to verify CDP integration.

Manual API Testing with cURL

Quick smoke tests you can run from the terminal

1. Create a payment

curl -s -X POST http://localhost:3000/api/v1/payments \
  -H "Authorization: Bearer $TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenSymbol": "USDC",
    "amount": "10.00",
    "merchantWallet": "0x0000000000000000000000000000000000000001"
  }' | jq .

2. List payments

curl -s http://localhost:3000/api/v1/payments?limit=5 \
  -H "Authorization: Bearer $TEST_API_KEY" | jq .

3. Verify a payment

curl -s -X POST http://localhost:3000/api/v1/verify \
  -H "Authorization: Bearer $TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paymentId": "YOUR_PAYMENT_ID"}' | jq .

4. Test error handling

# Missing auth (should return 401)
curl -s http://localhost:3000/api/v1/payments | jq .

# Invalid token (should return 400)
curl -s -X POST http://localhost:3000/api/v1/payments \
  -H "Authorization: Bearer $TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tokenSymbol": "INVALID", "amount": "10", "merchantWallet": "0x0000000000000000000000000000000000000001"}' | jq .

Run All Tests

# Run all test suites
pnpm test:all

# Or run individually:
pnpm test:api        # API integration (needs dev server + TEST_API_KEY)
pnpm test:services   # Service layer (needs DATABASE_URL)
pnpm test:wallets    # Wallet services (needs CDP credentials)

Next Steps

All tests passing? You're ready to integrate payments into your app.
Having failures? Check the Troubleshooting guide.
Review the Error Codes reference for specific error details.