API Reference

Coming Soon. The public REST API is currently under development. This page outlines the planned API surface for reference. In the meantime, use the Widget, Payment Links, or WordPress Plugin to accept payments.

## Overview

The DirectCryptoPay API will provide full programmatic control over payment intents, payment status, and merchant configuration. The API follows RESTful conventions and uses JSON for all request and response bodies.

Base URLs

Environment	Base URL
Testnet	`https://test-api.directcryptopay.com`
Mainnet	`https://api.directcryptopay.com`

Authentication

All API requests will require authentication via the X-API-Key header:

curl -X GET https://api.directcryptopay.com/v1/payments \
  -H "X-API-Key: YOUR_API_KEY"

Planned Endpoints

Payment Intents

Method	Endpoint	Description
`POST`	`/v1/payment_intents`	Create a new payment intent
`GET`	`/v1/payment_intents/:id`	Get a payment intent by ID
`GET`	`/v1/payment_intents`	List payment intents

Payments

Method	Endpoint	Description
`GET`	`/v1/payments`	List confirmed payments
`GET`	`/v1/payments/:id`	Get a payment by ID

Webhooks

Method	Endpoint	Description
`POST`	`/v1/webhooks`	Create a webhook endpoint
`GET`	`/v1/webhooks`	List webhook endpoints
`DELETE`	`/v1/webhooks/:id`	Delete a webhook endpoint

Create Payment Intent (Preview)

POST /v1/payment_intents
Content-Type: application/json
X-API-Key: YOUR_API_KEY
Idempotency-Key: unique-request-id

{
  "amount": 49.99,
  "currency": "USD",
  "metadata": {
    "orderId": "ORD-12345",
    "customerEmail": "customer@example.com"
  }
}

Response (Preview)

{
  "id": "pi_abc123def456",
  "status": "created",
  "amount": "49.99",
  "currency": "USD",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "chains": ["ethereum", "polygon", "bsc"],
  "tokens": ["USDC", "USDT", "ETH"],
  "expiresAt": "2025-01-15T12:00:00.000Z",
  "metadata": {
    "orderId": "ORD-12345",
    "customerEmail": "customer@example.com"
  },
  "createdAt": "2025-01-15T11:00:00.000Z"
}

Get Payment Intent (Preview)

GET /v1/payment_intents/pi_abc123def456
X-API-Key: YOUR_API_KEY

Response (Preview)

{
  "id": "pi_abc123def456",
  "status": "paid",
  "amount": "49.99",
  "currency": "USD",
  "recipient": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18",
  "token": "USDC",
  "chain": "polygon",
  "chainId": 137,
  "txHash": "0x7a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0",
  "senderAddress": "0xAbCdEf0123456789AbCdEf0123456789AbCdEf01",
  "confirmedAt": "2025-01-15T11:35:00.000Z",
  "metadata": {
    "orderId": "ORD-12345"
  },
  "createdAt": "2025-01-15T11:00:00.000Z"
}

Error Codes (Preview)

HTTP Code	Error	Description
`400`	`invalid_request`	Malformed request body or missing required fields
`401`	`unauthorized`	Invalid or missing API key
`404`	`not_found`	Resource does not exist
`409`	`idempotency_conflict`	Request with same idempotency key but different parameters
`429`	`rate_limited`	Too many requests -- back off and retry
`500`	`internal_error`	Server error -- contact support if persistent

Idempotency

For POST requests, include an Idempotency-Key header to prevent duplicate operations:

POST /v1/payment_intents
X-API-Key: YOUR_API_KEY
Idempotency-Key: order-12345-attempt-1
Content-Type: application/json

{
  "amount": 49.99,
  "currency": "USD"
}

If the same Idempotency-Key is sent again with the same parameters, DCP returns the original response without creating a duplicate payment intent. If the parameters differ, DCP returns a 409 Conflict error.

Stay Updated: Follow our announcements for the public API release. In the meantime, the Widget and Webhooks provide a complete integration path.

Previous Webhook Events Next Supported Chains