All systems normal
Developer Documentation

Dynopay API Reference

Everything you need to accept crypto payments, manage customer wallets, and track transactions programmatically.

Base URL

https://dynopay.com/api/user

Checkout Payments

Hosted payment page — redirect customers to complete crypto payments in a few clicks.

Learn more →

Direct Crypto API

Full control over the UI. Get wallet addresses and QR codes via API and build your own flow.

Learn more →

Customer Wallets

Create customer wallets, add funds, debit balances, and track transactions.

Learn more →

Webhooks

Receive real-time notifications when payments are confirmed, pending, or underpaid.

Learn more →

Navigation

Overview
Getting Started
Try It Live
Authentication
Customers
Create Customer
Payments
Create Checkout Payment
Create Direct Crypto Payment
Embedded Checkout
Create Embedded Checkout Session
Elements Inline Widget
Create Elements Payment Intent
Select Currency (Elements)
Poll Elements Intent Status
Wallets
Add Funds to Wallet
Debit from Wallet
Get Wallet Balance
Transactions
List Transactions
Get Transaction Details
Verify Crypto Payment
Currencies
Get Supported Currencies
Merchant Wallet Management
Credit Customer Wallet
Debit Customer Wallet
Webhooks
Rate Limits
Error Handling

Overview

Dynopay provides a simple API to accept cryptocurrency payments, manage customer wallets, and track transactions. Payments are instantly forwarded to your configured wallet 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

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.
  • Merchant Wallet Management — credit or debit a customer’s wallet 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

1

Create a payment

Call Create Checkout Payment with your API key and an amount. You get back a checkout URL.

2

Send the buyer to checkout

Redirect the buyer to the returned URL. They pick a cryptocurrency and pay.

3

Funds forward to your wallet

Once the payment confirms on-chain, funds are forwarded to your configured wallet, minus transparent fees.

4

Get notified via webhook

Dynopay posts a webhook to your server with the final status, so you can fulfil the order automatically.

Quick Integration

Most integrations only need two API calls: Create CustomerCreate Payment. The customer pays in crypto, and funds are forwarded instantly to your wallet.

Getting Started

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

1

Get your API Key

Go to your Dynopay dashboard → API section → "Create New Key". You'll receive an API key for authenticating requests.

2

Create a Payment

Use the Checkout Payment or Direct Crypto Payment endpoint with just your API key. No customer creation needed! The customer pays in crypto, funds forward instantly to your wallet.

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": "[email protected]"}'

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": "[email protected]"
  }'

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", …]
}

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

Dynopay uses three levels of authentication depending on the endpoint:

API Key Only

Used for creating customers and listing supported currencies. Only requires the x-api-key header.

x-api-key: your_api_key

API Key (Bearer Optional)

For payments and wallet operations. Works with just the API key (userless mode). Optionally add a customer token for per-customer tracking.

x-api-key: your_api_key
# Optional:
Authorization: Bearer eyJhbGciOi...

API Key + Bearer Token

For customer-specific operations where you want per-customer history and wallet balances.

x-api-key: your_api_key
Authorization: Bearer eyJhbGciOi...

Customers

POST

/api/user/createUser

Create Customer

API Key

Payments

POST

/api/user/createPayment

Create Checkout Payment

API Key (Bearer Optional)
POST

/api/user/cryptoPayment

Create Direct Crypto Payment

API Key (Bearer Optional)

Embedded Checkout

POST

/api/user/embed/session

Create Embedded Checkout Session

API Key

Elements Inline Widget

POST

/api/embed/public/elements/intent

Create Elements Payment Intent

Publishable Key
POST

/api/embed/public/elements/select-currency

Select Currency (Elements)

Publishable Key
GET

/api/embed/public/elements/status?intent_id=pi_...

Poll Elements Intent Status

Publishable Key

Wallets

POST

/api/user/addFunds

Add Funds to Wallet

API Key (Bearer Optional)
POST

/api/user/useWallet

Debit from Wallet

API Key (Bearer Optional)
GET

/api/user/getBalance

Get Wallet Balance

API Key (Bearer Optional)

Transactions

GET

/api/user/getTransactions

List Transactions

API Key (Bearer Optional)
GET

/api/user/getSingleTransaction/:id

Get Transaction Details

API Key (Bearer Optional)
GET

/api/user/getCryptoTransaction/:address

Verify Crypto Payment

API Key (Bearer Optional)

Currencies

GET

/api/user/getSupportedCurrency

Get Supported Currencies

API Key

Merchant Wallet Management

POST

/api/admin/customers/:customerId/credit

Credit Customer Wallet

API Key
POST

/api/admin/customers/:customerId/debit

Debit Customer Wallet

API Key

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

EventDescriptionAction
payment.pendingCrypto deposit detected on the blockchain (unconfirmed)Show "payment received" to user — wait for confirmation
payment.confirmedPayment fully confirmed (sufficient blockchain confirmations)Fulfill the order / deliver the product
payment.underpaidPartial payment received (less than expected amount)Notify customer or wait for remainder during grace period

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": "[email protected]",
  "merchant_id": 38,
  "destination_tag": null,
  "meta_data": { "order_id": "ORD-12345" },
  "timestamp": "2025-07-15T12:00:00.000Z"
}

Webhook Headers

HeaderDescription
Content-Typeapplication/json
X-DynoPay-EventThe event type (e.g. payment.confirmed)
X-DynoPay-SignatureHMAC-SHA256 signature for payload verification
X-DynoPay-TimestampUnix timestamp of when the webhook was sent
X-DynoPay-Webhook-IdUnique webhook delivery ID for idempotency

Signature Verification

Verify the X-DynoPay-Signature header to ensure webhook requests are authentic and haven't been tampered with.

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 });
});

Retry Policy

If your endpoint returns a non-2xx status code (or times out), Dynopay retries delivery with exponential backoff — up to 5 retries over approximately 30 minutes. After all retries fail, the webhook is moved to a dead-letter queue. You can re-trigger failed deliveries from the dashboard.

Webhook URL Priority

PrioritySourceWhen to Use
1stPer-payment webhook_url fieldDifferent webhook per payment or product
2ndAPI Key webhook settingsDifferent webhook per API integration
3rdCompany default settingsSame webhook for all payments

Rate Limits

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

Endpoint CategoryLimitWindow
Payment creation30 requests1 minute
General API100 requests1 minute
Authentication (login)10 requests15 minutes
Webhook delivery200 requests5 minutes

When rate limited, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating when you can retry.

Error Handling

All errors follow a consistent format. Check the success field and the HTTP status code.

json{
  "success": false,
  "message": "Amount must be greater than or equal to 5",
  "errors": [{ "key": "amount", "error": "Invalid amount" }]
}
StatusMeaning
400Bad Request — missing or invalid parameters
401Unauthorized — invalid or missing API key / token
403Forbidden — API key disabled or company inactive
404Not Found — resource does not exist
500Server Error — something went wrong on our side

Ready to get started?

Join merchants worldwide accepting crypto with Dynopay