DynoPay API Reference

Overview

Dynopay provides a simple API to accept cryptocurrency payments, manage customer wallets, and track transactions. Payments are forwarded to your configured wallet as soon as they confirm on-chain, with transparent fees. Every endpoint on this page is a merchant endpoint — authenticated with your API key.

Base URL

All merchant endpoints are relative to the base URL below. A path shown as /createPayment is called at https://dynopay.com/api/user/createPayment.

bashhttps://dynopay.com/api/user

Ways to accept payments

Pick whichever fits your stack — every method settles the same way (crypto in, forwarded to your wallet, webhook fired on status change). No code? Start with a Payment Link or a Buy Button.

• Hosted Checkout — call Create Checkout Payment, get a checkout_url, and redirect the buyer to a Dynopay-hosted page. Zero front-end work. See Payments.
• Payment Links — create a reusable link in the dashboard (or via API) and share it by email, chat, or QR — e.g. dynopay.com/aBc123. Great for invoices and one-off requests, no site needed.
• Buy Button — drop a <dynopay-buy-button> snippet on any page (Webflow, WordPress, plain HTML). A “Buy Now” button opens checkout in a modal. See Buy Button below.
• Direct API — call Create Direct Crypto Payment to get an address + QR and render your own pay screen. Full control. See Payments.
• Embedded Checkout (iframe) — mount the full checkout inside your page with embed.js + a server-created session. See Embedded Checkout.
• Elements — render the pay UI (currency picker, address, QR, live status) directly in your DOM, no iframe. See Elements Inline Widget.
• Webhooks — required for reliable fulfilment: Dynopay POSTs your server the moment a payment’s status changes. See Webhooks.

When to use each section

• Customers — optional. Create a customer to track payments and balances per buyer. Skip it for one-off “userless” checkouts.
• Payments — the core of the API. Create a hosted checkout or a direct crypto payment and the buyer pays in crypto.
• Wallets — top up, debit, and check a customer’s wallet balance.
• Customer Wallet Adjustments — credit or debit a customer’s store-credit balance programmatically (refunds, rewards, fees).
• Transactions — look up payment and transaction history.
• Currencies — list the cryptocurrencies you can accept.
• Webhooks — get notified the moment a payment’s status changes.

A typical payment, end to end

Getting Started

Integrate Dynopay in just two steps — no customer creation needed:

Quick Example (Userless — API Key Only)

bash# Create a checkout payment — just your API key, no customer setup!
curl -X POST https://dynopay.com/api/user/createPayment \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50, "redirect_uri": "https://yoursite.com/thanks"}'

# Or create a direct crypto payment with QR code:
curl -X POST https://dynopay.com/api/user/cryptoPayment \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25, "currency": "BTC", "redirect_uri": "https://yoursite.com/done"}'

# Optional: Create a customer for per-customer tracking
curl -X POST https://dynopay.com/api/user/createUser \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "email": "jane@example.com"}'

Try It Live

Run this request right now — no signup and no API key setup. It hits our public sandbox endpoint, returns an ephemeral payment link and never touches real funds or your data. Rate-limited per IP.

Request

bashcurl -X POST "https://dynopay.com/api/public/sandbox/payment-links" \
  -H "Authorization: Bearer dyno_sk_sandbox_demo_9f621db8" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "description": "Pro Plan – Monthly",
    "customer_email": "customer@example.com"
  }'

Sample response

json{
  "object": "payment_link",
  "id": "plink_sandbox_2727324c61ebfb8b",
  "livemode": false,
  "sandbox": true,
  "status": "awaiting_payment",
  "amount": 49.99,
  "currency": "USD",
  "checkout_url": "https://dynopay.com/pay/…",
  "expires_at": "2026-07-05T16:14:12.536Z",
  "supported_chains": ["USDT-TRC20", "USDT-ERC20", "USDT-BEP20"]
}

The sandbox key dyno_sk_sandbox_demo_9f621db8 is public and only works on this endpoint. When you are ready to go live, create your own API key in the dashboard and switch to the real endpoints below — the request shape is the same. You can also open the live checkout demo to see what your customers experience.

Authentication

Your API key is all you need. Every server-side endpoint authenticates with a single x-api-key header — no customer login and no token exchange. Two other key types exist only for specific cases:

x-api-key: dpk_live_Ab3k…

# Browser only
pk_live_xxxxxxxxxxxx

x-api-key: your_api_key
# Optional (advanced):
Authorization: Bearer {token_from_createUser}

