nodexpay

Nodex Pay API の非公式 Ruby クライアント SDK です。支払いの作成・取消と、Payment Result callback の署名検証を提供します。Ruby 3.4 以上に対応し、runtime dependency はありません。

[!IMPORTANT] この gem は Nodex Pay または Nodex Global Limited が提供・承認する公式 SDK ではありません。実運用前に Nodex Pay API ドキュメントと Testnet で挙動を確認してください。

インストール

Gemfile に追加します。

gem "nodexpay"

または直接インストールします。

gem install nodexpay

クライアント

Production と Testnet の取り違えを防ぐため、environment に既定値はありません。

require "nodex_pay"

client = NodexPay::Client.new(
  identification_token: ENV.fetch("NODEX_PAY_IDENTIFICATION_TOKEN"),
  hash_token: ENV.fetch("NODEX_PAY_HASH_TOKEN"),
  environment: :testnet
)

必要に応じて open_timeout、read_timeout、write_timeout を秒単位で指定できます。既定値はそれぞれ5秒、30秒、30秒です。

支払いを作成する

payment = client.create_payment(
  order_code: "order-123",
  amount: "100.00",
  amount_type: "JPY",
  color_theme: :light,
  deadline: Time.now + 3600,
  description: "Order #123"
)

payment.url
payment.token

amount には String、Integer、または利用アプリケーションが bigdecimal を導入済みの場合は BigDecimal を指定できます。署名精度を曖昧にしないため Float は受け付けません。amount を省略すると、支払者が金額を決める支払いを作成します。

order_code は Payment Request ごとに一意な ASCII 文字列を指定し、アプリケーション側で保存してください。

支払いを取り消す

client.cancel_payment(order_code: "order-123") #=> true

未払いかつ blockchain transaction が関連付けられていない支払いだけを取り消せます。すでに取消済みの場合も例外を返します。

Payment Result を検証する

Web framework が受信した raw JSON body をそのまま渡します。

result = client.verify_payment_result(raw_request_body)

if result.success?
  # order_code、amount、symbol を保存済み注文と照合して状態を更新する
end

署名不一致時は NodexPay::SignatureVerificationError、JSON や field が不正な場合は NodexPay::InvalidResponseError を送出します。

[!WARNING] Nodex Pay の署名対象は order_code と amount だけです。result、symbol、chain/transaction field の完全性や blockchain finality は署名だけでは保証されません。注文との照合、transaction_code の重複排除、必要に応じた on-chain 確認をアプリケーション側で行ってください。

エラー処理

begin
  client.create_payment(order_code: "order-123", amount: "100")
rescue NodexPay::BadRequestError => error
  warn "status=#{error.status} codes=#{error.error_codes.inspect}"
rescue NodexPay::TimeoutError, NodexPay::TransportError => error
  # 自動 retry はせず、結果不明として業務上の確認を行う
end

POST の自動 retry と redirect 追従は行いません。API error の詳細は status、error_codes、response_headers、response_body から確認できます。response body は機密情報として扱い、そのままログへ出力しないでください。

型定義

RBS は sig/nodex_pay.rbs、Sorbet RBI は rbi/nodex_pay.rbi として gem に同梱しています。SDK 本体は sorbet-runtime に依存しません。

標準の srb tc wrapper は、Bundler の依存に含まれる gem の rbi/ を検出するため、追加の require やコピーは不要です。Tapioca で gem RBI を管理する project では、その project の Tapioca 更新フローに従ってください。

RBI は NodexPay::Client、返却モデル、transport value、公開例外を型付けします。custom transport は duck typing のため T.untyped とし、call(Request) -> Response の契約は設計文書で定義しています。

開発時の bundle exec rake sorbet はRBIを typed: strict で検査し、Sorbet metrics上のsignature coverage（sig 数 ÷ 検出method数）が100%でなければ失敗します。CIでも同じtaskを実行するため、型エラーや型定義の追加漏れを許容しません。

開発

bundle install
bundle exec rake
bundle exec rake build

Testnet の資格情報を設定した場合に限り、支払い作成と取消の手動 smoke test を実行できます。

NODEX_PAY_IDENTIFICATION_TOKEN=... \
NODEX_PAY_HASH_TOKEN=... \
bundle exec rake smoke:testnet

この task は実際に Testnet の支払いを1件作成し、直後に取り消します。通信結果不明時の自動 retry は行いません。

設計判断、wire contract、テスト戦略は docs/README.md から参照できます。