API Endpoints

The Public REST API allows programmatic access to your DirectCryptoPay data. All endpoints require a Public API Key with the appropriate scope.

Base URLs#

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

Integrations (Public)#

Public endpoints for the payment widget. No API key required -- the widget validates Origin/Referer against the integration's domain allowlist. DCP-hosted pages (directcryptopay.com/pay/*) are automatically allowed.

Get Integration Config#

GET /public/integrations/:publicId

Authentication: None (public endpoint, validated by Origin header)

Returns the integration's configuration for the widget to display chain and token selectors.

curl https://api.directcryptopay.com/public/integrations/int_xxxxxxxxxxxx

Response:

{
  "publicId": "int_xxxxxxxxxxxx",
  "name": "My Store Payments",
  "allowChains": [137, 1, 56],
  "allowTokens": ["USDC", "USDT", "ETH"],
  "autoConversion": true,
  "preferredToken": "USDC",
  "chains": {
    "137": {
      "name": "Polygon",
      "tokens": [
        { "symbol": "USDC", "name": "USD Coin", "address": "0x3c49...", "decimals": 6, "isNative": false },
        { "symbol": "USDT", "name": "Tether", "address": "0xc213...", "decimals": 6, "isNative": false }
      ]
    },
    "1": {
      "name": "Ethereum",
      "tokens": [
        { "symbol": "ETH", "name": "Ethereum", "address": null, "decimals": 18, "isNative": true },
        { "symbol": "USDC", "name": "USD Coin", "address": "0xA0b8...", "decimals": 6, "isNative": false }
      ]
    }
  }
}

Create Payment Intent (Public)#

POST /public/integrations/:publicId/intent

Authentication: None (validated by Origin header against integration's domain allowlist; DCP-hosted pages are auto-allowed)

Creates a payment intent using the integration's configuration (payout address, constraints).

curl -X POST https://api.directcryptopay.com/public/integrations/int_xxxxxxxxxxxx/intent \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": "49.99",
    "currency": "USDC",
    "chainId": 137,
    "metadata": { "orderId": "ORD-12345" }
  }'

Field	Type	Required	Description
`amount_usd`	string	Yes*	Amount in USD
`amount`	string	Yes*	Amount in token smallest unit
`currency`	string	Yes	Token symbol (`USDC`, `ETH`, etc.)
`chainId`	number	Yes	Chain ID (must be in integration's `allowChains`)
`metadata`	object	No	Custom data attached to the payment
`idempotencyKey`	string	No	Prevent duplicate intent creation

*Provide either amount_usd or amount, not both.

Payment Links#

Manage payment links (payment tools) programmatically.

List Payment Links#

GET /api/v1/payment-links

Scope: payments:read

curl https://api.directcryptopay.com/api/v1/payment-links \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Response:

[
  {
    "id": "cm1abc123def456",
    "type": "LINK",
    "name": "Product Payment",
    "amount": "49.99",
    "denominationType": "CURRENCY",
    "currency": "USD",
    "url": "https://pay.directcryptopay.com/pay/cm1abc123def456",
    "status": "active",
    "views": 12,
    "payments": 3,
    "createdAt": "2025-01-15T11:00:00.000Z"
  }
]

Get Payment Link#

GET /api/v1/payment-links/:id

Scope: payments:read

curl https://api.directcryptopay.com/api/v1/payment-links/cm1abc123def456 \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Create Payment Link#

POST /api/v1/payment-links

Scope: payments:write

curl -X POST https://api.directcryptopay.com/api/v1/payment-links \
  -H "X-API-Key: dcp_pk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationId": "cm1integration123",
    "type": "LINK",
    "name": "Order #1234",
    "amount": "99.00",
    "currency": "USD",
    "denominationType": "CURRENCY",
    "returnUrl": "https://myshop.com/thank-you"
  }'

Request Body:

Field	Type	Required	Description
`integrationId`	string	Yes	Integration ID for chain/token configuration
`type`	string	Yes	`LINK`, `BUTTON`, or `WIDGET`
`name`	string	Yes	Display name for the payment
`amount`	string	Yes	Payment amount
`currency`	string	Yes	Currency code (e.g., `USD`, `USDC`)
`denominationType`	string	No	`CURRENCY` (fiat value) or `TOKEN` (crypto amount). Default: `CURRENCY`
`returnUrl`	string	No	URL to redirect after payment
`description`	string	No	Optional description
`allowCustomAmount`	boolean	No	Allow payer to enter custom amount. Default: `true`
`minAmount`	string	No	Minimum payment amount

Response: Returns the created payment link object.

Payment Intents#

Read payment intents created through widget, SDK, or payment links.

List Payment Intents#

GET /api/v1/payment-intents

Scope: payments:read

Query Parameters:

Param	Type	Description
`status`	string	Filter by status: `CREATED`, `PENDING`, `PAID`, `EXPIRED`, `FAILED`
`limit`	number	Max results (default: 50, max: 100)
`offset`	number	Skip N results for pagination

curl "https://api.directcryptopay.com/api/v1/payment-intents?status=PAID&limit=10" \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Get Payment Intent#

GET /api/v1/payment-intents/:id

Scope: payments:read

Payments#

Read confirmed on-chain payments.

List Payments#

GET /api/v1/payments

Scope: payments:read

Query Parameters:

Param	Type	Description
`status`	string	Filter by status
`limit`	number	Max results (default: 50, max: 100)
`offset`	number	Skip N results for pagination

curl "https://api.directcryptopay.com/api/v1/payments?limit=20" \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Get Payment#

GET /api/v1/payments/:id

Scope: payments:read

Events#

Read platform events (payment created, paid, webhook sent, etc.).

List Events#

GET /api/v1/events

Scope: events:read

curl https://api.directcryptopay.com/api/v1/events \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Returns the most recent 100 events for your account.

Webhooks#

Read webhook delivery logs.

List Webhook Events#

GET /api/v1/webhooks

Scope: events:read

Query Parameters:

Param	Type	Description
`limit`	number	Max results (default: 50, max: 100)
`offset`	number	Skip N results for pagination

curl "https://api.directcryptopay.com/api/v1/webhooks?limit=10" \
  -H "X-API-Key: dcp_pk_live_xxxxx"

Response:

{
  "data": [
    {
      "id": "cm1webhook123",
      "tenantId": "cm1tenant456",
      "type": "PAYMENT_CONFIRMED",
      "status": "DELIVERED",
      "createdAt": "2025-01-15T11:35:00.000Z"
    }
  ],
  "limit": 10,
  "offset": 0
}

Idempotency#

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

curl -X POST https://api.directcryptopay.com/api/v1/payment-links \
  -H "X-API-Key: dcp_pk_live_xxxxx" \
  -H "Idempotency-Key: order-12345-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"integrationId": "...", "type": "LINK", "name": "Order", "amount": "49.99", "currency": "USD"}'

Need help? See Authentication for key setup, or Error Codes for troubleshooting failed requests.

Previous Authentication Next Error Codes