Customers

Payments

Embedded Checkout

javascript// 1) SERVER — create a session with your SECRET api key
const r = await fetch('https://dynopay.com/api/user/embed/session', {
  method: 'POST',
  headers: { 'x-api-key': process.env.DYNOPAY_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 49.99, currency: 'USD', webhook_url: 'https://you.com/webhooks/dynopay' }),
});
const { client_secret } = (await r.json()).data;   // safe to send to the browser

// 2) BROWSER — load embed.js from your checkout origin, then mount inline
Dynopay.initEmbeddedCheckout({
  fetchClientSecret: async () => client_secret,
}).then((checkout) => checkout.mount('#dynopay-checkout'));
// ...or Dynopay.openCheckout({ fetchClientSecret }) to open it as a modal.

Elements Inline Widget

Wallets

Transactions

Testing (Sandbox)

Webhook Events

Currencies

Customer Wallet Adjustments

Payment Statuses

Every crypto payment carries a normalized payment_status. You get it back from every create call, from GET /getPaymentStatus/:payment_id, and inside the payment.* webhooks. Fulfil the order once it reaches settled — the convenience flag is_paid is true only when the status is settled.

Terminal statuses (settled, failed, expired, refunded) never change again — stop polling once you see one. Everything else is transitional.

Underpayments: how much is left to pay

When a customer sends less than the requested amount the payment goes underpaid and the deposit address stays open for the remainder during the grace period. GET /getPaymentStatus/:payment_id (and the payment.underpaid webhook) report exactly how much arrived and how much is still owed:

The customer can complete the payment by sending amount_remaining in the same coin to the same address before the grace period ends — no new payment is needed.

Confirming a payment: webhooks vs. polling

Buy Button

The Buy Button is the fastest way to sell without writing back-end code. Create a button once in the dashboard, then paste a small HTML snippet anywhere — a landing page, Webflow, WordPress, a blog, even an email-linked page. Your shopper clicks Buy Now and the Dynopay hosted checkout opens in a modal (or inline). The amount is fetched securely from our server by button-id, so it can never be tampered with in the browser.

1 · Create a button

1. Go to Developers → Buy Buttons in your dashboard.
2. Set a label, a fixed price (or a min/max range so the customer chooses), and the currencies you accept.
3. Copy the generated snippet. It already includes your publishable key (pk_live_…) and button id (btn_…).

2 · Paste the snippet

html<!-- Dynopay embed SDK — load once per page -->
<script src="https://checkout.dynopay.com/v1/embed.js"></script>

<!-- Paste the button anywhere on your page -->
<dynopay-buy-button
  publishable-key="pk_live_your_key"
  button-id="btn_xxxxxxxx"
  mode="modal"
  theme="dark"
></dynopay-buy-button>

Attributes

Webhooks

Dynopay sends webhook notifications to your configured URL when payment events occur. You set the webhook_url when creating a payment, or configure a default in your company settings.

Event Types

Webhook Payload

All webhook events are sent as POST requests with a JSON body to your configured URL.

json{
  "event": "payment.confirmed",
  "payment_id": "pay_abc123def456",
  "transaction_id": "txn_789xyz",
  "amount": 0.00042,
  "currency": "BTC",
  "base_amount": "25.00",
  "base_currency": "USD",
  "status": "completed",
  "customer_email": "jane@example.com",
  "merchant_id": 38,
  "destination_tag": null,
  "meta_data": { "order_id": "ORD-12345" },
  "timestamp": "2025-07-15T12:00:00.000Z"
}

Webhook Headers

Signature Verification

Verify the signature header to ensure webhook requests are authentic and haven't been tampered with. Prefer X-Dynopay-Signature-V2: it is signed over the exact bytes on the wire, so you can verify it in any language without re-serialising the parsed JSON. Both headers are sent while you migrate; the legacy X-DynoPay-Signature will be removed after the migration window closes. Signatures are sent only when your endpoint has a signing secret — saving a webhook URL (or creating an API key) auto-generates a whsec_… secret (shown once); endpoints without one receive the payload unsigned.

Signing spec

• Signed message — the exact string {t}.{rawBody}: the timestamp, a literal dot, then the raw request-body bytes. No webhook id, no re-serialisation.
• HMAC key — your signing secret used verbatim: the full whsec_… string (its UTF-8 bytes). Do not strip the whsec_ prefix and do not base64-decode it.
• Algorithm — HMAC-SHA256.
• Encoding — lowercase hex (this is the v1= value).
• Timestamp t — Unix seconds (the same value as the X-DynoPay-Timestamp header). Reject anything outside ±300s to stop replays.

