加盟店API概要

概要

HissPay は入金（お客様からの回収）と出金（受取口座への支払い）のAPIを、HTTPS POST + JSON で提供します。本番ゲートウェイ：https://transaction.hisspay.com、サンドボックス：https://sandbox-api.hisspay.com。

商品カタログの通貨：AUD, EUR, GBP, INR, JPY, THB, USD, USDT。カタログに掲載されていても利用可能とは限りません。お客様の商品コード、金額範囲、手数料は開通通知に記載されます。

導入準備

連携前の確認事項：加盟店が審査済みで有効であること、加盟店管理画面（mch.hisspay.com →アプリキー）でAPIアプリを作成し appId と appSecret を取得済みであること、入金・出金商品を契約済みであること、出金用にサーバーの公開送信元IPをホワイトリスト登録済みであること、公開HTTPSの通知URLがあること。まずサンドボックスで一通り検証してください。

署名ルール

すべてのリクエストに appId、timestamp（ミリ秒のUnix時刻、プラットフォームとの差30秒以内）、nonce（10文字以上、再利用不可）、sign ヘッダーを付けます。sign は、ボディの各フィールドと appId・timestamp・nonce を名前順に key=value で並べて & で連結し、末尾に appSecret を直接付けた文字列の SHA-256（小文字16進）です。HMACではありません。null は送らず、appSecret をブラウザやアプリに置かないでください。

入金注文作成

POST /transaction/payin/v1/apply で入金注文を作成し、支払者向けの payUrl を受け取ります。支払い確認は署名検証済みの通知または照会のみで行い、ブラウザの戻り先では判断しないでください。

出金注文作成

POST /transaction/payout/v1/apply は非同期処理です。code=0 は受付済みであり、支払完了ではありません。タイムアウトや 500 は結果未確定を意味します。まず元の注文を照会し、完全版ドキュメントの対応ルールに従ってから再送の可否を判断してください。

USDT 入金

USDT入金は currency=USDT とプラットフォームが割り当てるネットワーク別の商品コードを使用し、金額は小数点以下4桁までです。結果は通知または照会で確認します。

タイ（THB）

タイ（THB）：PromptPay QR 入金とタイの銀行振込による出金。入金の銀行コード：SCB, KBANK, KTB, BAY, GSB, TTB、出金：SCB, KBANK, KTB, BAY, GSB, TTB, BBL（ご利用可能な銀行は開通通知に記載）。1件あたりの既定範囲：500.00–49999.00 THB。

注文照会

POST /transaction/payin/v1/query と POST /transaction/payout/v1/query は merchantOrderNo または orderNo で照会します。appId ごとに毎秒5回までです。3〜5秒間隔でバックオフしながら照会してください。

残高照会

POST /transaction/payout/v1/balance は通貨ごとの balance（帳簿）、balanceActive（利用可能）、balanceFreeze（凍結）を返します。

非同期通知

プラットフォームは同じ4つの署名ヘッダー付きで notifyUrl に JSON を POST します。署名を検証し、注文単位で冪等に処理してから、正確に SUCCESS または OK を返してください。応答のない通知は限られた回数だけ再送されます。

注文ステータス

payStatus と paymentStatus、isFinal を組み合わせて判断します。入金照会の payStatus=0 は失敗を意味しません。

エラーコード

code=0 はAPI呼び出しの成功を意味し、支払結果は別途注文ステータスで確認します。各エラーコードと推奨対応は完全版ドキュメントを参照してください。

完全サンプル

サンドボックス加盟店を作成し、サンドボックスガイドの quickstart パックと5分間セルフチェックを実行してから、本番移行チェックリストに従ってください。