API Overview

Uapi provides a high-performance, non-custodial crypto payment infrastructure for global merchants. Our API makes complex blockchain interactions as simple as traditional payments.

1 Authentication

All requests must include your API Key in HTTP headers. Keys are split into Test Key (sandbox) and Live Key (production).

Every request goes through these 6 checks (in order)

Integration Flow

No-Code Integration

Create a brand-new payment order and receive a checkout link.

{
  "status": "success",
  "data": {
    "order_no": "PAY2024...",          // UAPI-generated order number (used by every subsequent call)    "amount": 100.001234,              // Order amount (echoed back)    "currency": "USDT",                // Settlement token    "chain": "trc20",                  // Settlement chain    "expire_in": 600,                  // Order TTL in seconds (relative)    "payment_url": "https://...",      // Checkout URL — redirect the buyer here    "fast_sync_enabled": true          // Whether fast on-chain confirmation is enabled for this order  }
}

Query Parameters

Responses (by state)

// Paid{ "status": "paid", "tx_hash": "0x123abc..." }

// Awaiting payment{ "status": "pending" }

// Order expired{ "status": "expired" }

// Error{ "status": "error", "error": "Invalid token" }

Rate limits: 30 / min per IP, 40 / 10s per order across all IPs. Server integrators should rely on Webhook callbacks instead of polling.

When a buyer underpaid or paid in the wrong currency, the merchant can flag the order as disputed and optionally rewrite the recorded amount / currency to match what was actually received.

Headers

Body

Success Response

{
  "status": "success",
  "data": {
    "order_id": 12345,
    "order_no": "UAPI20260408001",
    "merchant_order_id": "ORD-001",
    "order_status": "disputed",
    "amount": "100.000000",
    "currency": "USDT",
    "mode": "original"
  }
}

Rate limit: 20 / min per IP. After submission the order status flips to disputed — no further Webhook will fire.

Webhook Callback

Once the on-chain transaction is confirmed, UAPI immediately sends a POST callback to the notify_url you passed when creating the order.

If notify_url is omitted when creating an order, the default webhook URL configured in Merchant Console > API Settings is used instead.

Request Headers

Request Body (flat)

{
  "status": "paid",
  "order_no": "UAPI20260408001",
  "merchant_order_id": "ORD-001",
  "amount": "100.00",
  "chain": "trc20",
  "currency": "USDT",
  "tx_hash": "0xabcdef1234567890...",
  "paid_at": "2026-04-08T10:05:00+00:00"
}

Signature Input & Verification

The signed payload is four fields concatenated: order_no + amount + merchant_order_id + timestamp. The secret is your API Key — there is no separate webhook secret.

<?php
$rawBody   = file_get_contents('php://input');
$payload   = json_decode($rawBody, true);
$signature = $_SERVER['HTTP_X_UAPI_SIGNATURE']  ?? '';
$timestamp = $_SERVER['HTTP_X_UAPI_TIMESTAMP']  ?? '';
$apiKey    = 'sk_live_your_api_key';

// reject signatures older than 5 minutes (anti-replay)
if (abs(time() - (int)$timestamp) > 300) {
    http_response_code(401); exit('Stale timestamp');
}

$signInput = $payload['order_no']
           . $payload['amount']
           . $payload['merchant_order_id']
           . $timestamp;
$expected = hash_hmac('sha256', $signInput, $apiKey);

if (!hash_equals($expected, $signature)) {
    http_response_code(401); exit('Invalid signature');
}

// dedupe on X-UAPI-Event-ID, then process the order
// return HTTP 200 to acknowledge
http_response_code(200); echo 'success';

Order State Machine

Rate Limits, Idempotency & Amount Precision

The Four Rate-Limit Layers (in order)

Idempotency Guarantees

• Create Order: POSTing the same merchant_order_id returns the existing order (same order_no and payment_url) — no duplicate is created.
• Webhook: Each event has a unique X-UAPI-Event-ID; retries reuse the same id — dedupe on it.
• Concurrency: Lock by order_no (e.g. Redis) when handling webhooks to serialize per-order work.

Amount Precision & Anti-collision

Do NOT truncate the response amount to 2 decimals client-side; show the exact UAPI-returned amount in the QR / instructions.

Supported Networks & Precision

Errors & Error Codes

External API endpoints (X-API-KEY) currently emit errors in two shapes — a short single-field form and a structured status/error/code form. Your client should handle both.

Short form (most auth / rate-limit errors)

{ "error": "Invalid API Key" }

Structured form (business errors)

{
  "status": "error",
  "error": "Plan expired. Please upgrade/renew.",
  "code": "PLAN_EXPIRED"
}

HTTP Status Codes

Common error messages & how to fix

Tools & Versions

Developer FAQ

Multi-language Integration Examples

$apiKey = 'sk_live_xxx';
$data = [
    'amount' => 100.0,
    'chain' => 'trc20',
    'merchant_order_id' => 'MY_ORDER_001',
    'notify_url' => 'https://yoursite.com/callback',
    'domain' => 'yoursite.com'
];

$ch = curl_init('https://uapi.io/api/v1/order/create.php');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$result = json_decode($response, true);
echo $result['data']['payment_url'] ?? 'Create order failed';

const axios = require('axios');

const createOrder = async () => {
  const { data } = await axios.post('https://uapi.io/api/v1/order/create.php', {
    amount: 100.0,
    chain: 'trc20',
    merchant_order_id: 'MY_ORDER_001',
    notify_url: 'https://yoursite.com/callback',
    domain: 'yoursite.com'
  }, {
    headers: {
      'X-API-KEY': 'sk_live_xxx',
      'Content-Type': 'application/json'
    }
  });
  console.log(data.data.payment_url);
};