HashNutは、企業向けに安全で効率的なデジタル資産決済インフラを提供します。HashNut APIを組み込むだけで、Webサイトやモバイルアプリでデジタル資産決済を受け付けられます。
資金は加盟店のセルフカストディウォレットへ直接送金され、資産は加盟店自身が100%管理します。セキュリティレベルは、従来型銀行およびデジタルバンクを上回ります。
従来の決済システムや他の暗号資産決済ソリューションよりも高いプライバシー保護を実現します。
HashNut 決済エンジンは、Webサイトやモバイルアプリで暗号資産決済をシームレスに受け付けるための、包括的な分散型Web3決済インフラです。
オンチェーンなのは取引のみ。Web 2.5型。
世界初かつ現在唯一の、企業向けWeb3ソリューション。
決済はスマートコントラクトによって管理されます。
ClaimとWithdrawは加盟店が実行し、精算の主導権は事業者側にあります。
HashNutは加盟店資金へのアクセスも管理もできません。この設計が100%の資金安全性を支えます。
加盟店とエンドユーザー双方のプライバシーを保護し、従来の決済システムや他の暗号資産決済ソリューションよりも高い保護水準を実現します。
対応業界と決済シーンを詳しく見る。
活用シーンを見るHashNut 決済エンジンは、Webサイトやモバイルアプリで暗号資産決済をシームレスに受け付けるための、包括的な分散型Web3決済インフラです。
ユーザーは「支払う」を選ぶだけ。
QRコードを読み取るか、専用ウォレットアドレスへ送金して決済を完了できます。
DeFi決済に卸売・代理店・パートナー機能を統合した、世界唯一のソリューション。
企業自身で約5分でセットアップ。業界最速。
世界初かつ現在唯一のフルDeFi企業向けソリューション。100%の安全性（ハッキングリスク0%）と即時精算を実現します。
主要なウォレット、チェーン、トークンタイプに幅広く対応。
WeChatに匹敵するワンクリック決済体験を実現。
主要なウォレット、ブロックチェーン、デジタル資産、中央銀行デジタル通貨（CBDC）に幅広く対応。
決済プロセスは加盟店のバックエンドとシームレスに連携し、注文、請求、物流、財務データを同期。業務フロー全体をつなぎます。
注文・請求・物流・財務データを同期。
資金は加盟店のセルフカストディウォレットへ直接送金され、資産は加盟店自身が100%管理します。
顧客が指定されたデジタル資産を自身のウォレットから送金します。
HashNutが送金を検知し、確認済みの決済ステータスを返します。
請求サイクルはゼロ。
決済パターンを選ぶと、顧客のチェックアウト、オンチェーン確認、その後の加盟店業務フローまで確認できます。
HashNut 決済エンジンを金融機能の中核として活用することで、事業領域と収益機会を大きく広げられます。
顧客は注文に割り当てられた受取アドレスへ支払います。
決済はスマートコントラクトで管理され、加盟店が管理するアドレスへ着金します。
加盟店がClaimを実行し、承認済み残高をSplit Walletへ集約します。
加盟店が出金を実行し、資金を指定の送金先へ移します。
暗号資産決済市場は急速に成長しています。
Most Innovative Blockchain Project of the Year グランドウィナー
グランドファイナリスト
Fintech Applied Solutions 金賞。香港政府およびHong Kong Institute of Bankersが主催
Startup of the Year グランドアワード、Business Solutions メリットアワード
Outstanding Enterprise Payment Solution Award
香港城市大学データサイエンス学部との共同インターンシップ。
技術チームには、WeChat Pay、Monero、Visa出身の元チーフアーキテクト、テックリード、シニア開発者が在籍しています。
事業チームには、元VISA Directグローバル責任者、Cisco元ゼネラルマネージャー、Lenovoの共同創業者が参画しています。
複数のウォレットをひとつにまとめるシンプルなDeFiウォレット。個人ウォレットをNutPersonalで一元管理できます。
NutPersonalは、既存のウォレットや資産との互換性を保ちながら、決済・資産移動・ウォレット管理をひとつの体験に統合します。
法定通貨と暗号資産のどちらでも支払い可能。Visa、Mastercard、Google Pay、Apple Payなどに対応します。
HashNutのスワップ・クロスチェーン基盤を通じて、さまざまなチェーン上のトークンで支払えます。
ブロックチェーンアドレスではなくニックネーム宛に送金でき、日常的な暗号資産送金の手間を減らします。
ウォレット履歴からキャッシュフローレポートを作成し、個人のデジタル資産の動きを分かりやすく可視化します。
個人ウォレットをNutPersonalに取り込み、資産管理と支払いをひとつの場所から行えます。
複数のウォレットを統合し、資産管理や支払いに利用できます。
ウォレットをグループ化し、支払い時に複数ウォレットの資産を組み合わせられます。
代理店構造、ブランド独自のウォレット体験、HashNut 決済エンジンとの連携にも対応します。
NutPersonal上で多層代理店システムを構築し、ひとつの画面からネットワークを管理できます。
テーマ、ロゴ、機能を選び、ビジネスに合わせてNutPersonalをカスタマイズできます。
NutPersonalはHashNut 決済エンジンと連携し、決済や財務レポートに対応します。
HashNutの法人向け・個人向けウォレット製品は、パートナー向けにホワイトラベル提供できます。
HashNutアプリをApp StoreまたはGoogle Playからダウンロードできます。
NutCardは、お好みの暗号資産であらゆる国でご利用いただけます。
カード利用者向けに、シンプルなKYCオンボーディングを採用しています。
地域での事業展開に向けた代理店パートナーシップモデルに対応します。
運用と収益を効率的に管理できる専用ダッシュボードを提供します。
運用・事業面のニーズに合わせた個別サポートを利用できます。
パートナー向けインセンティブ・報酬制度で地域展開を支援します。
各市場でNutCardを展開するパートナー向けにフランチャイズネットワークを支援します。
現在のNutCard申込フローへ進みます。
加盟店アカウントをセットアップし、資金フロー全体を検証したうえで決済APIを統合し、本番運用に備えます。
HashNutは企業向けのデジタル資産決済インフラです。顧客は割り当てられた受取アドレスへオンチェーンで支払い、HashNutが決済状態を検知して加盟店の業務フローと同期します。精算の主導権は加盟店側にあります。
HashNut V4はEOAアーキテクチャと2-of-2 MPC受取アドレスを使用します。現行システムを実装する際は、V4のアカウント、SDK、API資料を同じバージョンで揃えてください。
V4の加盟店ツール、SDK、API仕様を一式で使用してください。V4統合にV3のエンドポイント例を混在させないでください。
go get github.com/nuttybounty/hashnut-sdk-go/v4HashNutのセットアップ、決済処理、精算、API統合で使用する主要用語です。
1つのチェーン上の1つの加盟店ウォレットが、1つの独立したHashNut加盟店アカウントになります。チェーンごとにSplit Wallet、API認証情報、受取アドレスプールを個別に持ちます。
ClaimとWithdrawの中心となる精算コントラクトです。顧客の支払いはまず受取アドレスへ入り、その後、加盟店がClaimを実行して承認済み残高をSplit Walletへ集約します。
決済注文に一時的に割り当てられるMPC管理アドレスです。顧客は、その注文に表示された受取アドレスへ指定のデジタル資産を送金します。
加盟店が実行するデスクトップクライアントです。デプロイ、受取アドレス作成、トークン承認、Claim、Withdraw、Sweepなど、セットアップと精算に必要なウォレット・MPC操作を処理します。加盟店の秘密鍵とクライアントパスワードは加盟店端末内に保持されます。
| 名称 | 用途 |
|---|---|
accessKeyId | 加盟店レベルのサーバーリクエストで使用する公開API Key識別子。 |
secretKey | HMAC署名用の秘密鍵。サーバー側で管理し、フロントエンドコードには絶対に公開しないでください。 |
accessSign | 注文作成時に返される注文固有の認証情報。ドキュメントに記載された注文レベルの操作で使用します。 |
注文ステータスは整数値で管理され、INIT(0) から支払い・確認済みの状態を経て FINISH(4) まで進みます。失敗・期限切れ・キャンセルは負の終端ステータスです。SUCCESS(3) が、初めて安全に履行できるステータスです。
Claim 受取アドレスの承認済み残高をSplit Walletへ集約します。 Withdraw 加盟店の利用可能な持分を、設定済みの出金アドレスへ移します。 Sweep MPC管理の受取アドレスに残ったネイティブGasコインを加盟店ウォレットへ回収します。
資金の動きと注文ステータスは分けて確認してください。支払いが成功していても、加盟店への出金まで完了しているとは限りません。
顧客が、注文に割り当てられた受取アドレスへ指定資産を送金します。
資金は割り当てられたMPC管理の受取アドレスへ着金します。HashNutによる決済検知は自動ですが、精算操作は別プロセスです。
加盟店がClaimを実行し、受取アドレスの承認済み残高をSplit Walletへ集約します。
加盟店がWithdrawを実行し、Split Wallet内の利用可能な加盟店持分を設定済みの出金アドレスへ移します。
PAIDやSUCCESSは決済ステータスを示します。一方、ClaimとWithdrawは精算フロー上で資金がどこにあるかを示します。意図的に分離されたプロセスです。
注文作成から安全に履行できる状態まで、注文がどのように進むか、また通知がその中でどう機能するかを確認します。
ドキュメントに記載されたWebhookステータスには PAID、SUCCESS、FAILED、EXPIRED があります。すべてのステータス遷移でWebhookが送られるとは限りません。通知を検証したうえでQuery Orderを実行し、正式な現在ステータスを確認してください。
正式なQuery Orderの結果が SUCCESS(3) または後続の支払い済み終端ステータスである FINISH(4) に達した時点で、1回だけ履行します。通知が重複しても二重提供されないよう、履行処理は冪等にしてください。
加盟店側で必要なツールを準備し、後回しにできる項目を整理します。まず小規模に始め、フロー全体を検証してから本番向けに拡張してください。
| 項目 | 用途 |
|---|---|
| HashNut MPC Client | 精算インフラ、受取アドレス、Claim、Withdraw、および関連する秘密鍵操作のデプロイと管理。 |
| HashNut Dashboard | 注文の作成・管理、API Keyの管理、加盟店設定の管理。 |
| 項目 | 用途 |
|---|---|
| WindowsまたはmacOS端末 | HashNut MPC Clientを実行します。 |
| 加盟店ウォレット | Gasを支払い、1つのチェーン上で1つの加盟店アカウントの基点となります。 |
| MetaMaskまたはTronLink | 対応EVMチェーンではMetaMask、TRON DashboardへのログインではTronLinkを使用します。 |
| ネイティブGasコイン | 実行するオンチェーン操作に必要な量を用意します。 |
| 出金アドレス | Withdraw後に加盟店持分を受け取る最終送金先。 |
| アプリケーションURL | notifyUrl はサーバー通知用、 callbackUrl はブラウザ復帰用です。どちらも後から変更できます。 |
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 加盟店サーバー | 顧客ブラウザ → 加盟店フロントエンド |
| 外部から到達可能？ | はい | いいえ。ローカル開発ではlocalhostを使用できます。 |
| 用途 | 決済ステータス通知 | ユーザー体験 / ブラウザ復帰 |
| 支払い証明？ | 検証後、Query Order | いいえ |
notifyUrlはサーバー間通信、callbackUrlはブラウザリダイレクトです。通信方向が逆です。
まず受取アドレス5件でアカウントを作成します。
少額注文を作成して支払い、Claim、Withdrawまで実行します。
Demo ShopとAPI統合フローを使用します。
検証後に受取アドレスプールを増やします。
本番URL、IP制限、監視、運用責任者を設定します。
加盟店ウォレットをローカルで初期化し、1つのチェーン上の1加盟店アカウントに必要な決済インフラを作成します。
WindowsまたはmacOSでクライアントを実行します。加盟店側の秘密鍵操作はこのクライアント内で行われます。加盟店ウォレットの秘密鍵とMPC Clientパスワードは加盟店端末内に保持してください。
Windows、macOS Intel、macOS Apple Silicon向けの現行V4 MPC Clientを使用します。アカウント運用時はクライアントとローカルのkeys.dbワークスペースをセットで管理してください。
ウォレットをインポートすると、以下を含むローカルMPCワークスペースが作成されます。 keys.dbセットアップを完了する前にバックアップしてください。
1チェーン + 1加盟店ウォレット = 1つの独立したHashNutアカウントです。
Withdraw後、加盟店持分はこのアドレスへ送金されます。
キャパシティを拡張する前に、小規模な受取アドレスプールで検証します。
notifyUrlとcallbackUrlは後から変更できるため、テスト中は一時的な開発用URLを使用できます。
セットアップにより、Split Wallet、MPCインフラ、受取アドレス、API認証情報が作成されます。
| 保存 | 理由 |
|---|---|
keys.db | クライアントが使用するローカルMPC鍵情報。安全にバックアップしてください。 |
| 加盟店ウォレットの秘密鍵 | keys.dbとは別に必要です。分けて保管してください。 |
| Account Infoエクスポート | 作成したアカウントとインフラの運用記録。 |
accessKeyId | 加盟店レベルのAPIリクエストで使用する公開識別子。 |
secretKey | サーバー側HMAC署名用シークレット。生成時に安全に取得し、保管してください。 |
開発者に必要なのはAPI認証情報とアカウント識別子です。加盟店ウォレットの秘密鍵操作は、Account Ownerまたは加盟店側MPC Clientで行います。
本番運用の前に、アカウント、決済検知、精算フロー、API Keyがすべてエンドツーエンドで正常に機能することを確認します。
デプロイ済みのアカウント構成と設定済みの精算情報を確認します。
DashboardまたはDemo Shopを使い、少額の支払いを完了します。
支払い済み受取アドレスの残高をSplit Walletへ集約します。
加盟店持分を設定済みの出金アドレスへ移します。
Demo Shopとサーバー統合を使い、注文作成、照会、通知を確認します。
決済検知、Claim、Withdrawは別々のステージです。少額で実際に検証しながら、この順序で確認してください。
実際の運用資金を扱う前に、One-Key Setupで作成されたインフラを確認します。
Split Wallet、ネットワーク、出金アドレス、受取アドレスプール、API Keyの記録を、セットアップ時に保存したAccount Infoと照合します。
初回検証では、想定した小規模プールが存在し、正しい加盟店アカウントとチェーンに紐づいていることを確認します。
設定済みの出金アドレスは、加盟店がWithdrawを実行した際の送金先です。アカウント操作に使うウォレットを変更しても、設定済みの出金先は自動では変わりません。
出金アドレスは本番運用上の重要設定として扱ってください。最初のエンドツーエンドテスト前と、本番移行前の両方で確認します。
少額の決済注文を作成し、顧客の支払いを完了して、HashNutが正しく検知することを確認します。
テスト金額は少額にしてください。目的は取引金額ではなく、フロー全体の検証です。
支払い案内を開き、指定された資産を割り当て済み受取アドレスへ送金します。取引が検知・確認され、注文ステータスが進むまで待ちます。
0xA4...19CDashboardとQuery Orderで正式なステータスを確認します。ブラウザリダイレクトを支払い証明として使用しないでください。
承認済みの受取アドレス残高をSplit Walletへ集約します。Claimは加盟店が実行します。
支払い済み受取アドレスに想定したトークン残高があり、回収に必要なトークン承認が済んでいることを確認します。
Claimでは加盟店持分を最終出金アドレスへ送りません。承認済み残高を受取アドレスからSplit Walletへ移す操作です。次のステップがWithdrawです。
Split Walletから加盟店の利用可能な持分を、設定済みの出金アドレスへ移します。
取引を開始する前に、設定済みの出金アドレスを確認します。
送金先ウォレットが想定した加盟店持分を受け取ったことを確認します。これで顧客の支払いから加盟店の精算まで、主要な資金フローを検証できました。
API認証情報とDemo Shopを使い、注文作成、注文照会、通知処理が正しく接続されていることを確認します。
Demo Shopは加盟店セットアップとアプリケーション統合をつなぐ実践的なテスト環境です。API Keyを使って決済フロー全体を確認してください。
保管 accessKeyId と secretKey をサーバー側設定に保管します。 secretKey をフロントエンドコードに公開してはいけません。
Create Orderが成功するだけでは不十分です。Query Orderが動作し、通知署名が検証され、アプリケーションがHashNutへ正式なステータスを照会し、履行処理が冪等になっていることを確認します。
初期アカウントと統合を検証した後に、決済の同時処理能力を増やしてください。
受取アドレスは未完了の決済注文に一時的に割り当てられます。そのため、プール数が加盟店アカウントで同時に開ける決済注文数の上限になります。
現在の公開ガイダンスでは、検証時は受取アドレス5件から始め、フロー確認後にプールを増やすことを推奨しています。本番では決済頻度に応じて50、100、200など実用的な単位で設定します。
同じSplit Walletと加盟店アカウントに対して、MPC Clientの受取アドレス作成フローを使用します。選択したチェーンで必要なアドレス管理操作に備え、十分なネイティブGasを用意してください。
検証済みテストフローから、本番設定、監視、キャパシティ、運用責任体制へ移行します。
本番稼働後は、セットアップではなく監視が中心になります。未完了注文、決済例外、Claim、Withdraw、受取アドレス容量、ネイティブGas、エスカレーションを継続的に確認します。
統合テスト中に、サーバー通知とブラウザ復帰を混同せず、ローカルの通知ハンドラを外部から到達可能にします。
notifyUrl はサーバー間通信用エンドポイントです。通知対象の注文ステータスが発生した際、HashNutからインターネット経由で到達できる必要があります。
ルートが待受状態で、受信リクエストを安全にログへ記録できることを確認します。
開発用トンネルまたはリバースプロキシサービスを使い、一時的な公開HTTPSアドレスを作成します。
例：トンネルドメイン + 通知パス。
支払いを行い、サーバーが想定した通知を受信することを確認します。
通知検証後、Query Orderで正式な現在ステータスを取得します。
一時的なトンネルは、安定した本番HTTPSエンドポイントへ置き換えます。 notifyUrl とは分けてください。 callbackUrlnotifyはHashNut → サーバー、callbackは顧客ブラウザ → フロントエンドです。
ブラウザ復帰は顧客体験の一部であり、支払い証明ではありません。
自社プロダクトに同じ顧客・サーバーフローを組み込む前に、決済フローを一通り実行してください。
Demo Shopで顧客の決済フローを確認しながら、加盟店アカウントとAPIの動作を検証します。
demo.hashnut.ioを開く ↗58ドルの商品購入を順番に進め、顧客体験とHashNutの決済処理がそれぞれどの部分を担当するか確認します。
顧客は通常どおり商品を選びます。支払い開始まではHashNutを表示する必要はありません。
検証対象の加盟店アカウント / API Keyを使用します。
金額、資産、ネットワーク、受取アドレスが正しいことを確認します。
顧客ウォレットから指定資産を送金します。
検知と確認の進行を確認します。callbackUrlだけを根拠に履行しないでください。
加盟店サーバーがHashNut注文を取得し、SUCCESS / FINISHを正しく解釈できることを確認します。
アカウント全体の検証に含める場合は、加盟店側からClaimとWithdrawを実行します。
顧客体験は自社ブランドで加盟店プロダクトへ組み込めますが、注文作成、通知検証、正式ステータス照会、1回限りの履行は引き続きサーバー側の責任です。
アカウントと資金フローを検証した後、加盟店サーバーをHashNutへ接続します。
加盟店サーバーは商取引注文とHashNut APIを処理します。顧客資金は顧客ウォレットから割り当てられたオンチェーン受取アドレスへ直接移動します。
加盟店アカウントと資金フローは事前に検証済みである必要があります。開発者へ渡すのはサーバー設定であり、加盟店ウォレットやMPCのシークレットではありません。
BSC0x91...2AFaccessKeyId
secretKey
notifyUrl
callbackUrl
セットアップ時に作成したアカウント識別子とAPI認証情報を使用します。加盟店ウォレットの秘密鍵は受け取らないでください。
accessKeyId と secretKey をサーバー側のシークレットストレージに保管します。
HMAC-SHA256を secretKey で計算し、UUID + timestamp + request bodyを入力として、結果をBase64エンコードします。
自社の加盟店注文を返された payOrderId と accessSign。
金額、資産、ネットワーク、割り当て済み受取アドレスを表示します。
通知を検証し、Query Orderで正式な現在ステータスを取得します。
検証済みのSUCCESS / FINISHになってから履行し、処理は冪等にしてください。
go get github.com/nuttybounty/hashnut-sdk-go/v4callbackUrlはブラウザ復帰の仕組みであり、支払い証明ではありません。決済の正しい状態は、検証済みのサーバー通知と正式なQuery Order結果から判断します。
テストと本番を分け、認証情報、アカウントコンテキスト、URLを使用中の環境に揃えてください。
本番でまとまった決済量を扱う前に、Sandbox / テスト環境で注文作成、決済ステータス処理、資金フロー全体を検証します。
統合作業、少額の検証注文、エンドツーエンドテストに使用します。
加盟店アカウント、callback、受取アドレス容量、運用プロセスを検証した後にのみ使用します。
現行V4アカウントまたはSDKリリースで提供されるBase URLと環境値を使用します。V3エンドポイントURLはV4統合と互換性がありません。
APIリクエストが成功するだけでは不十分です。本番前にCreate Order → 顧客支払い → 通知 → Query Order → Claim → Withdrawまで確認し、さらに受取アドレス容量とGas管理責任を検証します。
加盟店レベルのAPIリクエストはサーバー側で署名し、secretKeyをフロントエンドコードやクライアントバンドルに含めないでください。
| 認証情報 | 用途 |
|---|---|
accessKeyId | 加盟店レベルのリクエストで使用する公開識別子。 |
secretKey | 加盟店サーバー内で使用するHMAC鍵。シークレットそのものを送信しないでください。 |
accessSign | 注文作成時に返される注文固有の認証情報。記載された注文レベル操作で使用します。 |
sign = Base64(
HMAC-SHA256(secretKey, uuid + timestamp + requestBody)
)const crypto = require('node:crypto');
function signRequest(secretKey, uuid, timestamp, requestBody) {
const input = uuid + timestamp + requestBody;
return crypto
.createHmac('sha256', secretKey)
.update(input)
.digest('base64');
}この例はドキュメント記載の署名式を実装しています。リクエストヘッダー名とエンドポイント形式は、現行V4 APIリファレンスに合わせてください。
bindIp は、API Keyを利用できるサーバーIPアドレスを制御します。 * は制限なしを意味します。統合中には便利ですが、本番では可能な限り実際のサーバーIPへ絞り込んでください。
自社の加盟店注文に対応するHashNut決済注文を作成し、返された識別子を業務レコードとともに永続化します。
merchantOrderId = A1042payOrderId + accessSign| フィールド | 意味 |
|---|---|
merchantOrderId | 自社注文の識別子。対象の加盟店 / チェーン / チャネル内で一意にしてください。 |
merchantChannel | 1つの加盟店コンテキスト内でのグループ化。ドキュメント上のデフォルト値： default。 |
expireDuration | 注文の有効期間（秒）。ドキュメント上のデフォルト： 172800 （48時間）、最大： 259200 （72時間）。 |
payOrderId | 作成後に返されるHashNut全体で一意の決済注文識別子。 |
accessSign | 決済注文とともに返される注文固有の認証情報。 |
保管 payOrderId と accessSign を加盟店注文と同時に保存します。注文レベルの操作や、通知遅延・重複時の復旧に必要です。
Query Orderを、現在のHashNut決済注文ステータスを確認する正式な手段として扱います。
ドキュメント記載の注文レベル操作では payOrderId + accessSign を使用し、照会のたびに加盟店HMACを再計算しません。
最も重要なステータスは SUCCESS(3) です。後続の照会で FINISH(4) が返る場合もありますが、引き続き支払い済み状態です。正式な照会結果が安全な支払い済み状態に達した時点で1回だけ履行します。
Confirm Paymentはサーバー側の注文ライフサイクル内で扱い、履行前に現在の注文ステータスを確認します。
Confirm PaymentはV4 APIの注文レベル操作です。決済注文ライフサイクルの一部として扱い、顧客履行の正情報源にはしないでください。
Create Orderでは注文に紐づく accessSign が返されます。注文レベル操作では、加盟店の secretKey をブラウザへ公開せず、返された注文識別子と注文認証情報を使用します。
確認関連の操作後も、現在ステータスの正式な確認手段はQuery Orderです。照会した注文が SUCCESS (3) または FINISH (4)。
V4統合でConfirm Paymentが必要な場合は加盟店サーバー側で実行します。ブラウザ復帰URL、ボタンクリック、取引ハッシュが存在することだけを履行証明にしないでください。
現行V4 API仕様で提供されるエンドポイントパスとリクエストフィールドを使用します。V4実装に旧HashNut APIバージョンを混在させないでください。
現在のステータスでキャンセル可能な未払い注文のみキャンセルし、その終端ステータスを自社システムへ保存します。
ドキュメント上のライフサイクルでは、加盟店がキャンセルすると注文は INIT (0) to CANCELED (-3) へ遷移できます。 CANCELED は終端ステータスです。
自社の merchantOrderId、HashNutの payOrderId、返された注文認証情報をセットで管理します。
チェックアウト画面が開いたままでも、顧客が未払いとは限りません。
ドキュメント上の遷移はINITからCANCELEDです。
自社の業務フローではCANCELEDを終端として扱います。
顧客が引き続き支払う必要がある場合は、終端状態のCANCELED注文を復活させず、新しい決済注文を作成します。
現行V4 API仕様で提供されるエンドポイントパス、リクエストフィールド、認証方式を使用します。
チェックアウト、通知処理、履行、照合、運用で決済注文ステータスを一貫して解釈します。
| 値 | 名称 | 意味 |
|---|---|---|
0 | INIT | 注文作成済み。顧客の支払い待ち。 |
1 | PAID | オンチェーンで支払い取引を検知。確認待ち。 |
2 | CONFIRMING | 必要なブロック確認数を待機中。 |
3 | SUCCESS | 支払い確認済み。初めて安全に履行できる状態。 |
4 | FINISH | 支払い後処理完了。引き続き支払い済み状態。 |
-1 | FAILED | 支払い検証に失敗。 |
-2 | EXPIRED | 支払い完了前に注文が期限切れ。 |
-3 | CANCELED | 加盟店が注文をキャンセル。 |
支払い不足の場合、残額に対する追加支払いレコードが作成されることがあります。部分的な追加入金が繰り返されると、累計支払額が注文総額に達するまで複数の追加レコードが生成されます。
決済ステータス変更をサーバー間で受信・検証し、履行前に正式な注文ステータスを照会します。
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 加盟店サーバー | 顧客ブラウザ → 加盟店フロントエンド |
| 到達性 | HashNutから到達可能であること | 開発中はlocalhostでも可 |
| 用途 | 決済ステータスのシグナル | 顧客を加盟店画面へ戻す |
| 支払い証明 | 検証後、Query Order | 証明として使用しない |
notifyUrlでサーバー間通知を受信します。
記載された署名アルゴリズムでHashNut署名を検証します。
HashNut / 加盟店識別子から加盟店注文を特定します。
Query Orderで正式な現在ステータスを取得します。
検証済みの安全な支払い済み状態でのみ履行し、処理は冪等にします。
現行V4通知仕様で要求されるレスポンスを返します。
現行のローカル参考資料では、以下の通知が記載されています： PAID, SUCCESS, FAILED, and EXPIRED。すべてのステータス遷移で通知が発生するとは限りません。
通知遅延、イベント重複、部分支払い、期限切れ、一時的なAPI障害が、二重履行や注文喪失につながらないよう統合を設計します。
| 状況 | 対応 |
|---|---|
| 通知の重複 | 通知処理と履行を冪等にします。 |
| 通知の欠落 / 遅延 | Query Orderで照会： payOrderId + accessSign。 |
| 通知より先にブラウザが復帰 | callbackUrlを信用せず、サーバー側の注文ステータスを照会します。 |
| 支払い不足 | 設定済みポリシーに従って追加支払いレコード / 残額を処理します。 |
| 期限切れ注文 | 新しい注文を作成します。期限切れ注文を再開しないでください。 |
| 一時的なAPI障害 | 上限付きバックオフで再試行し、楽観的に履行せず加盟店注文を保留にします。 |
merchantOrderId、payOrderId、注文ステータス、通知受信時刻、Query Order結果、履行結果をログに記録します。以下は記録しないでください： secretKey または加盟店の秘密鍵。
本番トラフィックが加盟店アカウントに入る前に、アプリケーションフローと資金フローを一緒に検証します。
加盟店サーバーがHashNut決済注文を作成し、返された識別子を保存します。
顧客に金額、資産、ネットワーク、受取アドレスを表示します。
顧客が取引を完了します。
加盟店サーバーがメッセージを検証します。
サーバーがSUCCESS / FINISHを確認します。
加盟店アプリケーションが商品またはサービスを1回だけ提供します。
想定した支払い済み残高を確認します。
承認済み残高をSplit Walletへ移します。
加盟店持分を設定済みの出金アドレスへ移します。
加盟店注文、オンチェーン支払い、HashNut注文ステータス、精算記録が一致していることを確認します。
遅延・重複イベントからの復旧動作を含め、アプリケーションフローと資金フローの両方をエンドツーエンドで検証できた場合のみ本番へ移行します。
ローンチ後は、注文ステータス、精算、キャパシティ、ネイティブGas、例外を監視し、決済処理を安定稼働させます。
運用担当はアプリケーションコードを確認しなくても、決済を安定稼働させるための4つの問いに答えられる状態を目指します。
決済はどのステータスか？
INIT · PAID · CONFIRMING · SUCCESS · FINISH何を回収できる状態か？
受取残高 · Claim · Withdraw未使用の受取アドレスは残っているか？
未完了注文 · 利用可能アドレス · Gas人の対応が必要なものは？
ステータス不一致 · Gas · キャパシティ · 照合| 領域 | 主担当 |
|---|---|
| 顧客 / 注文ステータスの問題 | 運用担当 + 開発者 |
| Claim / Withdraw | Account Owner / 権限を持つ運用担当 |
| 受取アドレス容量 | 運用 |
| ネイティブGas | 運用担当 / Account Owner |
| API認証 / 通知エラー | 開発者 |
| keys.db / 加盟店ウォレットのバックアップ | アカウント管理者 |
未完了注文と直近の支払い済み注文をステータス別に監視し、外れ値を調査します。加盟店システムとHashNutに不整合が見える場合はQuery Orderを使用します。
| ステータス | 運用上の意味 |
|---|---|
| INIT | 注文は未完了で、顧客の支払い待ちです。 |
| PAID / CONFIRMING | 支払いは検知済みですが、まだ最初の安全な履行状態には達していません。 |
| SUCCESS | 支払い確認済み。正式な検証後、アプリケーションは1回だけ履行できます。 |
| FINISH | 後続の支払い済み状態 / 後処理完了。 |
| FAILED / EXPIRED / CANCELED | 履行ではなく加盟店側での対応が必要な終端例外。 |
merchantOrderId, payOrderId、現在ステータス、支払額、タイムスタンプ、履行状態を加盟店システムで検索可能にしておきます。
ClaimとWithdrawは管理された加盟店側オペレーションとして実行し、各資金移動を想定した受取アドレス残高・Split Wallet残高と照合します。
受取アドレスの承認済みトークン残高をSplit Walletへ集約します。加盟店が実行します。
Split Walletから加盟店の利用可能な持分を設定済みの出金アドレスへ移します。プラットフォーム持分は別途処理されます。
現行クライアントフローで対応している場合、MPC管理の受取アドレスに残ったネイティブGasコインを加盟店ウォレットへ回収します。
小規模チームでは同じ人が複数の役割を兼任する場合がありますが、本番手順では、精算操作を実行できる権限者と、その操作をどのようにレビューするかを明確に記録してください。
未完了注文に十分な受取アドレス容量と、加盟店側のオンチェーン操作に十分なネイティブGasを確保します。
受取アドレスは注文間で再利用されますが、有効な注文に割り当て中のアドレスは別の有効注文には使えません。需要がプールを使い切る前に残り容量を監視してください。
現在の公開ガイダンスでは、初回検証は5アドレスから始め、本番では50、100、200など実用的な単位でプールを設定することを推奨しています。累計取引件数ではなく、同時に開いている注文数に基づいて容量を決めてください。
| チェーン系統 | 加盟店側Gas |
|---|---|
| Ethereum / EVM | 関連するデプロイや加盟店側オンチェーン操作に必要なネイティブネットワークコイン。 |
| BSC | BNB |
| Polygon | POL / 現行ネイティブネットワークコイン |
| TRON | TRX |
運用操作が失敗してからGasを補充するのではなく、ネイティブ残高を運用チェックリストに含めてください。
問題を早期に検知し、決済ステータスの問題と精算の問題を切り分け、適切な担当者が対応できるだけの情報を添えてエスカレーションします。
| 症状 | 想定担当 / 最初の確認 |
|---|---|
| 顧客が支払ったと言っているのに注文がINITのまま | チェーン取引、ネットワーク / 資産、受取アドレスを確認し、その後、開発者 / HashNutの決済検知を確認します。 |
| PAID / CONFIRMINGが異常に長く続く | チェーン確認数とネットワーク状態を確認します。 |
| 通知が来ない | 開発者が注文を直接照会し、notifyUrlの到達性 / ログを確認します。 |
| Claimでトークンを回収できない | トークン承認と受取アドレス残高を確認します。 |
| Withdrawの送金先が想定と異なる | 停止し、再試行前に設定済みの出金アドレスを確認します。 |
| 受取アドレスプールが不足 | 未完了注文でプールを使い切る前に、運用担当が容量を追加します。 |
| MPC Clientで新しいアドレスを作成できない | ローカルクライアント、keys.db、加盟店ウォレット、ネットワーク、Gasを確認します。 |
加盟店アカウント / チェーン、merchantOrderId、payOrderId、現在の注文ステータス、該当する場合はトランザクションハッシュ、タイムスタンプ、実行した操作、正確なエラー内容を含めます。絶対に送ってはいけないもの： secretKey または秘密鍵。
バックエンドがGoの場合はV4 Go SDKを使用します。
go get github.com/nuttybounty/hashnut-sdk-go/v4SDKでリクエスト構築の手間は減らせますが、認証情報の保護、加盟店注文のマッピング、通知検証、正式な注文照会、冪等な履行、運用ログは引き続きサーバー側の責任です。
V4 packageパスとV4 API仕様をセットで使用し、V3エンドポイント例を混在させないでください。
JavaバックエンドではV4 Java SDKを使用し、API認証情報と決済検証はサーバー側で管理します。
現行V4 Java SDKリリースで提供されるpackage座標とコード例を使用します。
1つのチェーン上の1加盟店ウォレットに対して作成される構成要素と、決済、精算、APIアクセスとの関係を理解します。
各チェーンには独立した加盟店アカウント、Split Wallet、API Key、受取アドレスプールがあります。1つのチェーンでのセットアップが、別のチェーンを自動的に作成・管理するとは考えないでください。
アカウント運用を継続するために必要な加盟店側資産をバックアップし、サーバー認証情報とウォレットのシークレットを分けて管理します。
ローカルMPC情報とアカウント情報は用途が異なります。両方を保管しつつ、ウォレットのシークレットとアプリケーション認証情報は分離してください。
keys.db加盟店側クライアントが使用するローカルMPC鍵情報。
加盟店アカウントの理解・統合に必要な設定と識別子。
0x91...2AF0x72...891AKID••••91••••••••••••| 資産 | ルール |
|---|---|
keys.db | 安全にバックアップしてください。MPC管理アドレス操作を継続するため、ローカルMPC Clientワークスペースで必要です。 |
| 加盟店ウォレットの秘密鍵 | keys.dbとは分けてバックアップし、開発者へ渡さないでください。 |
| Account Info | エクスポートしたアカウント記録を加盟店の運用ドキュメントと一緒に保管します。 |
accessKeyId | サーバー設定に保管します。 |
secretKey | サーバー側シークレットストレージに保管し、生成時に安全に取得してください。 |
Account Ownerは加盟店ウォレット情報とローカルMPC資産を保護し、開発者はアプリケーションAPIシークレットを保護します。小規模チームでは同じ人が担当する場合でも、シークレットは分けて保管・取り扱ってください。
加盟店の決済動作とアプリケーションルーティングを、明示的・編集可能・本番運用に安全な状態で管理します。
| 設定 | 意味 |
|---|---|
notifyUrl | HashNutの決済ステータス通知を受信する公開サーバーエンドポイント。 |
callbackUrl | 顧客の決済体験後に戻るブラウザURL。ローカル開発ではlocalhostを使用できます。 |
bindIp | API Key用のサーバーIP許可リスト。 * は制限なしを意味します。 |
| 設定 | ドキュメント記載の動作 |
|---|---|
merchantChannel | デフォルトのチャネル値： default。 |
expireDuration | デフォルト172800秒（48時間）、最大259200秒（72時間）。 |
| 受取アドレス容量 | 検証時は小さく始め、アカウントと統合を確認してから拡張します。 |
本番移行前に、本番URL、IP制限、出金先、キャパシティ、Gas、通知処理、運用責任体制を確認します。設定変更は記録・テストし、まとまった決済量がアカウントに入る前に検証してください。
Buy one demo item with 0.01 USDT. After the payment is confirmed, take over the same order as the merchant and complete the settlement.
Connect your website or app through HashNut’s payment infrastructure.
決済の活用方法、販売・代理店機会、戦略的パートナーシップについてご相談ください。
HashNutのサービスをご利用いただく際の個人データの収集、利用、共有および管理について説明します。
HashNutのウェブサイト、アプリケーション、製品およびサービスへのアクセスと利用に適用される条件です。
HashNutが事業全体で金融犯罪リスクを特定、評価、管理する方法について説明します。