NOWPayments 互換 API

パス、x-api-key ヘッダー、リクエストとレスポンスのフィールド、ステータス、x-nowpayments-sig の IPN 署名は NOWPayments のドキュメントに従うため、既存のコードは通常、新しいベース URL、API key、IPN secret を用意するだけで動きます。ほかのサービスからの移行ですか?移行の概要をご覧ください。

内部では通常の blockwallets の請求です。受取アドレスはあなたのもの、決済ページは当社のホスト型決済ページで、支払いはオンチェーンで承認され、2つ目のノードでも照合されて初めて有効になります。以下では、3つのステップに続けて、各 API の対応範囲と元のサービスとの違いを説明します。実装していないパラメーターは、黙って無視されることなくエラーを返します。

3つのステップ

1. 加盟店アカウントを取得し(トップページから申し込み)、管理画面「開発者 › 連携とキー」の「サイトのドメイン」にドメインを追加します。コールバック URL(ipn_callback_url)とリダイレクト URL(success_url / cancel_url / redirect_url)は、これらのドメイン上、またはコールバック URL のドメイン上である必要があります。キーが漏えいしても、Webhook を別の場所に向けることはできません。
2. 加盟店管理画面の「開発者 › 連携とキー」で互換の認証情報を発行します。本番用とテスト用が1組ずつあり、NOWPayments は API key + IPN secret、Coinbase Commerce は API key + webhook shared secret です。表示は一度だけで、当社にはハッシュ / 暗号文だけを保存します。
3. コードを下記のベース URL に向け、新しいキーを使います。まずテスト用の認証情報でテストネット上で動かし、そのあと本番に切り替えてください。

NOWPayments

- const NP = "https://api.nowpayments.io/v1";
+ const NP = "https://blockwallets.io/nowpayments/v1";

const res = await fetch(`${NP}/payment`, {
  method: "POST",
  headers: { "x-api-key": process.env.NOWPAYMENTS_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    price_amount: 49.9, price_currency: "usd", pay_currency: "usdttrc20",
    order_id: "A-1001", order_description: "Pro plan",
    ipn_callback_url: "https://shop.example/ipn/nowpayments",
  }),
});
const { payment_id, pay_address, pay_amount } = await res.json();

対応エンドポイント

非対応:払い出し、換算、カストディのサブパートナー、サブスクリプション、update-merchant-estimate、法定通貨での決済。これらのパスは 404 を返します。

IPN コールバック

決済が最終ステータスになると、作成時に指定された ipn_callback_url に POST します。x-nowpayments-sig = HMAC-SHA512(IPN secret, キーで再帰的に並べ替えた JSON) で、NOWPayments の検証コードとまったく同じです。送信するボディはすでに並べ替え済みのコンパクトな JSON なので、生のボディに対する HMAC でも検証できます(PHP / Python では、非常に小さい小数の再エンコードが JS と異なることがあるため、こちらが最も安全です)。失敗したコールバックは 1 分後、5 分後、30 分後、…と再試行し、合計 8 回です。

import crypto from "node:crypto";

// Same as the NOWPayments docs (our body is already sorted, so hashing the raw body works too)
function sortObject(obj) {
  return Object.keys(obj).sort().reduce((r, k) => {
    r[k] = obj[k] && typeof obj[k] === "object" ? sortObject(obj[k]) : obj[k];
    return r;
  }, {});
}
function verifyIpn(params, sig, ipnSecret) {
  const hmac = crypto.createHmac("sha512", ipnSecret).update(JSON.stringify(sortObject(params))).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyIpn(req.body, req.headers["x-nowpayments-sig"], process.env.NOWPAYMENTS_IPN_SECRET)

$raw = file_get_contents('php://input');
$data = json_decode($raw, true);
tksort($data);  // the recursive ksort from the NOWPayments docs
$hmac = hash_hmac('sha512', json_encode($data, JSON_UNESCAPED_SLASHES), trim($ipnSecret));
$ok = hash_equals($hmac, $_SERVER['HTTP_X_NOWPAYMENTS_SIG'] ?? '');

confirmed、sending、failed は送信されません。承認されると finished になって残高に計上され、転送は行いません。

通貨ティッカー

NOWPayments との相違点

• price_currency は usd のみ(加えて 1:1 の usdt / usdc)。ほかの法定通貨は 400 を返します。
• pay_amount(暗号資産の固定額)、payout_address / payout_currency / payout_extra_id、customer_email には対応しておらず、400 を返します。
• is_fixed_rate は受け付けますが効果はありません。レートは常に固定します(BTC / LTC などは複数の取引所の中央値で、30 分間)。is_fee_paid_by_user が true の場合、プラットフォーム手数料が pay_amount に上乗せされます(プラットフォーム手数料は 1%、取扱高が増えると下がります。料金を参照)。
• 決済の有効期間は最長 12 時間です(NOWPayments は 7 日)。partially_paid_url は保存されてそのまま返されますが、決済ページはそこへリダイレクトしません。
• payment_id は 10 桁の数字です。/invoice で作成したインボイスでは、決済の payment_id がインボイスの id と同じで、インボイスにはちょうど1件の決済があります(parent_payment_id による再入金はありません)。
• 送信されるのは最終ステータスと partially_paid の IPN のみです(上の表)。waiting / confirming は送信しません。fee.serviceFee はプラットフォーム手数料(受取額 × 請求作成時の料率、標準 1%)で、ほかの手数料は 0 です。

テストモード

テスト用の認証情報で作成したチャージと決済は各チェーンのテストネットで動き、その Webhook はテスト用の IPN secret / shared secret で署名されます。本番とは完全に分離されており、テスト用のキーから本番の決済は見えません。

そのほか(決済ページ、承認、ネットワークと最低額、返金)はメインのドキュメントのとおりに動作します。