Yokinsoft.SBPaymentService 1.0.1.5-pre-release

SB Payment Service .NET Library [未完成]

SBペイメントサービスの提供する決済サービスへのアクセスをサポートするための .NET ライブラリです。 .NET Framework, .NET Standard 2.0 の2種類のDLLを含みます。次の主な機能を内蔵しています。

• リンク型 HTML form のレンダリングと、結果・返却データの受信
• API型 サーバーとの通信機能
• プログラミング上煩雑になる Hash の計算と照合
• DES暗号の暗号・復号処理。
• パラメーターの検証（一部）

このライブラリは SB Payment Service の公開仕様に基づいて実装されています。 開発者向けの技術情報、仕様は SB Payment Service Developer で公開されています。

※なお本ライブラリの開発者は SBペイメントサービス株式会社 とは直接関係がありません。本ライブラリの内容や仕様に関する SBペイメント社 への問い合わせなどはご遠慮ください。

※現在、支払い要求と取り消しに関する主なメソッド以外は未実装です。設計に賛同いただいて実装にご協力いただける方募集します。

ライセンス

MIT ライセンス

Copyright (c) 2023-2025 Yokinsoft

以下に定める条件に従い、本ソフトウェアおよび関連文書のファイル（以下「ソフトウェア」）の複製を取得するすべての人に対し、ソフトウェアを無制限に扱うことを無償で許可します。これには、ソフトウェアの複製を使用、複写、変更、結合、掲載、頒布、サブライセンス、および/または販売する権利、およびソフトウェアを提供する相手に同じことを許可する権利も無制限に含まれます。

上記の著作権表示および本許諾表示を、ソフトウェアのすべての複製または重要な部分に記載するものとします。

ソフトウェアは「現状のまま」で、明示であるか暗黙であるかを問わず、何らの保証もなく提供されます。ここでいう保証とは、商品性、特定の目的への適合性、および権利非侵害についての保証も含みますが、それに限定されるものではありません。 作者または著作権者は、契約行為、不法行為、またはそれ以外であろうと、ソフトウェアに起因または関連し、あるいはソフトウェアの使用またはその他の扱いによって生じる一切の請求、損害、その他の義務について何らの責任も負わないものとします。

動作環境

.NET Framework 4.8 で動作を確認しています。(.NET Core では未検証 )

開発しているプロジェクトで SBPaymentService.dll を参照してください。

簡単な使用例

リンク型 方式でクレジット決済へ誘導する HTML FORM を出力するコード

次の例は試験環境の条件で、 C# cshtml Razor で記述した場合です。

@using SBPaymentService
@{
    var env = MerchantEnvironment.LinkTrialEnvironment;
    var formData = new PaymentRequestData
    {
        cust_code = "abc_cus_code",
        order_id = "ORDER123",
        item_id = "item_id",
        amount = "1234",
        pay_type = "0",
        service_type = "0",
        success_url =  new Uri(Request.Url, Request.RawUrl).ToString(),
        cancel_url = new Uri(Request.Url, Request.RawUrl).ToString(),
        error_url = new Uri(Request.Url, Request.RawUrl).ToString(),
        pagecon_url = new Uri(Request.Url, Request.RawUrl).ToString(),
        request_date = FormData.FormatDateTime( DateTime.Now ),
        item_name = "お買い物の支払い"
    };
}
<form action="@env.RequestPaymentUrl" method="post" accept-charset="shift_jis">
    @formData.RenderForm(env)
    <button type="submit" class="btn btn-primary btn-md">支払いに進む</button>
</form>

環境設定

