1. 首頁
  2. 開發者
開發者

幾分鐘內接上加密貨幣收款

標準的 REST API:以 x-api-key 驗證、以 JSON 收送資料,透過簽章 IPN 接收狀態更新。建立型請求支援冪等金鑰,並有連接測試網的測試環境。

API 基本網址https://omniwallet.ewin888.com/api/v1/
測試環境https://omniwallet-dev.ewin888.com/api/v1/

WebMCP

AI 助理可在商戶後台查詢餘額、訂單與下發報價。實際下發仍由您在後台確認。

快速上手

  1. 01

    取得 API 金鑰

    註冊並登入後台,在「開發者 → API 金鑰」建立金鑰,再到「IPN」設定 IPN 密鑰。建議先在測試環境完成串接。

  2. 02

    建立付款

    呼叫 POST /v1/payment,帶入金額、計價幣別與收款幣種。回應中的 pay_address 是這筆付款的專屬地址,pay_amount 是應付金額。

    POST /v1/paymentcurl
    curl -X POST "https://omniwallet.ewin888.com/api/v1/payment" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: order-A-1024" \
      -d '{
        "price_amount": 120,
        "price_currency": "usd",
        "pay_currency": "usdttrc20",
        "order_id": "A-1024",
        "order_description": "Pro plan, 12 months",
        "ipn_callback_url": "https://example.com/ipn"
      }'
    回應JSON
    {
      "payment_id": 355446374401130,
      "payment_status": "waiting",
      "pay_address": "TJ8nq3M5yVfQ9C2dWkPz7aH4sLrE6uXbGt",
      "price_amount": 120,
      "price_currency": "usd",
      "pay_amount": 120.02,
      "pay_currency": "usdttrc20",
      "order_id": "A-1024",
      "network": "TRC20",
      "expiration_estimate_date": "2026-10-02T09:15:00.000Z",
      "omni_payment_url": "https://omniwallet.ewin888.com/payment/4fKq9ZtR2mXcL8vBnW1pYs"
    }
  3. 03

    引導客人付款

    把地址與金額(或 QR)顯示給客人;也可以改用 POST /v1/invoice 建立託管發票頁,再把客人導向回應中的 invoice_url。

    POST /v1/invoicecurl
    curl -X POST "https://omniwallet.ewin888.com/api/v1/invoice" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "price_amount": 49.9,
        "price_currency": "usd",
        "order_id": "A-1025",
        "order_description": "Starter plan",
        "ipn_callback_url": "https://example.com/ipn",
        "success_url": "https://example.com/thanks",
        "cancel_url": "https://example.com/cart"
      }'
    回應JSON
    {
      "id": "355447603200201",
      "order_id": "A-1025",
      "price_amount": "49.9",
      "price_currency": "usd",
      "pay_currency": null,
      "invoice_url": "https://omniwallet.ewin888.com/invoice/8hTz2QpLm4XwN7cVb1RkYe",
      "success_url": "https://example.com/thanks",
      "cancel_url": "https://example.com/cart",
      "created_at": "2026-10-01T09:20:00.000Z"
    }
  4. 04

    接收 IPN

    付款狀態每次變化,我們都會 POST 到您的 ipn_callback_url。請先驗證簽章,再依 payment_status 更新訂單。

    驗證 IPN
  5. 05

    切換到正式環境

    商戶審核通過後,在正式環境建立新的 API 金鑰與 IPN 密鑰,並把基本網址換成正式環境。

驗證 IPN 簽章

我們以您的 IPN 密鑰,對「鍵依字母排序後的 JSON」計算 HMAC-SHA512,並以十六進位字串放在 x-omni-sig 標頭。我們送出的請求本文就是這段排序後的 JSON,所以直接對收到的原始本文驗證即可。

  • 以常數時間比較簽章
  • IPN 可能重複或不依順序送達:以 payment_id 與狀態去重,必要時呼叫 GET /v1/payment/{id} 取得最新狀態
  • 回應任何 2xx 代表已收到;其他回應或逾時都會自動重試
ExpressNode.js
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const IPN_SECRET = process.env.OMNI_IPN_SECRET;

// Keep the raw body: the signature covers the exact bytes we send.
app.post('/ipn', express.raw({ type: 'application/json' }), (req, res) => {
  const received = String(req.get('x-omni-sig') || '');
  const expected = crypto
    .createHmac('sha512', IPN_SECRET)
    .update(req.body)
    .digest('hex');

  const valid = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send('invalid signature');

  const payment = JSON.parse(req.body.toString('utf8'));
  // Idempotent update: the same status can be delivered more than once.
  // await orders.applyStatus(payment.order_id, payment.payment_status);
  res.sendStatus(200);
});

