API Documentation
API Reference
Complete reference for the PayDirect REST API. All endpoints require authentication via API key.
Authentication
All API requests must include an authorization header
Authorization: Bearer <YOUR_API_KEY>| Header | Type | Description |
|---|---|---|
Authorization | string | Bearer token with your API key |
Content-Type | string | application/json |
Idempotency-Key | string (optional) | Unique key to prevent duplicate requests |
POST
/payments
Create a new payment intent
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
amount | string | Yes | Payment amount (e.g. "15.00") |
currency | string | Yes | Currency code (USDC, ETH, etc.) |
description | string | No | Human-readable description |
metadata | object | No | Custom key-value metadata |
type | string | No | Payment type: immediate, escrow, time-locked |
Request Example
curl -X POST https://paydirect.com/api/payments \
-H "Authorization: Bearer $PAYDIRECT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": "15.00",
"currency": "USDC",
"description": "API billing payment",
"metadata": { "orderId": "ORD_123" }
}'Response (201 Created)
{
"id": "pay_01GX5K...",
"status": "pending",
"amount": "15.00",
"currency": "USDC",
"description": "API billing payment",
"metadata": { "orderId": "ORD_123" },
"createdAt": "2025-08-11T14:36:22Z",
"paymentUrl": "https://paydirect.com/pay/pay_01GX5K..."
}GET
/payments/{id}
Retrieve a payment by ID
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Payment ID (e.g. pay_01GX5K...) |
Response (200 OK)
{
"id": "pay_01GX5K...",
"status": "completed",
"amount": "15.00",
"currency": "USDC",
"description": "API billing payment",
"metadata": { "orderId": "ORD_123" },
"createdAt": "2025-08-11T14:36:22Z",
"completedAt": "2025-08-11T14:36:45Z",
"transactionHash": "0xabc123..."
}Status Enum
| Status | Description |
|---|---|
pending | Payment created, awaiting settlement |
completed | Settlement confirmed on-chain |
failed | Settlement failed (insufficient funds, chain error) |
cancelled | Payment cancelled by user or expired |
POST
/webhooks
Register a webhook endpoint
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS endpoint URL |
events | string[] | Yes | Event types to subscribe to |
Request Example
{
"url": "https://yourapp.com/webhooks/paydirect",
"events": ["payment.completed", "payment.failed"]
}Response (201 Created)
{
"id": "wh_01ABC...",
"url": "https://yourapp.com/webhooks/paydirect",
"events": ["payment.completed", "payment.failed"],
"secret": "whsec_...",
"createdAt": "2025-08-11T14:36:22Z"
}Error Codes
Standard error responses returned by the API
| HTTP Status | Error Code | Meaning |
|---|---|---|
| 400 | 40001 | Missing required fields |
| 401 | 40102 | Invalid or missing API key |
| 402 | 40203 | Invalid payment request |
| 404 | 40400 | Resource not found |
| 429 | 42900 | Rate limit exceeded |
| 500 | 50000 | Internal server error |