入金・出金APIを数ステップで導入

概要

India Payme は加盟店様向けに2つの中核的な取引機能を提供しています。入金（Payin）——加盟店に代わってエンドユーザーから代金を受け取る機能、出金（Payout）——加盟店に代わって指定口座へ送金する機能です。すべての外部公開APIは POST + JSON形式で、API署名の付与が必須です。プラットフォーム側での処理が完了すると非同期通知で加盟店へコールバックするほか、能動的な注文照会にも対応しています。

機能	メソッド	パス
入金注文作成	POST	/transaction/payin/v1/apply
入金注文照会	POST	/transaction/payin/v1/query
出金注文作成	POST	/transaction/payout/v1/apply
出金注文照会	POST	/transaction/payout/v1/query
残高照会	POST	/transaction/payout/v1/balance

ベースURL（本番ゲートウェイドメインは口座開設後にプラットフォームより提供される内容をご確認ください）：

導入準備

加盟店管理画面 → アプリケーション鍵にログインすると、各アプリケーションに appKey と appSecret の1組の認証情報が発行されます。appKey はリクエストヘッダーの appId に対応し、appSecret は署名専用の鍵で、ローカルでの署名計算にのみ使用し、送信には含めません。

すべてのリクエストには以下のHTTPヘッダーを付与してください。Content-Type は application/json です。

Header	必須	説明
appId	はい	加盟店アプリケーションID（appKeyと同一）
timestamp	はい	ミリ秒単位のUnixタイムスタンプ
nonce	はい	ランダム文字列。10桁以上、使い切りで再利用不可
sign	はい	次節のルールに従って算出した署名

署名ルール

署名アルゴリズムは純粋なSHA-256（16進数の小文字）であり、HMACではありません。appSecret を署名対象文字列の末尾にそのまま連結してからSHA-256を計算します。手順は以下のとおりです。

1. 「リクエストボディのトップレベルフィールド（値が空でないもののみ）」と「署名ヘッダー appId、timestamp、nonce」をまとめて1つのMapにします（sign 自体は対象に含めません）。
2. パラメータ名をASCII昇順でソートし、key1=value1&key2=value2… の形式で連結します。
3. 末尾に区切り文字なしで appSecret を直接連結し、文字列全体のSHA-256（16進数小文字）を計算した値が sign になります。

有効期限とリプレイ攻撃対策：

• タイムスタンプの有効期限は30秒：|サーバー時刻 − timestamp| ≤ 30秒。これを超えると timestamp has expired が返されます。クライアントとゲートウェイの時刻同期（NTP）を必ず行ってください。
• nonceによるリプレイ防止：同一の nonce は1回しか使用できません。重複すると nonce has been used（エラーコード 900）が返されます。
• 空値のフィールドは署名対象に含まれません——「署名対象フィールドの集合」は「実際に送信するJSONフィールド」と完全に一致させる必要があります。

Node.js での署名サンプル：

入金注文作成 POST

POST /transaction/payin/v1/apply —— 入金注文を1件作成し、決済ページの支払いリンク payUrl を返却します。ユーザーをこのリンクへ誘導することで支払いを完了させます。

フィールド	型	必須	説明
merchantOrderNo	string	はい	加盟店注文番号。重複不可
amount	number	はい	注文金額。小数指定可（例：100.02）
name	string	はい	ユーザー氏名。英字のみ、3文字以上、スペース使用可、記号・数字は不可
phone	string	はい	電話番号
email	string	はい	メールアドレス
currency	string	はい	通貨：INR / PKR / USDT / BDT
product	string	はい	決済プロダクトコード。契約内容に基づきプラットフォームが発行
notifyUrl	string	いいえ	非同期通知先URL。指定しない場合は加盟店のデフォルト通知先を使用
returnUrl	string	いいえ	支払い成功後の遷移先ページ
payType	string	いいえ	ウォレット直接支払い方式：JAZZCASH / EASYPAISA / BKASH / NAGAD

payUrl を取得したらユーザーをそのリンクへ誘導し、決済を行っていただきます。最終的な結果は非同期通知を正としてください。

出金注文作成 POST

POST /transaction/payout/v1/apply —— 指定口座へ送金を実行します。非同期処理：APIはまず口座の検証と資金の凍結を行い、その後非同期でチャネルとのマッチングと出金処理を行います。レスポンスは通常 payStatus=0（受理成功）となり、最終結果は注文照会または通知を正としてください。

