リンク型 - 基本仕様 | Developer - SBペイメントサービス

接続方式概要

リンク型を利用した加盟店様のサイトと当社決済画面の連携とその処理を表した概略図となります。

例）購入要求

上記は概要を理解いただくための図（②で必要となる加盟店様と当社サーバー間でのやり取りは図より省略）となります。詳細は「提供機能一覧」と「インターフェース仕様（リンク型購入要求／リンク型顧客決済情報登録要求／リンク型継続課金（定期・従量）申込要求）」を必ずご確認ください。

HTTPフォーマット

基本ルール

リンク型はHTTPS POSTリクエスト／レスポンスを利用した通信を行い、文字コード（キャラクタセット）はShift_JISを使用します。基本的な構造は以下のとおりです。

<form action=”https://stbfep.sps-system.com/xxxx/xxxxxxxx” method="POST">
     <input type="hidden" name="タグエレメント名1" value="設定内容1">
     <input type="hidden" name="タグエレメント名2" value="設定内容2">
     <input type="submit" value="submit">
</form>

                     <form action=”https://stbfep.sps-system.com/xxxx/xxxxxxxx” method="POST">
     <input type="hidden" name="タグエレメント名1" value="設定内容1">
     <input type="hidden" name="タグエレメント名2" value="設定内容2">
     <input type="submit" value="submit">
</form>

... 3 行すべてを表示する

使用可能Portは、「443」となります。
各リクエスト／レスポンスにおいて未設定項目がある場合でもタグエレメントの削除は不可です。未設定項目については空文字の設定をお願いします。ただし、明細行繰返項目のみ、タグエレメントの削除が可能です。
当社から加盟店へ送信するリクエストは、インターフェース項目定義の連番通りには返却されず、順不同での返却となります。当社からのリクエスト情報を取得する場合は、タグエレメント指定で情報の取得をお願いします。
画面連携がある場合はsubmit属性の記述が必要です。
FORMタグのaction属性に指定する接続先は、環境構築完了後に当社より連絡します。

サンプルコード

各機能のサンプルコードは、リンク型システム仕様書（サンプルコード）を参照ください。

<form action="https://stbfep.sps-system.com/xxxx/xxxxxxxx" method="POST">
     <input type="hidden" name="pay_method" value="credit">
     <input type="hidden" name="merchant_id" value="20053">
     <input type="hidden" name="service_id" value="001">
     <input type="hidden" name="cust_code" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
     <input type="hidden" name="sps_cust_no" value="">
     <input type="hidden" name="sps_payment_no" value="">
     <input type="hidden" name="order_id" value="YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY">     <input type="hidden" name="item_id" value="1"     ・・・     （中略）     ・・・     <input type="hidden" name="free_csv" value=””>
         <!--商品明細行繰り返し start -->
         <!—明細を使用しない場合は丸ごと省略可能です -->
         <input type="hidden" name="dtl_rowno" value="1">
         <input type="hidden" name="dtl_item_id" value="SBPS-001">
         <input type="hidden" name="dtl_item_name" value="テスト明細商品名1">
         <input type="hidden" name="dtl_item_count" value="1">
         <input type="hidden" name="dtl_tax" value="50">
         <input type=”hidden” name="dtl_amount" value="1000">
         <input type="hidden" name="dtl_rowno" value="2">
         <input type="hidden" name="dtl_item_id value="SBPS-002">
         <input type="hidden" name="dtl_item_name" value="テスト明細商品名2">
         <input type="hidden" name="dtl_item_count" value="1">
         <input type="hidden" name="dtl_tax" value="100">
         <input type="hidden" name="dtl_amount" value="2000">
         <!--//商品明細行繰り返し end -->
     <input type=”hidden” name=”request_date” value=”20081015214001”>
     <input type=”hidden” name=”limit_second” value=”600”>
     <input type=”hidden” name=”sps_hashcode” value=” ab8be32d9602530076219c3424122db77d5202bb”>
     <input type=”submit” value=”submit”>
