1. 首页
  2. 开发者
开发者

几分钟内接入加密货币收款

REST API 与 NOWPayments v1 兼容:相同的接口、字段、状态值与币种代码。使用 x-api-key 进行身份验证,并通过带签名的 IPN 接收状态更新。

API 基础 URLhttps://omniwallet.ewin888.com/api/v1/
测试环境https://omniwallet-dev.ewin888.com/api/v1/

快速入门

  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

    引导顾客付款

    向顾客展示地址与金额(或二维码);也可以改用 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

    付款状态每次变化时,我们都会向您的 ipn_callback_url 发送 POST 请求。请先验证签名,再根据 payment_status 更新订单。

    验证 IPN
  5. 05

    切换到正式环境

    商户审核通过后,在正式环境中创建新的 API 密钥与 IPN 密钥,并将基础 URL 切换为正式环境。

验证 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"
}

付款状态

状态值与 NOWPayments 相同。

状态说明
waiting
等待付款
等待顾客付款
confirming
确认中
已检测到交易,正在等待区块确认
confirmed
已确认
已确认入账
sending
结算中
正在结算到您的钱包
partially_paid
部分付款
付款不足,顾客可在到期前补足
finished
已完成
付款完成
failed
失败
付款失败,例如命中制裁名单
refunded
已退款
已退款给付款人
expired
已过期
逾期未付款

从 NOWPayments 迁移

API 相互兼容,大部分代码都无需修改。

  1. 替换基础 URL将 https://api.nowpayments.io/v1/ 替换为下方的 OmniWallet 基础 URL。
  2. 改用 OmniWallet 的 API 密钥请求头名称同样是 x-api-key。
  3. 更新 IPN 验证改用 OmniWallet 的 IPN 密钥与 x-omni-sig 请求头。如果希望现有程序完全不改,可以在后台开启 x-nowpayments-sig 兼容请求头。
  4. 确认支持的币种币种代码相同(例如 usdttrc20、usdcsol),但只能使用我们支持的币种,请通过 GET /v1/merchant/coins 或支持币种页面确认。
  5. 检查出款设置出款同样通过 POST /v1/auth 获取有效期 5 分钟的 JWT;此外,具有出款权限的 API 密钥必须设置 IP 白名单,收款地址也需先加入白名单。
API 基础 URLdiff
- https://api.nowpayments.io/v1/
+ https://omniwallet.ewin888.com/api/v1/

保持不变

  • 接口路径与 HTTP 方法
  • 请求与响应的字段名
  • 付款与出款的状态值
  • 币种代码
  • IPN 签名算法

需要注意的差异

  • IPN 签名请求头为 x-omni-sig(可选择同时发送 x-nowpayments-sig)
  • OmniWallet 的扩展字段以 omni_ 开头
  • 不支持法币出款(返回 HTTP 501)
  • 结算一律支付到后台绑定的钱包
  • 测试环境使用真实的区块链测试网

测试环境(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

开始接受加密货币支付

免费注册,先在测试环境完成对接;商户审核通过后,即可切换到正式环境。