フィールド	型	必須	説明
merchantOrderNo	string	はい	加盟店注文番号
amount	number	はい	送金金額。最低100.00
accountName	string	はい	受取人氏名。英字のみ、3文字以上、スペース使用可
account	string	はい	受取口座番号
phone	string	はい	電話番号
email	string	はい	メールアドレス
currency	string	はい	通貨：INR / PKR / USDT / BDT
bizCode	string	はい	出金業務タイプ：IMPS / UPI / BANK / JAZZCASH / EASYPAISA / BKASH / NAGAD / ECARD
payCode	string	はい	支払い方式：CARD / WALLET / NBK / ITT / VC
branchCode	string	はい	清算コード：インドは IFSC、パキスタンは bankcode、バングラデシュは bizCode に応じて入力
product	string	はい	出金プロダクトコード。プラットフォームが発行
bankName	string	いいえ	銀行名
swiftCode	string	いいえ	SWIFTコード（越境送金 ITT 利用時に使用）

注文照会 POST

入金は POST /transaction/payin/v1/query、出金は POST /transaction/payout/v1/query です。merchantOrderNo または orderNo を指定して注文を特定します。レート制限：5回/秒。

残高照会 POST

POST /transaction/payout/v1/balance —— 加盟店口座の残高を照会します。レート制限：5回/秒。

非同期通知

注文が最終ステータスに達すると、プラットフォームは POST（JSON）で加盟店の notifyUrl（未指定の場合はデフォルト通知先）へ通知を送信し、通知にも同様の署名ヘッダー（appId/timestamp/nonce/sign）を付与します。加盟店側では自身の appSecret を用いて同じルールで署名を再計算し、照合することで通知の真正性を検証してください。

入金通知のペイロードには merchantOrderNo、orderNo、currency、product、amount、realAmount、status（入金成功時は "1"）が含まれます。出金通知にはさらに utr（銀行取引番号）と statusDes（ステータス説明）が含まれ、status は "1" が成功、"2" が失敗です。

加盟店側はプレーンテキストで OK または success を返却してください（大文字小文字は区別しません）。返却がない場合、プラットフォームは再試行キューに入ります：最大5回、間隔は分単位で段階的に延長されます（1 / 2 / 5 / 10 / 30 / 60 / 120分）。そのため、加盟店側のAPIはべき等性を担保する必要があります（同一の orderNo に対して複数回通知される可能性があります）。

注文ステータス

加盟店側では以下の公開ステータスを基準にしてください（内部のステートマシンはより詳細ですが、直接は公開していません）。

シナリオ	フィールド	値
注文受理レスポンス	payStatus	0 作成 / 1 成功 / 2 失敗 / 3 キャンセル
入金注文照会	payStatus	0 処理中 / 1 入金済み / -1 キャンセル済み
出金注文照会	payStatus	0 送金待ち / 1 送金済み / -1 キャンセル済み
非同期通知	status	入金成功時は "1"／出金は "1" 成功・"2" 失敗

エラーコード

レスポンスボディの code != 0 は失敗を意味し、msg にメッセージが含まれます。主なビジネスエラーコードは以下のとおりです。

code	説明
0	成功
400	パラメータエラー / 署名検証失敗（Sign invalid）
900	リクエスト重複 / nonceリプレイ
10000 / 10001	アプリケーションが存在しない / アプリケーション利用不可
10002	通貨未対応
10003 / 10007	加盟店利用不可 / 加盟店口座利用不可
10004	プロダクト未開通または契約期限切れ
10005 / 10009	利用可能なチャネルなし / チャネル一時利用不可
10008	口座残高不足
10010	IPがホワイトリストに未登録
10011 / 10012	プロダクト無効 / 支払い方式無効
10020	加盟店注文番号の重複
30001 / 30002	注文番号エラー / 通貨エラーまたは口座未有効化

完全な連携フロー

入金を例に説明します。

1. ビジネスリクエストボディを組み立てます（「入金注文作成」のフィールドを参照）。
2. timestamp（ミリ秒）と nonce（10桁以上のランダム文字列）を生成します。
3. 「署名ルール」に従って sign を計算します。
4. 4つの署名ヘッダーとJSON Bodyを付与して POST /transaction/payin/v1/apply を実行します。
5. code==0 の場合は data.payUrl を取得し、ユーザーを支払いへ誘導します。
6. 非同期通知を待ち受けつつ、能動的な注文照会で最終ステータスを確認することもできます。
7. 通知を受信したら署名を検証し、ビジネス処理を行った上でプレーンテキストの OK を返却します。

注：本ドキュメントに記載のAPIパス、フィールド、ステータスコードはすべて本番実装に対応しています。本番ゲートウェイドメイン、利用可能な product プロダクトコード、IPホワイトリストポリシーなどは、口座開設後にプラットフォームより提供される内容をご確認ください。