</form>

                     <form action="https://stbfep.sps-system.com/xxxx/xxxxxxxx" method="POST">
     <input type="hidden" name="pay_method" value="credit">
     <input type="hidden" name="merchant_id" value="20053">
     <input type="hidden" name="service_id" value="001">
     <input type="hidden" name="cust_code" value="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
     <input type="hidden" name="sps_cust_no" value="">
     <input type="hidden" name="sps_payment_no" value="">
     <input type="hidden" name="order_id" value="YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY">     <input type="hidden" name="item_id" value="1"     ・・・     （中略）     ・・・     <input type="hidden" name="free_csv" value=””>
         <!--商品明細行繰り返し start -->
         <!—明細を使用しない場合は丸ごと省略可能です -->
         <input type="hidden" name="dtl_rowno" value="1">
         <input type="hidden" name="dtl_item_id" value="SBPS-001">
         <input type="hidden" name="dtl_item_name" value="テスト明細商品名1">
         <input type="hidden" name="dtl_item_count" value="1">
         <input type="hidden" name="dtl_tax" value="50">
         <input type=”hidden” name="dtl_amount" value="1000">
         <input type="hidden" name="dtl_rowno" value="2">
         <input type="hidden" name="dtl_item_id value="SBPS-002">
         <input type="hidden" name="dtl_item_name" value="テスト明細商品名2">
         <input type="hidden" name="dtl_item_count" value="1">
         <input type="hidden" name="dtl_tax" value="100">
         <input type="hidden" name="dtl_amount" value="2000">
         <!--//商品明細行繰り返し end -->
     <input type=”hidden” name=”request_date” value=”20081015214001”>
     <input type=”hidden” name=”limit_second” value=”600”>
     <input type=”hidden” name=”sps_hashcode” value=” ab8be32d9602530076219c3424122db77d5202bb”>
     <input type=”submit” value=”submit”>
</form>

... 3 行すべてを表示する

使用可能なデータ型の定義

リンク型を利用したインターフェースで使用可能なデータ型は、以下のとおりです。

仕様書上の表記	データ型	使用可能文字	備考
９	数値型	1バイトの0～9 （半角数字）	「-」などの符号は許可していません。
Ｘ	半角文字列	以下のASCII文字列 A～Z 半角英大文字 a～z 半角英小文字 0～9 半角数字 * アスタリスク – ハイフン _ アンダーバー @ アットマーク半角スペース . ピリオド	左記以外の半角記号は許可していません。（ + や / など）全角文字は、自動で半角に置換されません。 NET CASH決済の場合、商品IDで使用できるのは、半角英大文字、半角英小文字、半角数字、ハイフン、アンダーバーのみとなります。
Ｍ	マルチバイト文字列	全角文字：　ひらがな　カタカナ　英数字　記号　JIS第一水準漢字　JIS第二水準漢字半角文字：　上記Ｘ欄で定義している半角文字列	以下の8文字は例外で使用できません。 JIS文字コード ― ダッシュ 01区　2130　+D ＼バックスラッシュ 01区　2140　+0 ～波ダッシュ 01区　2140　+1 ‖ パラレル 01区　2140　+2 －二分ダッシュ 01区　2150　+D ¢ セント 01区　2170　+1 £ ポンド 01区　2170　+2 ¬ 否定算術記号 02区　2240　+C ※詳細は、JIS X 0208文字コード表（第2水準）を参照ください。機種依存文字は使用できません。半角カナは全角カナに置換されます。

チェックサム値の生成方法について

リクエストの各タグエレメント（ハッシュ値を除く）の値を項目定義順に文字列結合し、最後に当社より払い出されたハッシュキーを結合した値を「UTF-8」へ変換して、「SHA1」にてハッシュ演算を行ってください。

※必須項目かどうかに関わらず、設定した全ての項目の値を連結する必要があります。

※項目の値の前後に半角スペースが含まれていた場合、連結時には削除した値を利用する必要があります。

※当社からの購入結果（画面返却）のチェックサム値については、文字コードをShift-JISで作成してチェックサム値を設定します。

《ハッシュ生成例》

credit ①

12345 ②

001 ③

TEST1 ④

ABCD1234 ⑤

Goods001 ⑥

テスト商品 ⑦

2000 ⑧

・・・・・ ⑨

387ccbcbf1139f292・・・ ⑩

①当社提供支払方法（pay_method）

②当社提供マーチャントID（merchant_id）

③当社提供サービスID（service_id）

④加盟店固有顧客ID（cust_code）

⑤加盟店固有購入ID（order_id）

⑥加盟店固有商品ID（item_id）

⑦加盟店固有商品名称（item_name）

⑧金額（税込）（amount）

⑨※その他設定した全ての項目を上記同様、項目定義順に連結

⑩当社提供ハッシュキー

上記のように、項目定義順に連結した文字列を「UTF-8」へ変換して、「SHA1」にてハッシュ演算を行った値をハッシュ値とします。生成したハッシュ値は、sps_hashcodeに設定します。

