Dynopay API Reference
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
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/userWhen 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
Create a payment
Call Create Checkout Payment with your API key and an amount. You get back a checkout URL.
Send the buyer to checkout
Redirect the buyer to the returned URL. They pick a cryptocurrency and pay.
Funds forward to your wallet
Once the payment confirms on-chain, funds are forwarded to your configured wallet, minus transparent fees.
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 Customer → Create 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:
Get your API Key
Go to your Dynopay dashboard → API section → "Create New Key". You'll receive an API key for authenticating requests.
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_keyAPI 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
/api/user/createUser
Create Customer
API KeyPayments
/api/user/createPayment
Create Checkout Payment
API Key (Bearer Optional)/api/user/cryptoPayment
Create Direct Crypto Payment
API Key (Bearer Optional)Embedded Checkout
/api/user/embed/session
Create Embedded Checkout Session
API KeyElements Inline Widget
/api/embed/public/elements/intent
Create Elements Payment Intent
Publishable Key/api/embed/public/elements/select-currency
Select Currency (Elements)
Publishable Key/api/embed/public/elements/status?intent_id=pi_...
Poll Elements Intent Status
Publishable KeyWallets
/api/user/addFunds
Add Funds to Wallet
API Key (Bearer Optional)/api/user/useWallet
Debit from Wallet
API Key (Bearer Optional)/api/user/getBalance
Get Wallet Balance
API Key (Bearer Optional)Transactions
/api/user/getTransactions
List Transactions
API Key (Bearer Optional)/api/user/getSingleTransaction/:id
Get Transaction Details
API Key (Bearer Optional)/api/user/getCryptoTransaction/:address
Verify Crypto Payment
API Key (Bearer Optional)Currencies
/api/user/getSupportedCurrency
Get Supported Currencies
API KeyMerchant Wallet Management
/api/admin/customers/:customerId/credit
Credit Customer Wallet
API Key/api/admin/customers/:customerId/debit
Debit Customer Wallet
API KeyWebhooks
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
| Event | Description | Action |
|---|---|---|
payment.pending | Crypto deposit detected on the blockchain (unconfirmed) | Show "payment received" to user — wait for confirmation |
payment.confirmed | Payment fully confirmed (sufficient blockchain confirmations) | Fulfill the order / deliver the product |
payment.underpaid | Partial 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
| Header | Description |
|---|---|
Content-Type | application/json |
X-DynoPay-Event | The event type (e.g. payment.confirmed) |
X-DynoPay-Signature | HMAC-SHA256 signature for payload verification |
X-DynoPay-Timestamp | Unix timestamp of when the webhook was sent |
X-DynoPay-Webhook-Id | Unique 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
| Priority | Source | When to Use |
|---|---|---|
1st | Per-payment webhook_url field | Different webhook per payment or product |
2nd | API Key webhook settings | Different webhook per API integration |
3rd | Company default settings | Same 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 Category | Limit | Window |
|---|---|---|
| Payment creation | 30 requests | 1 minute |
| General API | 100 requests | 1 minute |
| Authentication (login) | 10 requests | 15 minutes |
| Webhook delivery | 200 requests | 5 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" }]
}| Status | Meaning |
|---|---|
400 | Bad Request — missing or invalid parameters |
401 | Unauthorized — invalid or missing API key / token |
403 | Forbidden — API key disabled or company inactive |
404 | Not Found — resource does not exist |
500 | Server Error — something went wrong on our side |
Ready to get started?
Join merchants worldwide accepting crypto with Dynopay