Developers

Integrate once. Test everything first.

Every operation in DDXPay is a command or a query with metadata. From that one definition come the REST endpoint, the OpenAPI contract, the audit record and the AI tool — so the API is never a second-class citizen of the product.

REST API

Predictable by design.

  • Versioned under /api/v1, with a published OpenAPI contract. Every build checks that the public contract stays backward compatible.
  • Idempotent writes. Every write accepts an Idempotency-Key. Retrying is safe; reusing a key for a different request is a conflict, not a second payment.
  • Errors you can branch on. Problem details with a stable code such as payments.asset_not_supported, a human sentence in English and a correlation id for support.
  • Pagination that does not skip rows, and rate limits per tenant and per mode, so a test script cannot slow down live traffic.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "title": "payments.asset_not_supported",
  "status": 400,
  "detail": "The combination USDT on ethereum is not supported.",
  "correlationId": "00-0d382bbb59ce74377d7fc4957d0d39de-…"
}

A real response from test mode: USDT has no official contract on the Ethereum testnet, so it is refused there.

API keys

The key decides the mode — and nothing else can.

A key starting with ddx_test_ works only with test data and simulated providers; ddx_live_ only with live data. The request body has no way to change that.

Shown once

The full key is shown when it is issued and never again. We store a hash; screens and responses show a masked prefix.

Scoped, never above its issuer

Pick scopes from ready-made profiles or area by area. A key can never carry a right the person issuing it does not hold.

Rotation with a grace period

Rotating issues a successor while the old key keeps working for a while, and every key shows who issued it and when it was last used.

Webhooks

Signed, retried, and visible.

  • HMAC-SHA256 over the timestamp and the raw body, so a captured notification cannot be replayed months later.
  • Separate secrets for test and live, generated by us and shown once.
  • HTTPS only, no redirects. A failed delivery is retried eight times, doubling from 30 seconds — about an hour in total.
  • Every delivery on screen with the response code and the start of the body, a Resend button and a test event per endpoint.
  • Events for the whole life of the money: payment_intent.credited, refund.sent, withdrawal.failed, payout_run.completed, card_payment.disputed, fiat_transfer.completed and more.
POST /hooks/ddxpay HTTP/1.1
Content-Type: application/json
DDXPay-Event-Type: payment_intent.credited
DDXPay-Event-Id: 01a1d959-2cb7-7a6b-bff1-447fce628717
DDXPay-Signature: t=1794643200,v1=5f2c9e…

# signed: HMAC-SHA256(secret, "<t>.<raw body>")
# the event id de-duplicates retries

Sandbox

Break it on purpose, before your customers do.

Test mode is part of the data model, not a separate copy of the product. It runs on public testnets — Tron Nile, Ethereum Sepolia, Base Sepolia and Bitcoin testnet — and every scenario goes through the same pipeline as live money.

  • Nine scenarios: paid, underpaid, overpaid, paid after expiry, high risk, sanctioned, stuck, reorganised and wrong chain.
  • Review before you run. The sandbox shows what will arrive and how it will be judged; then it shows what the platform recorded.
  • One click or one API call — the same scenarios from the back office and from /api/v1/test/payments/simulate.
The sandbox screen: take a test payment and choose what happens to it. The sandbox screen in the dark theme.

Node.js SDK

Small on purpose.

The SDK covers what a shop really uses — creating a checkout session, reading payments and verifying webhooks — and nothing that is not its business.

  • Server-side only. It holds an API key, so it does not even compile against browser types.
  • Zero runtime dependencies — node:crypto and the built-in fetch.
  • Safe by default: an http:// base URL is refused, the key never goes into a URL, signatures are compared in constant time.
  • Reasons, not just false: a signature mismatch and a stale timestamp are different failures, because one is an attack and the other a slow queue.

npm package coming soon

import { DdxPay, verifyWebhook } from "@ddxpay/sdk";

const ddx = new DdxPay({
  baseUrl: process.env.DDXPAY_BASE_URL,
  apiKey: process.env.DDXPAY_API_KEY,
});

// Price in euros; the buyer pays USDT on Tron.
const session = await ddx.createCheckoutSession({
  reference: "order-10482",
  fiatAmount: 149,
  fiatCurrency: "EUR",
  assetSymbol: "USDT",
  chainName: "tron",
});

// session.token goes into the widget. It is shown once.

Checkout widget

About 3 KB, and it stays out of your page.

One self-executing script with no dependencies. It renders into a container you choose and never writes raw HTML into your page.

  • A session token, not a key: it is limited to one order, expires, and is useless for anything else.
  • Knows offers: when the buyer may choose the coin, the widget shows the choice and locks the rate only then.
  • No shop around it? The same widget runs on our hosted payment page for invoices and links.
<div id="ddxpay-checkout"></div>
<script
  src="https://api.example.com/pay/checkout.js"
  data-token="cs_…"
  data-base-url="https://api.example.com">
</script>

WooCommerce

A plugin, not a project.

For WooCommerce stores there is a ready plugin built on the same public API any integrator uses.

Pay on the hosted page

The buyer picks a coin on the DDXPay payment page; the order waits until the money is credited.

Signed notifications

The plugin verifies the webhook, then reads the payment itself before it marks the order paid.

Refunds from WooCommerce

The order’s Refund button requests the refund in DDXPay. PHP 7.4+, no dependencies, both order-storage modes.

The plugin is not in the WordPress plugin directory yet; we provide the package directly.

MCP

Your own AI client, with your rules.

DDXPay runs a Model Context Protocol server. An MCP client authenticates with an API key and gets exactly the tools that key and your AI settings allow.

  • Find, run and aggregate read operations — “how many USDT deposits were credited this week?” — with totals kept per asset.
  • Propose, never act. A change becomes a proposal a person confirms in the back office, or confirms in the client with a short-lived token bound to the exact arguments.
  • A test key sees test data only, and a key from one tenant never sees another.
# The back office shows this command, with a fresh key, once.
claude mcp add --transport http ddxpay \
  https://api.example.com/mcp \
  --header "Authorization: Bearer ddx_test_…"

Get a sandbox key.

We set up a test tenant for your team, with test keys and the sandbox, so you can integrate before anything touches real money.