API型、リンク型で共通して使われる契約に基づく接続情報を MerchantEnvironment で保持します。 MerchantEnvironment クラスは各プロパティを独自に設定するか、派生クラスである NameValueMerchantEnvironment を使って config ファイルの appSettings セクションから 読み込むこともできます。NameValueMerchantEnvironment のコンストラクタは NameValueCollection を引数に取るため、任意の方法（個別に定義したXMLファイルなど）から 取得し NameValueCollection に格納し直したものを使うこともできます。引数を省略した場合は System.Web.Configuration.WebConfigurationManager.AppSettings から設定が取得されます。name value の規則は次のようになります。

    
    <add key="SBP:MerchantID" value="12345" />
    <add key="SBP:ServiceID" value="000" />
    <add key="SBP:APIUrl" value="https://api.example.com/xxxx" />
    <add key="SBP:APIHashKey" value="[HASHKEY]" />
    <add key="SBP:TripleDESKey" value="[DESKEY]" />
    <add key="SBP:TripleDESInitKey" value="[KESINITKEY]" />
    <add key="SBP:TripleDESPadding" value="NoPadding" />
    <add key="SBP:BasicAuthID" value="xxxx" />
    <add key="SBP:BasicAuthPassword" value="xxxx" />
    <add key="SBP:APIRemoteAddress" value="123.123.123.13" />
    <add key="SBP:PartnerMngNo" value="ABCDEFG" />
    <add key="SBP:RequestPaymentUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:RequestAccountRegistrationUrl" value="https://xxxx/xxxxx/xxxx" />
    <add key="SBP:RequestAccountUnregistrationUrl" value="https://xxxx/xxxx/xxxxx" />
    <add key="SBP:RequestSubscribeUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:HashKey" value="[HASHKEY]" />
    <add key="SBP:RemoteAddress" value="123.123.123.123" />
    <add key="SBP:Test" value="true" />
    
    <add key="SBP:Test:MerchantID" value="12345" />
    <add key="SBP:Test:ServiceID" value="000" />
    <add key="SBP:Test:RequestPaymentUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:Test:RequestAccountRegistrationUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:Test:RequestAccountUnregistrationUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:Test:RequestSubscribeUrl" value="https://xxxx/xxxx/xxxx" />
    <add key="SBP:Test:HashKey" value="[HASHKEY]" />
    <add key="SBP:Test:RemoteAddress" value="123.123.123.123" />
    <add key="SBP:Test:APIUrl" value="https://api.example.com/xxxx" />
    <add key="SBP:Test:APIHashKey" value="[HASHKEY]" />
    <add key="SBP:Test:TripleDESKey" value="[KEY]" />
    <add key="SBP:Test:TripleDESInitKey" value="[KEY]" />
    <add key="SBP:Test:TripleDESPadding" value="NoPadding" />
    <add key="SBP:Test:BasicAuthID" value="xxxxx" />
    <add key="SBP:Test:BasicAuthPassword" value="xxxx" />
    <add key="SBP:Test:APIRemoteAddress" value="123.123.123.123" />

<add name="SBP:Test" value="true" /> を true に設定するとテスト環境を使用し、 false に設定すると本番環境の設定を使用します。

使い方

API型 で決済要求

注意: 現在API型のメソッドの多くは未実装か未検証

SBPaymentService.Api.Method 名前空間に支払い方法ごとのクラスが定義されています。 MerchantEnvironment と 名前空間に定義された支払メソッドごとのクラスを使ってAPIにアクセスします。

簡単な例

  using SBPaymentService;
  using SBPaymentService.Api.Method

  var credit = new Credit( new NameValueMerchantEnvironment() );
  var res1 = credit.RequestPayment("customer-a", "order-1", "item-1", 1000);
  var res2 = credit.ConfirmPayment( sps_transaction_id: res1.res_sps_transaction_id, tracking_id: res1.res_tracking_id );

リンク型

• 購入要求の条件設定と、HTML form の出力
• 「購入結果CGI」「確定通知」
• 「結果（画面返却）」

購入要求