<form action=”https://stbfep.sps-system.com/xxxx/xxxxxxxx” method=”POST”> <input type=”hidden” name=”pay_method” value=”credit”> <input type=”hidden” name=”merchant_id” value=”12345”> <input type=”hidden” name=”service_id value=”001”> <input type=”hidden” name=”cust_code” value=”TEST1”> <input type=”hidden” name=”order_id” value=”ABCD1234”> <input type=”hidden” name=”item_id” value=”Goods001” <input type=”hidden” name=”item_name” value=”テスト商品”> <input type=”hidden” name=”amount” value=”2000”> 　　　　　　　　　　　・　　　　　　　　　　　・　　　　　　　　　　　・ハッシュ値を設定 <input type=”hidden” name=”limit_second” value=”600”> ｚ <input type=”hidden” name=”sps_hashcode” value=”ab8be32d9602・・・”> <input type=”submit” value=”submit”> </form>

リンク型の基本シーケンス

例：購入要求

１）購入要求（購入or解約）をリクエスト

２）購入要求（購入or解約）の結果を通知[結果CGI]

３）結果CGIへの応答を返却

４）購入要求（購入or解約）の結果を通知。また、エンドユーザーの画面を加盟店へ返却

結果CGIレスポンスの共通仕様

結果CGIレスポンスは、HTTPリクエストに対するレスポンスとして、HTTPのBody部にCSV形式（カンマ区切り）にて、「処理結果」＋「,（カンマ）」＋「エラーメッセージ」の記述をお願いします。なお、処理結果がOKの場合は、エラーメッセージの記述は不要です。

例：OKの場合：OK,

　　　NGの場合：NG,既に完売済みです。

※エラーメッセージが100桁以上で返却される場合、アラートメールが送信されますので、100桁以内で設定してください。
※結果CGIのリクエストにはタイムアウトが設定されているため、速やかにレスポンスを返却してください。
タイムアウトとなった場合は、前述の購入結果通知アラートメールが送信されます。

《加盟店の後処理の概念とレスポンス》

（1）CGIと処理結果が共にOKの場合

（2）結果CGIはOKで、処理結果がNGの場合

※決済不整合が発生している可能性があります。リンク型システム仕様書（基本仕様）に記載している結果通知アラートメール受信時と同様の対応をお願いします。
※決済不整合が生じた場合、加盟店との確認の上でSBPS側にて返金処理する場合もございます。また、その際もエンドユーザーへ実際に返金されるまでには時間を要する場合がありますので、予めご注意ください。

（3）結果CGIはNGで、処理結果がOKの場合

※結果CGIでNGを受信したときは、先にNGの後処理を行ったうえで、レスポンスOKを返却してください。

結果（画面返却）の共通仕様

結果（画面返却）には、トランザクショントークンチェック用に [TOKEN] エレメントが格納されております。このエレメントに関しては、ハッシュ演算の対象外項目となります。また、ハッシュ生成ロジックは、Shift-JISでの連結となります。

要求および結果CGI

結果（画面返却）

※チェックサムは英字大文字に変換し設定しております。

要求の端末タイプの設定

要求リクエストの利用端末タイプの設定値およびHTTPリクエストエージェントを判断し、利用端末に合わせた画面イメージを表示します。なお、利用端末タイプが未設定の場合は、PC（0）扱いとして処理されます。

利用端末	リクエストでの利用端末タイプ	HTTP エージェント	表示画面イメージ	カスタマイズ可／不可	備考
PC	0	PC	PC専用	可	カスタマイズの際は別途調整
携帯	1	3キャリア	携帯専用	不可	携帯画面（3キャリア共通）／バックカラー白
Android※1	0	Android	Android 専用	不可	Android画面専用に生成された画面表示を行う
iPhone※1	0	iPhone	iPhone専用	不可	iPhone画面専用に生成された画面表示を行う
iPad※1	0	iPad	PC専用	可	基本PC画面を表示します。

※1：申込時、各利用端末の指示がない場合については、PC画面が表示されます。

購入結果通知アラートメールについて

購入結果通知アラートメールとは、決済完了後に何らかの障害で加盟店へ購入結果CGIが返せなかった場合に、リアルタイムでその旨を案内するアラートメールです。送信先のメールアドレスは、申込時に指定できます。

購入結果通知アラートメールの発報条件