app.listen(3000);
PHPPHP
<?php
$secret   = getenv('OMNI_IPN_SECRET');
$raw      = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_OMNI_SIG'] ?? '';

// The signature covers the exact bytes we send.
$expected = hash_hmac('sha512', $raw, $secret);
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('invalid signature');
}

$payment = json_decode($raw, true);
// Idempotent update: the same status can be delivered more than once.
// apply_status($payment['order_id'], $payment['payment_status']);
http_response_code(200);
FlaskPython
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
IPN_SECRET = os.environ["OMNI_IPN_SECRET"].encode()

@app.post("/ipn")
def ipn():
    raw = request.get_data()  # the exact bytes we signed
    expected = hmac.new(IPN_SECRET, raw, hashlib.sha512).hexdigest()
    received = request.headers.get("x-omni-sig", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    payment = json.loads(raw)
    # Idempotent update: the same status can be delivered more than once.
    # apply_status(payment["order_id"], payment["payment_status"])
    return "", 200
IPN 本文範例JSON
{
  "actually_paid": 120.02,
  "actually_paid_at_fiat": 120,
  "invoice_id": null,
  "order_description": "Pro plan, 12 months",
  "order_id": "A-1024",
  "outcome_amount": 119.42,
  "outcome_currency": "usdttrc20",
  "parent_payment_id": null,
  "pay_address": "TJ8nq3M5yVfQ9C2dWkPz7aH4sLrE6uXbGt",
  "pay_amount": 120.02,
  "pay_currency": "usdttrc20",
  "payment_id": 355446374401130,
  "payment_status": "finished",
  "price_amount": 120,
  "price_currency": "usd",
  "purchase_id": null,
  "updated_at": "2026-10-01T09:17:42.000Z"
}

付款狀態

付款可能的狀態如下;每次狀態變化都會送出 IPN。

狀態說明
waiting
等待付款
等待客人付款
confirming
確認中
已偵測到交易,正在等待區塊確認
confirmed
已確認
已確認入帳
sending
結算中
正在結算到您的錢包
partially_paid
部分付款
付款不足,客人可以在到期前補足
finished
已完成
付款完成
failed
失敗
付款失敗,例如命中制裁名單
refunded
已退款
已退款給付款人
expired
已過期
逾期未付款

測試環境(Sandbox)

測試環境是獨立的一套部署,連接各鏈的測試網,API 與正式環境完全相同。

  • 帳號、API 金鑰與資料都和正式環境分開,需要另外註冊;商戶審核會自動通過
  • 使用各測試網的測試幣付款,交易可以在測試網的區塊瀏覽器查到
  • 測試幣沒有實際價值,請勿把主網資產轉到測試環境的地址
網路測試網可用幣種代碼
EthereumEthereum Sepoliaeth usdc
BNB Smart ChainBNB Smart Chain Testnetbnbbsc usdtbsc
PolygonPolygon Amoymaticmainnet usdcmatic
Avalanche C-ChainAvalanche Fujiavax usdcavax
ArbitrumArbitrum Sepoliaetharb usdcarb
BaseBase Sepoliaethbase usdcbase
OptimismOP Sepoliaethop usdcop
TRONTRON Niletrx usdttrc20
SolanaSolana Devnetsol usdcsol
BitcoinBitcoin Testnet4btc

冪等與重試

所有建立資源的 POST 請求都可以帶 Idempotency-Key 標頭。遇到網路逾時,用同一個金鑰重送,不會重複建立付款或出款。

  • 同一個金鑰、相同內容:回傳第一次的結果
  • 同一個金鑰、內容不同:回應 422 IDEMPOTENCY_KEY_REUSED
  • 第一次請求仍在處理:回應 409 IDEMPOTENCY_IN_FLIGHT,請稍後重試
HTTPHTTP
POST /api/v1/payout HTTP/1.1
Host: omniwallet.ewin888.com
x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_JWT
Idempotency-Key: 6c0a8e6e-3f5b-4f7a-9a52-1f0c2d9b7e41
Content-Type: application/json

開始接受加密貨幣付款

免費註冊,先在測試環境完成串接;商戶審核通過後,就能切換到正式環境。