PaymentRequestData クラスに条件を設定し RenderForm メソッドを呼び出します。

  using SBPaymentService;
  var env = new MerchantEnvironment();
  var formData = new PaymentRequestData {
        ...
        amount = "1000",
        ...
        success_url = ....,
        cancel_url = ....,
        error_url = ....,
        pagecon_url = ....,
        request_date = FormData.FormatDateTime(DateTime.Now)
  }

ASP.NET Razor によるHTMLは次のようになります。データは <input type=hidden ...> 形式でページ上では見えないように出力されます。

  <form action="@env.RequestPaymentUrl" method="post" accept-charset="Shift_JIS">
      @formData.RenderForm(env)
      <button class="btn btn-success form-control" type="submit">ソフトバンクペイメントのお手続きへ案内いたします。</button>
  </form>

コンビニ決済など一部の決済に引き渡す顧客情報を設定する free_csv という項目は、エンコード処理がサポートされます。

formData.FreeCsv = new string[]{"webcvs","payeasy", "banktransfer"}.Contains(pay_method) ? 
    new OfflinePaymentFreeCsv {
        LAST_NAME = "山田",
        FIRST_NAME = "花子",
        LAST_NAME_KANA = "ヤマダ",
        FIRST_NAME_KANA = "ハナコ",
        TEL = new string( "090-1234-1234".Where( c => "0123456789".Contains(c)).ToArray()),
        MAIL = "test@example.com",
    };

※設定できる文字種に制限があり不正な文字が含まれている項目は空文字列で再設定され出力されます。

RenderHTML RenderForm メソッドは次の場合例外が発生します。

• HTMLレンダリング前の内部的なパラメーターチェックで不合格の場合

結果CGI「購入結果CGI」

購入要求の pagecon_url で設定したURLでの処理になります。

    var data = FormData.ParseFormData<PaymentRequestResultData>(Request, environment);

    ...
    Response.Write("OK");

ParseFormData では次の照合に失敗した場合に例外が発生します。それ以外、メッセージの内容がOK　NGにかかわらず受信したデータを返します。

• ハッシュ値の照合
• merchant_id の照合
• service_id の照合

結果（画面返却）

購入要求の結果、利用者のブラウザ上で戻ってきたページでの処理になります。

    var data = FormData.ParseFormData<PaymentRequestReturnData>(Request, environment);

リンク型に関するその他の注意

本ライブラリでは

• 結果CGI
• 画面返却

に関して便宜上

• Result
• Return

の用語で区別しています。それぞれのデータを受信する際のクラス名は

• PaymentRequestResultData
• PaymentRequestReturnData

となります。

文字エンコーディングに関する注意

SBペイメントのリンク型では、 Formデータの POST は Shift_JIS であること、また、結果CGIと画面返却時でハッシュ計算に関する文字コードが UTF-8, Shift_JISの違いがあります。 ハッシュ計算に関する文字コードの違いの扱いは本ライブラリ内で吸収されていますが、FORMデータ受信（SBペイメント側、あるいはユーザーのブラウザから）POSTされたデータのエンコーディングは Webサーバーの設定が必要です。IIS ASP.NET の場合 web.config を使った場合は次のようになります。

  <system.web>
	<globalization requestEncoding="Shift_JIS"/>
  </system.web>

リンク型、実際の実装時の工夫

RenderForm でHTML form を出力してから、支払い要求へPOSTするまで時間の開きがある場合、例えば、ユーザーのボタン押下アクションを待つような場合、 SBペイメントのサーバーは request_date からある時間の経過後タイムアウトエラーになるようです。 開発時には、これを回避するためのトリックが必要になるかもしれません。

改定歴

• 2025-05-23 内部設計の見直し。ネストされたプロパティを含めたハッシュ計算、暗号化、復号化バグ修正。
• 2025-04-22 改定
• 2025-03-13 楽天ペイ（オンライン決済）V2 を追加
• 2023-03-17 PayPay（オンライン決済）を追加

© Yokinsoft 2023-2025 https://www.yo-ki.com