当社より購入結果CGIの送信に失敗した場合
当社より購入結果CGIを送信したが、加盟店側で受信できなかった場合
当社側で加盟店からの購入結果CGIレスポンスを受信できなかった場合
当社側で加盟店からの購入結果CGIレスポンスを受信したが、処理結果がOK／NG以外だった場合

購入結果通知アラートメール発生時のエンドユーザーへの影響

購入結果通知アラートメールは、当社側で決済完了後に行われる処理となるため、実際には決済が完了しているにも関わらず、サービスは提供されていないことがあります。その場合、決済とサービス提供状況の不一致（決済不整合）が起こっている可能性があります。

購入結果通知アラートメール受信時の対応方法

アラートメールを受信した場合、以下の手順で状況を確認した上で表を参考にして対応を判断してください。

当社が提供する決済管理ツールで該当トランザクションを検索し、決済ステータスを確認します。
加盟店側のサービス提供ステータス（提供済または未提供）を確認します。
ご確認いただいた決済ステータスとサービス提供ステータスの結果をもとに対応を判断します。

サービス提供ステータス決済ステータス	サービス提供済	サービス未提供
決済完了（入金済み）	問題なし	返金またはサービス提供
決済未完了（≠入金済み）	サービス停止	問題なし

※決済手段毎に、決済金額のエンドユーザーへの請求タイミングが異なるため、アラートメールを受信した際の対応については、請求タイミングも考慮ください。エンドユーザーへの請求タイミングの詳細は、各決済手段のサービス仕様書を参照ください。

購入結果通知アラートメールのサンプル

以下のようなアラートメールが当社より加盟店に送信されます。

【件名】 SBPSマルチ決済サービス　決済結果通知エラー報告
【本文】「購入結果通知」処理中に、障害が発生しました。
マーチャント名：○○○○
発生日時：2006/10/05 12:27:15
発生箇所：1 発生内容：3
【処理レコード】
マーチャントID：12345
サービスID：001
購入ID：762f97146a5858131229dae931295fb6
トラッキングID：93899499957845
SBPSトランザクションID：8fae36dace2f2b69ed56924538dcfd85
【購入結果CGIのリクエスト内容】
処理結果支払方法：WebMoney
処理結果ステータス：OK
エラーコード：1301
購入完了処理日時：20061005122715
–凡例—
（発生箇所） 1：マーチャント 2：FEP 3：G/W 4：決済機関 5：マーチャント-GW
（発生内容） 1：リクエスト／レスポンスエラー 2：内部処理エラー 3：接続エラー 4：設定エラー（処理結果ステータス） OK：要求処理OK NG：要求処理NG CR：退会通知（継続課金停止）

※メールの記載内容は、予告なく変更される場合があります。

特記事項

当社の証明書

当社で表示する全画面は、SSL認証です。サイバートラスト社（https://www.cybertrust.co.jp/）発行の証明書を導入しています。当社画面連携システムについては、SSL通信が必須となり、httpsでのリクエストとなります。

冗長化

結果通知と送受信するサーバについて冗長化した場合、プライマリ、セカンダリの指定は必要ありません。但し、通知先URLについては同じにする必要があります。

顧客決済情報の保管と顧客IDの設定

エンドユーザーの決済情報は、リクエストに設定される加盟店管理の顧客IDと対に保管されます。従って、リクエストに設定する加盟店管理の顧客IDは、必ず一意となるようにお願いします。
加盟店サイトで一見のエンドユーザーを扱う場合、購入要求リクエストに設定する顧客IDの先頭に“reg_sps”を設定すると、顧客決済情報保管機能が無効（カード入力画面の保管有無チェックボックス無し）となります。
※楽天ペイ（オンライン決済）およびTポイントプログラム（オンライン決済）では、“reg_sps”での決済は不可となります。

各結果CGIの通知元IPアドレス

テスト環境：61.215.213.47
本番環境：61.215.213.20

※加盟店にて通信制限されている場合は、上記IPからの通信許可をお願いします。

当社表示の各画面ドメイン（全決済共通）

テスト環境：http://stbfep.sps-system.com/要求毎のパス
本番環境：https://fep.sps-system.com/要求毎のパス

※各要求の接続先は環境構築完了後、連絡します。

※テスト環境と本番環境では接続先が異なりますので、本番環境への切り替え時には接続先にご注意ください。

利用可能な暗号化プロトコルについて

当社が準拠するPCI DSSの定めにより「SSL 3.0」「TLS 1.0」は利用できません。

