API Documentation

Payments API

Create and manage payments on Base mainnet. Supports USDC, ETH, and ADAO with automatic fee deduction and forwarding to the merchant wallet.

Payment Lifecycle

Every payment moves through these statuses

Status	Description
pending	Payment created, waiting for on-chain transfer to the workspace receiving address
detected	Incoming transfer detected on Base (not yet confirmed)
confirmed	Required block confirmations met
forwarded	Net amount sent to merchant wallet, fee sent to treasury. Settlement complete.
failed	Settlement failed (insufficient funds, chain error, etc.)
expired	No transfer received within the expiry window (default: 60 minutes)
cancelled	Merchant cancelled the payment before it was confirmed

Sandbox behavior: In sandbox mode (using pd_test_ keys), the full lifecycle completes instantly — pending → detected → confirmed → forwarded — with no real on-chain transactions.

POST

/api/v1/payments

Create a new payment

Request Body

Field	Type	Required	Description
`tokenSymbol`	string	Yes	`"USDC"`, `"ETH"`, or `"ADAO"`
`amount`	string	Yes	Positive amount (e.g. `"15.00"`)
`merchantWallet`	string	Yes	Destination Base address (`0x...`, 42 chars)
`description`	string	No	Human-readable description
`metadata`	object	No	Arbitrary key-value metadata (e.g. orderId)
`expiresInMinutes`	number	No	Minutes until expiry (default: 60)
`walletType`	string	No	`"eoa"` or `"smart_wallet"`. Which wallet receives the payment. Defaults to workspace setting.

Headers

Header	Required	Description
`Authorization`	Yes	Bearer pd_test_... or pd_live_...
`Idempotency-Key`	No	Unique string to prevent duplicate payments

cURL Example

curl -X POST https://www.paydirect.com/api/v1/payments \
  -H "Authorization: Bearer pd_test_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-attempt-1" \
  -d '{
    "tokenSymbol": "USDC",
    "amount": "100.00",
    "merchantWallet": "0xYourBaseAddress...",
    "description": "Invoice #1234",
    "metadata": { "orderId": "ORD_123", "customer": "alice" }
  }'

TypeScript SDK

const { payment, receivingAddress } = await client.createPayment({
  tokenSymbol: "USDC",
  amount: "100.00",
  merchantWallet: "0xYourBaseAddress...",
  description: "Invoice #1234",
  metadata: { orderId: "ORD_123" },
});

Response (201 Created)

{
  "payment": {
    "id": "a1b2c3d4-e5f6-...",
    "workspace_id": "ws-uuid-...",
    "token_symbol": "USDC",
    "gross_amount": "100.00",
    "fee_amount": "1.50",
    "net_amount": "98.50",
    "merchant_wallet": "0xYourBaseAddress...",
    "status": "pending",
    "environment": "sandbox",
    "description": "Invoice #1234",
    "metadata": { "orderId": "ORD_123", "customer": "alice" },
    "expires_at": "2026-02-16T15:36:22Z",
    "created_at": "2026-02-16T14:36:22Z"
  },
  "receivingAddress": "0xWorkspaceWalletAddress..."
}

GET

/api/v1/payments

List payments for the workspace

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (pending, detected, confirmed, forwarded, failed, expired, cancelled)
`environment`	string	Filter by environment (sandbox, live)
`limit`	number	Max results (1-100, default: 50)
`offset`	number	Pagination offset (default: 0)

Example

curl "https://www.paydirect.com/api/v1/payments?status=forwarded&limit=10" \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "payments": [ { ... }, { ... } ],
  "total": 42
}

GET

/api/v1/payments/:id

Retrieve a single payment by ID

Path Parameters

Parameter	Description
`id`	Payment UUID

curl https://www.paydirect.com/api/v1/payments/a1b2c3d4-e5f6-... \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "payment": {
    "id": "a1b2c3d4-e5f6-...",
    "status": "forwarded",
    "token_symbol": "USDC",
    "gross_amount": "100.00",
    "fee_amount": "1.50",
    "net_amount": "98.50",
    ...
  }
}

Returns 404 if the payment does not exist or does not belong to the authenticated workspace.

POST

/api/v1/payments/:id/cancel

Cancel a pending payment

curl -X POST https://www.paydirect.com/api/v1/payments/a1b2c3d4.../cancel \
  -H "Authorization: Bearer pd_test_abc123..."

Response (200 OK)

{
  "payment": {
    "id": "a1b2c3d4-...",
    "status": "cancelled",
    ...
  }
}

Only payments in pending status can be cancelled. Returns 400 if the payment is already confirmed or forwarded. Fires a payment.cancelled webhook event.

POST

/api/v1/verify

Verify that a payment has been settled

Request Body

Field	Type	Description
`paymentId`	string	The payment UUID to verify

curl -X POST https://www.paydirect.com/api/v1/verify \
  -H "Authorization: Bearer pd_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"paymentId": "a1b2c3d4-..."}'

Response (200 OK)

{
  "verified": true,
  "payment": {
    "id": "a1b2c3d4-...",
    "status": "forwarded",
    ...
  }
}

verified is true only when the payment status is forwarded (fully settled). Use this endpoint to confirm settlement before fulfilling orders.