Which secret signs which endpoint

Each endpoint is signed with its own secret. Your account / dashboard endpoint is signed with your account webhook secret (the whsec_… shown once when you save the URL). A per-payment webhook_url is signed with the secret in effect on that payment. Always verify a request with the secret that belongs to the endpoint receiving it.

V2 (recommended)

javascriptconst crypto = require('crypto');

// Verify against the RAW request body. Reject anything older than ±300s (replay).
function verifyWebhookV2(rawBody, headerV2, secret, toleranceSec = 300) {
  const tokens = String(headerV2).split(',').map((s) => s.trim());
  const t = Number((tokens.find((p) => p.startsWith('t=')) || '').slice(2));
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  const exp = Buffer.from(expected, 'hex');
  // During a secret rotation DynoPay sends MULTIPLE v1= values (current +
  // previous, ~24h grace). Match if ANY verifies — always scan them all,
  // never just parse a single v1 (Object.fromEntries would drop all but the last).
  return tokens
    .filter((p) => p.startsWith('v1='))
    .some((p) => {
      const got = Buffer.from(p.slice(3), 'hex');
      return got.length === exp.length && crypto.timingSafeEqual(got, exp);
    });
}

// Express — capture the raw body so the bytes are byte-identical to what was signed.
app.post('/webhooks/dynopay', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString();
  const v2 = req.headers['x-dynopay-signature-v2'];

  if (v2 && !verifyWebhookV2(rawBody, v2, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody);
  // Fulfill based on event.event (payment.confirmed, payment.pending, ...)
  res.status(200).json({ received: true });
});

Test vector

Feed these exact inputs to your HMAC routine — if you get the same v1, your signing is byte-correct and any remaining failure is header parsing (see rotation note above).

textsecret        = whsec_test_secret_example
t             = 1700000000
raw_body      = {"event":"payment.settled","payment_id":"pay_123","amount":19.99}
signed string = 1700000000.{"event":"payment.settled","payment_id":"pay_123","amount":19.99}
v1 (hex)      = f49a2735cfb74e9d7a03537ff1af830cf6876f25cd1cb42fe4143bf2e5cb1c66

V1 (legacy)

javascriptconst crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return signature === expectedSignature;
}

// In your Express webhook handler:
app.post('/webhooks/dynopay', (req, res) => {
  const signature = req.headers['x-dynopay-signature'];
  const isValid = verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  switch (req.body.event) {
    case 'payment.confirmed':
      // Fulfill order
      break;
    case 'payment.pending':
      // Show pending status
      break;
    case 'payment.underpaid':
      // Notify customer
      break;
  }

  // Always return 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Webhook URL Priority

Rate Limits

Dynopay enforces rate limits to ensure platform stability. Limits are applied per IP address and per API key.

Error Handling

All errors return the human-readable message plus a machine-readable error object — a stable type and code you can branch on, the offending param, a doc_url, and a request_id (also returned as a Request-Id response header — quote it when contacting support). The legacy success/message/errors fields are unchanged, so existing integrations keep working.

json{
  "success": false,
  "message": "Amount must be greater than or equal to 5",
  "errors": [{ "key": "amount", "error": "Invalid amount" }],
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "Amount must be greater than or equal to 5",
    "param": "amount",
    "doc_url": "https://dynopay.com/documentation#errors",
    "request_id": "req_8f3c2a1b"
  }
}

error.type is one of invalid_request_error, authentication_error, rate_limit_error or api_error.

Error codes

Branch on error.code — these stay stable even if we reword a message.

Idempotent retries

Send an Idempotency-Key header on any POST (a unique value per logical request, e.g. a UUID) to make it safe to retry. If a network blip makes you retry, the same key + same body replays the original response — with an Idempotent-Replay: true header — so a payment is never created twice. Reusing a key with a different body returns 409 idempotency_key_reused; keys are remembered for 24 hours.

bashcurl https://api.dynopay.com/api/user/createPayment \
  -H "x-api-key: $DYNOPAY_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-ce2a-4b7d-9a1e-1b2c3d4e5f60" \
  -H "Content-Type: application/json" \
  -d '{"amount": 25, "redirect_uri": "https://your-site.com/thanks"}'