また、「TLS 1.1」に関しても暗号化方式としての脆弱性に指摘があり、将来的に使用を禁止される可能性が高いため、加盟店においては「TLS 1.2」を利用ください。

リンク型におけるApple Pay決済について

当社のリンク型におけるApple Pay決済は Apple Pay on the Web を利用しております。

動作環境や制約につきましては、以下を参照ください。

https://developer.apple.com/documentation/apple_pay_on_the_web

顧客IDについて

顧客IDに以下の文字列をご使用されないよう、ご留意をお願いいたします。

SPSTestUser0001　／　SPSTestUser0002　／　SPSTestUser0003　／　SPSTestUser0004　／　SPSTestUser0005

各仕様書の項目定義に記載の桁数について

各仕様書の項目定義に記載の桁数はbyte数です。マルチバイト項目でもbyte数を記載しております。
マルチバイト項目の場合は、エンコード前の桁数です。

検証環境における負荷試験について

決済機関の仕様により検証環境における負荷試験は不可となります。ご要望の際は別途お問い合わせください。

SSLについて

利用可能SSL

リンク型では、各要求で加盟店より指定されたURLに対し、結果CGIをリクエストします。SSL通信でのリクエストとなるため、受信先（加盟店サーバ）に正規SSL証明書の実装が必要となります。当社とのSSL通信が可能な主な証明書につきましては、以下の表を参照ください。なお、以下の表は、当社でのSSL通信の設定および疎通実績から取得したものであり通信を担保するものではありませんので、必ず事前に疎通確認をお願いします。

《通信確認済SSL証明書》（※2016/02現在）

No	利用可能なルート証明書	認証企業名	主な証明書商品名
1	Baltimore CyberTrust Root ※1	サイバートラスト株式会社	SureServer[SHA-2] SureServer EV[SHA-2]
			SureServer[SHA-2] SureServer EV[SHA-2]
			SureServer[2048bit] SureServer EV[2048bit]
			SureServer[2048bit] SureServer EV[2048bit]
	GTE CyberTrust Global Root ※1		SureServer[2048bit] SureServer EV[2048bit]
	GTE CyberTrust Global Root ※1		SureServer[2048bit] SureServer EV[2048bit]
2	GlobalSign	GMOグローバルサイン株式会社	EV SSL
2	GlobalSign	GMOグローバルサイン株式会社	EV SSL
3	VeriSign Class 3 Public Primary Certification Authority – G5	合同会社シマンテック・ウェブサイトセキュリティ	セキュア・サーバID グローバル・サーバID セキュア・サーバID EV グローバル・サーバID EV



4	GeoTrust Global CA	日本ジオトラスト株式会社	クイックSSLプレミアムクイックSSLプレミアムワイルドカードトゥルービジネスID トゥルービジネスID ワイルドカード



5	Starfield Class 2 Certification Authority ※1	ジェイサート株式会社	スターフィールドスタンダードSSL スターフィールドデラックスSSL スターフィールドEV SSL


6	Security Communication RootCA2	セコムトラストシステムズ株式会社	セコムパスポートfor Web SR 3.0 セコムパスポートfor Web EV 2.0


	Security Communication RootCA1 ※1		セコムパスポートfor Web SR 2.0 セコムパスポートfor Web EV

※1：販売終了のため、証明書の有効期限までは利用可能です。

※証明書商品は認証企業により予告なく変更になる場合がありますので、必要に応じて認証企業へお問い合わせください。

※加盟店のシステム環境によって、クロスルート証明書等の実装が必要となる場合があります。詳細は認証企業にお問い合わせください。当社では、加盟店の環境設定にお答えできない場合があります。

※当社サーバに対するルート証明書やクロスルート証明書等の実装は承れませんので、ご了承ください。

※プライベートSSL証明書は利用できませんので、正規SSL証明書を利用ください。

テスト環境でのSSL証明書

テスト環境では非SSL通信でも疎通が可能となります。その場合は、各要求でのインターフェース上の通知先URL（pagecon_url）の値をhttp://～で設定します。

※本番環境では、正規SSL証明書のみのSSL通信となりますのでご注意ください。

※テスト環境に対するプライベートSSL証明書の組込み依頼は対応していません。

※Basic認証を設定している場合は、エラーとなり通知ができないため、必ず認証設定を外してください

はじめに

接続方式

課金方式

決済サービス

決済サービス|オプション

決済管理ツール

テスト

お知らせ

基本仕様