A Crypto Payment API helps you accept cryptocurrencies more easily by handling wallet setup, payment tracking, and confirming transactions. It turns complicated blockchain processes into a smooth experience for websites, apps, or backend systems. This guide shows you how to integrate OxaPay’s Crypto Payment API step by step—making it easy to accept crypto payments whether you’re a developer or running an online business.
What Is a Crypto Payment API?
A Crypto Payment API is a set of tools that lets your website, app, or backend system accept and manage crypto payments more easily. Instead of creating wallet addresses manually, waiting for blockchain confirmations, or checking payment statuses yourself, the API handles everything—generating invoices, tracking payments, and updating order status in real time.
Think of it like a digital cashier built for crypto. You send it the amount and order details, and it gives your customer a unique wallet address or payment link. Once the payment is made, the API notifies your system instantly—no manual steps, no technical confusion.
Common Questions About Crypto Payment APIs
💬 Do I need to know how to code to use a crypto payment API?
Yes, if you plan to integrate it directly into a custom website or application, you’ll need some basic programming skills—usually in JavaScript, Python, or PHP. However, if you’re using a platform like WooCommerce or WordPress, many providers (including OxaPay) offer ready-to-use plugins that require no coding at all.
💬 Can I accept multiple cryptocurrencies with one integration?
Absolutely. A good Crypto Payment API allows you to accept several coins—like BTC, ETH, USDT (TRC-20, ERC-20, etc.), and others—through a single, unified setup. As a result, this saves time and makes your payment flow more efficient.
💬 How fast are crypto payments using an API?
The API detects incoming payments as soon as they appear on the blockchain. Most APIs, like OxaPay’s, send instant status updates via Webhook, so your system is notified within seconds—no need to refresh or check manually.
💬 Is it secure to accept crypto through an API?
Yes, if best practices are followed. This includes using HTTPS, protecting your API key, checking Webhook data, and optionally limiting allowed IPs. OxaPay supports all of these.
💬 Can I test the system before accepting real payments?
Yes. OxaPay provides a Sandbox mode that simulates the full payment flow—perfect for testing without risking real crypto.
💬 How do I display the payment request to my customers?
Most Crypto Payment APIs return a payment link or wallet address after invoice creation. For example, you can display the address directly on your checkout page or alternatively, redirect the customer to a secure hosted payment page. OxaPay supports both methods, allowing you to choose the one that best fits your design and user experience.
💬 How do I track the payment status?
These APIs typically send status updates through Webhooks. As soon as a payment is made, the system sends your backend a real-time message showing the payment status—such as “paid,” “confirming,” or “expired.” This enables your platform to automatically update the order without any manual action.
Why OxaPay’s Crypto Payment API Stands Out
A good Crypto Payment API should be easy to implement, secure by default, and flexible enough to support different business models. OxaPay delivers on all three. Its API is simple, clearly explained, and requires no KYC—making it ideal for fast integration. With built-in webhook support, strong security practices, and real-time response updates, it helps both developers and businesses launch crypto payments with minimal hassle.
Key advantages of the OxaPay API:
- Clear and easy-to-follow guides for fast setup
- Stable, clearly defined API paths to ensure long-term reliability
- Consistent JSON responses for easy parsing and integration
- Built-in error handling and status codes for smooth debugging
- High availability with fast response times and low latency
- Secure architecture with API key authentication and IP allowlisting
OxaPay Crypto Payment API: Integration Guide
1. Create Your OxaPay Account and Get an API Key
Before integrating the API, you’ll need to create an account on OxaPay.com and generate your API key. This key is what connects your system to OxaPay securely.
Here’s how to get started:
- Sign up on OxaPay
Go to the homepage and click “Sign Up”. You can register using your email, Google account, or even Telegram. - Access the Merchant API section
Once logged in, go to the dashboard and click on Merchant API in the sidebar. - Generate your API key
Click the “Generate API Key” button. You’ll be asked to select which cryptocurrencies you want to accept. You can also configure:- Underpaid Coverage (e.g., accept small underpayments)
- Who pays the network fee (you or the customer)
- Copy and store your API key securely
This key is like a password—never share it publicly and avoid hardcoding it directly into front-end code.
📌 Note: You can generate multiple keys if you need different settings for different services (e.g., one for your website, one for a mobile app).
Once your API key is ready, you’re all set to start making authenticated API calls to create payment invoices.
2. Configure API Settings and Choose Supported Coins
Before you start creating invoices, it’s important to configure your API settings to match your business needs. OxaPay gives you full control over how the system should behave for each payment request.
Here’s what you can configure:
1. Choose Supported Coins
From your OxaPay dashboard, go to Merchant API > Settings and select which cryptocurrencies you want to accept. You can enable popular coins like BTC, ETH, USDT (TRC-20, ERC-20, BEP-20), USDC, DAI, and more.
📌 Tip: You can change this list anytime without generating a new API key.
2. Set Underpaid Coverage
Define how much of a small underpayment you’re willing to accept (e.g., 5%, 10%, up to 60%). This helps avoid failed transactions caused by small transfer differences or manual entry errors.
3. Define Fee Responsibility
Choose whether you (the merchant) or the customer (the payer) will cover the blockchain network fee. This directly impacts what the customer sees on the payment page.
4. Set Invoice Lifetime
Decide how long your invoices should remain active—commonly 10, 30, or 60 minutes. Once the time expires, the payment link becomes invalid unless reactivated.
For developers:
These settings are used by default, but you can change them for each invoice if needed.
Optional for Developers:
You can override default dashboard settings by including parameters in your API request JSON, as shown below.
{
"amount": 49.99,
"currency": "USDT",
"lifeTime": 30,
"underPaidCover": 10,
"feePaidByPayer": true
}
This allows you to customize invoice behavior per request, without altering your global API configuration.
Generate a Payment Invoice (createInvoice Endpoint)
Once you’ve configured your API settings, the next step is to generate a payment invoice using the createInvoice endpoint. This endpoint then creates a unique payment link or wallet address that your customer can use to pay securely.
🔧 Technical Explanation (for developers)
The createInvoice endpoint accepts several parameters:
Required parameters:
- merchant – Your API key
- amount – The total payment amount
Optional parameters:
- currency – The cryptocurrency you want to receive (e.g., “USDT”)
- orderId – Your own internal order reference
- callbackUrl – The URL OxaPay should use to notify your system of payment status
- description – Description shown on the invoice
- lifeTime – Time limit before the invoice expires (in minutes)
- feePaidByPayer – Who pays the blockchain fee
- underPaidCover – Allowed underpayment margin
- returnUrl – Redirect destination after payment
Example in Python (requests)
import requests
payload = {
"merchant": "YOUR_API_KEY",
"amount": 49.99,
"currency": "USDT",
"orderId": "ORDER-1234",
"description": "Monthly Subscription",
"callbackUrl": "https://yourdomain.com/webhook",
"returnUrl": "https://yourdomain.com/thank-you"
}
response = requests.post("https://api.oxapay.com/merchant/invoice", json=payload)
print(response.json())
This code sends your order information to OxaPay and receives a payment link that your customer can use.
Example in JavaScript (fetch)
fetch("https://api.oxapay.com/merchant/invoice", {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
merchant: "YOUR_API_KEY",
amount: 49.99,
currency: "USDT",
orderId: "ORDER-1234",
description: "Monthly Subscription",
callbackUrl: "https://yourdomain.com/webhook",
returnUrl: "https://yourdomain.com/thank-you"
})
})
.then(res => res.json())
.then(data => console.log(data));
Plain Explanation
Don’t worry if you’re not a programmer. This step is about telling OxaPay how much the customer should pay and for what. Once the request is sent, OxaPay generates a secure payment link that your customer can use to complete the transaction. This link is unique for every order and ensures that the payment is tracked and confirmed automatically.
You can think of it like sending the details of a bill to an assistant, and they instantly create a payment page for your customer—complete with tracking, security, and expiration.
Using Platforms like WordPress or WooCommerce?
You don’t need to write any code if you’re using a platform like WordPress or WooCommerce. OxaPay provides ready-to-use plugins that handle this invoice generation automatically. When a customer places an order, the plugin creates the invoice, shows the payment link, and tracks the payment—all without requiring you to touch the API.
Display the Payment Link or Wallet Address
After creating an invoice with the API, OxaPay returns a payment link. This link takes the customer to a secure page where they can complete the payment using their preferred cryptocurrency.
You can either show this link as a button on your checkout page—for example, “Pay with Crypto”—or redirect the user to it right after placing the order. This page is hosted by OxaPay, works on all devices, and updates in real time.
Alternatively, if you want more control, you can use the payLink from the response and decide how to show it. For example, you can redirect users using JavaScript.
window.location.href = response.payLink;
In addition to the payment link, you’ll also receive a trackId—a unique identifier for each invoice. This value can be saved in your database so that later, you can match payment updates to the correct customer order. Especially when using Webhooks, this ensures your system always knows which payment belongs to which order.
Moreover, you don’t need to design or host your own payment interface. OxaPay already provides a fully optimized payment page that works smoothly across all devices. Thanks to its simplicity, speed, and mobile-friendly design, you can just connect, display the link, and let the platform handle the rest.
Handle Real-Time Payment Status with Webhooks
Once a customer pays, your system needs to know—instantly and automatically. OxaPay solves this with Webhooks, which send real-time payment status updates to a URL you define during invoice creation.
This means no manual checking is required. As soon as a payment is detected or confirmed, OxaPay sends a secure HTTP POST request to your specified callbackUrl, carrying key information like the payment status, track ID, amount, and currency.
Here’s what you might receive:
{
"trackId": "abc123",
"status": "paid",
"amount": "49.99",
"currency": "USDT"
}
Common status values include:
- waiting: Invoice created, no payment yet
- confirming: Payment seen, waiting for blockchain confirmation
- paid: Payment fully confirmed
- underPaid: Partial amount received
- expired: Invoice expired due to timeout
This allows your system to react instantly—for example, by updating an order to “Paid,” activating a subscription, or sending a confirmation email.
If you’re building your own backend, it’s essential to secure and validate Webhook requests properly. Here’s a more robust Python example using Flask:
from flask import Flask, request, jsonify
app = Flask(__name__)
WEBHOOK_SECRET = "YOUR_SECRET_TOKEN"
@app.route('/webhook', methods=['POST'])
def handle_webhook():
received_secret = request.headers.get('X-Webhook-Secret')
if received_secret != WEBHOOK_SECRET:
return jsonify({"error": "Unauthorized"}), 403
try:
data = request.get_json()
track_id = data.get("trackId")
status = data.get("status")
if status == "paid":
print(f" Payment confirmed for {track_id}")
elif status == "underPaid":
print(f" Partial payment for {track_id}")
return jsonify({"status": "ok"}), 200
except Exception as e:
print(f" Webhook error: {str(e)}")
return jsonify({"error": "Bad request"}), 400
To make this even more secure:
- Only accept Webhooks from known IP addresses
- Always use HTTPS for your callback URL
- Log all incoming Webhook events for audit or troubleshooting
Even if you’re not writing code yourself, understanding this process ensures you can verify that payments are being processed and confirmed automatically and securely.
Process Payment Status in Your System
Once your system receives a payment update via Webhook, the next step is to take appropriate action inside your platform. This usually means marking an order as paid, delivering a digital product, activating a subscription, or simply notifying the customer that their payment was successful.
You’ll receive key information in the Webhook payload, such as the trackId (unique to each invoice), the status (e.g., “paid” or “underPaid”), and the amount. With this data, your system can identify which order the payment belongs to and what should happen next.
In practical terms, this might look like updating an order status in your database:
# Example logic after receiving a Webhook
if status == "paid":
mark_order_as_paid(track_id)
send_confirmation_email(user_id)
elif status == "underPaid":
notify_customer_about_remaining_balance(track_id)
If you included your own orderId when creating the invoice, you can use it here to match the payment to your internal order system. This helps ensure accuracy, especially when multiple invoices are being processed at the same time.
Even if you’re using a platform like WooCommerce or a CMS plugin, this process happens automatically in the background. But if you’re building a custom flow, it’s important to ensure that the payment data updates your system in real time, so that customers receive immediate confirmation and services are delivered without delay.
A smooth post-payment process builds trust with your users and ensures everything runs efficiently after a successful transaction.
Secure Your Integration
When working with any payment system—especially one involving cryptocurrency—security is critical. OxaPay’s API is designed with secure defaults, but it’s up to you to apply best practices when integrating it into your system.
First, treat your API key like a password. It gives full access to your payment system, so never expose it in public code, front-end scripts, or version control platforms. Always store it on the server side, in a secure environment variable or a protected config file.
Next, make sure your callbackUrl (Webhook endpoint) is protected.
OxaPay allows you to:
- Restrict accepted IP addresses, so that only OxaPay servers can access your Webhook
- Use secret tokens, either in the request header or as part of the URL, to verify the source of each incoming request
- Ensure HTTPS is always used, so that all data transfers are encrypted and safe from interception
If you want to validate incoming Webhook requests, you can compare a secret value in your server against the one sent by OxaPay. This helps ensure that the message wasn’t forged or tampered with.
Here’s a simplified example of how to validate a Webhook request using a token:
WEBHOOK_SECRET = "YOUR_SECRET_TOKEN"
@app.route('/webhook', methods=['POST'])
def handle_webhook():
if request.headers.get('X-Webhook-Secret') != WEBHOOK_SECRET:
return jsonify({"error": "Unauthorized"}), 403
# Process the payment data here
return jsonify({"status": "ok"}), 200
By following these simple steps—keeping your API key private, securing your Webhooks, and using HTTPS—you help protect your business, your users, and the integrity of your crypto payments.
Security doesn’t have to be complicated. It just needs to be consistent.
Test Everything in Sandbox Mode
Before going live with crypto payments, it’s essential to test your entire integration in a risk-free environment. OxaPay provides a full Sandbox Mode that simulates real payment behavior—without transferring any actual funds.
You can test everything: invoice creation, payment status updates, webhook handling, and even edge cases like underpayments or expired transactions.
How to Access Sandbox Mode:
- Log in to your OxaPay account.
- Go to the Merchant API section.
- Select Sandbox tab and click Generate Sandbox API Key.
- Use this key with the Sandbox API endpoint:
https://sandbox.oxapay.com/merchant/invoice
The Sandbox environment mirrors the production API exactly, but no real coins are involved—making it perfect for safe testing.
Example: Simulate an Invoice in Sandbox
import requests
payload = {
"merchant": "YOUR_SANDBOX_API_KEY",
"amount": 10,
"currency": "USDT",
"callbackUrl": "https://yourdomain.com/webhook",
"orderId": "TEST-001",
"description": "Sandbox test"
}
response = requests.post("https://sandbox.oxapay.com/merchant/invoice", json=payload)
print(response.json())
This creates a test invoice in the sandbox environment. You’ll get a payLink—open it in your browser and simulate different payment actions.
Test Scenarios to Try:
- Partial payment: Send less than the invoice amount to trigger an underPaid webhook status
- Expired invoice: Wait beyond the lifeTime (e.g., 10 minutes) to simulate expiration
- Full payment: Complete the simulated payment and verify that a paid webhook is triggered
Whether you’re writing code or using a plugin, Sandbox testing gives you confidence before you go live. It helps ensure that all systems—checkout, payment status, and fulfillment—work exactly as expected, with no surprises.
Optional: Use Advanced Endpoints
Once your basic crypto payments are working, OxaPay offers additional API tools to expand your setup:
- Swap API – Accept one coin and receive another automatically. For example, your customer pays in BTC, you get USDT—no manual conversion needed.
- Static Address API – Assign fixed wallet addresses to users for recurring or account-based deposits.
- Payout API – Automate outbound crypto transfers to users, partners, or vendors from your OxaPay balance.
These features aren’t required to accept payments, but they’re ready when you need more flexibility, automation, or scale.
Business Benefits of OxaPay’s Crypto Payment API
OxaPay’s API brings more than just easy integration—it adds real value to your business:
- Accept crypto from customers anywhere without banking restrictions.
- Reduce processing costs compared to cards or PayPal with minimal blockchain fees.
- Streamline invoicing, payment tracking, and order fulfillment automatically.
- Attract privacy-focused, tech-savvy users who prefer fast crypto payments.
- Build a scalable and resilient payment system for long-term growth.
Conclusion
Accepting crypto payments no longer requires complex infrastructure or deep blockchain knowledge. Thanks to OxaPay’s Crypto Payment API, you can now launch fast, secure, and fully automated crypto payments tailored to your business needs. Whether you’re a developer building custom flows or a business owner seeking a simple plug-and-play solution, the process is now more accessible than ever.
With this in mind, you already have the tools, the flexibility, and the support to move forward. Now, the only step left is to begin.
Get Started Now
- Create a free OxaPay account and start integrating crypto payments
- Explore the API documentation with integration examples and a full Sandbox environment for testing before going live
OxaPay crypto gateway makes crypto payments simple, secure, and scalable—designed for real-world business needs.
