Developer/接続方式/API型/基本仕様

基本仕様

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

例：クレジットカード決済の場合

上記は概要を理解いただくための図となります。詳細は決済手段別の「サービス概要」と「API型 IF仕様」を必ずご確認ください。

XMLフォーマット

基本ルール

API型で利用するXMLは、W3Cから勧告されたXML 1.0に準拠し、文字コード（キャラクタセット）はShift_JISを使用します。基本的な構造は以下のとおりです。最初のタグは必ずXML宣言を記述してください。また、親タグ、子タグは必ず入れ子にして記述してください。

XML
                     <?xml version="1.0" encoding="Shift_JIS"?>
 <親タグ>
  <子タグ1>～</子タグ1>
  <子タグ2>～</子タグ2>
  <子タグn>～</子タグn>
 </親タグ>
... 3 行すべてを表示する

タグ名の大文字と小文字は区別されるので、正しく指定してください。特に明記がない限り、任意の子タグは以下の記述方法で省略できます。当社からのリクエスト／レスポンスでは、(2)の表記になります。

  • タグそのものを記載しない。
  • <タグ名></タグ名>
  • <タグ名/>

タグの外側ではコメントタグ、タブ文字（09H）、改行（0AH）、復帰（0DH）を適宜利用できます。タグの内側（タグの値、実データ）は以下のルールに従います。

  • タグの内側にある文字列の前、途中、後にある半角スペースと全角スペースは削除されずにそのまま使用されます。
  • 数値項目の前、途中、後に半角スペース、全角スペースがある場合はエラーとなります。
  • タブ文字（09H）、改行（0AH）、復帰（0DH）は使用できません。使用した場合はエラーとなります。
  • 携帯電話固有の絵文字は指定できません。絵文字を指定した場合はエラーとなります。
  • 各値に使用できない文字は、必ずエスケープ文字を利用する必要があります。
    （　 < → &lt;　& → &amp;　> → &gt;　” → &quot;　’ → &apos;　など ）

サンプルXMLコード

XML
                     <?xml version="1.0" encoding="Shift_JIS"?>
  <sps-api-request id="ST01-00101-101">
    <merchant_id>99999</merchant_id>
    <service_id>001</service_id>
    <cust_code>CUSTCODE123456789012</cust_code>
    <order_id>ODRABCDE123456789</order_id>
    <item_id>ITMABCDE123456789</item_id>
    <amount>1000</amount>
    <pay_method_info>    暗号化が必須である項目もあります。
      <cc_number>1234567890123456</cc_number>   詳細は決済手段別の 「API型 IF仕様」 を参照ください。 
      <cc_expiration>201305</cc_expiration>
      <cust_manage_flg>0</cust_manage_flg>
    </pay_method_info>     
    <encrypted_flg>0</encrypted_flg>    
    <request_date>20080220092420</request_date>  
    <sps_hashcode>70352f41061eda4ff3c322094af068ba70c3b38b</sps_hashcode> 
  </sps-api-request>
... 3 行すべてを表示する

2行目のsps-api-requestのID属性に、API毎に割り当てられた機能IDをセットします。機能IDについては、決済手段別の「API型 IF仕様」を参照ください。

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

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

仕様上 の表記データ型使用可能文字備考
９数値型1バイトの0～9（半角数字）「-」などの符号は許可していません。
Ｘ半角文字列以下のASCII文字列
文字 説明
A～Z 半角英大文字
a～z 半角英小文字
0～9 半角数字
* アスタリスク
– ハイフン
_ アンダーバー
@ アットマーク
半角スペース
. ピリオド 　		左記以外の半角記号は許可していません。
（ + や / など）
全角文字は、自動で半角に置換されません。
Ｍマルチバイト 文字列全角文字：
ひらがな
カタカナ
英数字
記号
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文字コード表」を参照ください。機種依存文字は使用できません。
各項目に使用できる文字の制約があります。詳細は決済手段別の「API型 IF仕様」を参照ください。
マルチバイト文字列項目は、送信時にBASE64エンコードが必須となります。

決済固有パラメータ（クレジットカード情報やお客様情報等）について、当社から払い出される暗号化キーによる3DES暗号化を必須としています。試験時や、VPN・専用線経由での連携が可能な環境においては、3DESを必須としない設定も可能です。暗号化が必須である項目については、決済手段別の「API型 IF仕様」を参照ください。

暗号化の手順は、以下のとおりです。

  • 当社より送付する暗号化キーを利用し、必要項目を3DESにてエンコードします。
  • アルゴリズム：3DES-CBC（Paddingなし）
  • Padding文字列：半角スペース

              ※自動Paddingなしのため、最後の8バイトブロックに対し、補完文字列が必要です。

              例）文字列「ABCDEFGHIJKLMN」の暗号化のPadding処理

              　　ABCDEFGH　IJKLMN□□　　※□：半角スペース

  • キー長：192ビット
内容バイト長備考
秘密キー24申込後、当社より提供します。
初期化ベクトル（iv）8
  • BASE64エンコードを行います。

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

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

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

※URLエンコード、BASE64エンコード、3DES暗号化処理を行う前のデータにてハッシュ演算を行う必要があります。

【ハッシュ生成例】

12345 ①001 ②SPSUSR000001 ③SPSODR000001 ④ITEM001 ⑤500SPSCコイン ⑥500 ⑦・・・・・ ⑧b5bb3540cefd944cb9e9904 ⑨

              ①当社提供　加盟店固有コード（マーチャントID）

              ②当社提供 加盟店サービスコード（サービスID）

              ③加盟店固有　顧客コード

              ④加盟店固有　注文コード

              ⑤加盟店固有　商品コード

              ⑥加盟店固有　商品名称

              ⑦決済金額

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

              ⑨当社提供　ハッシュキー

上記のように、項目定義順に連結した文字列に対して、「SHA1」にてハッシュ演算を行った値をハッシュ値とします。

特記事項

通信環境について

API型を利用するにあたり、SSLでのインターネット接続もしくは、専用線・VPNでの接続が必須となります。

通信プロトコルについて

API型では、全てHTTPS/POSTでの通信となります。SSLによる暗号化は必須となります。

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

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

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

ベーシック認証について

API型は、全ての通信においてベーシック認証を必須としています。ベーシック認証のIDおよびパスワードは、設定完了時に加盟店担当者へお送りします。

接続先について

当社システムの接続先の詳細につきましては、設定完了時に加盟店担当者へお送りします。

最大同時接続数について

加盟店から当社への最大同時接続数は5接続です。それ以上に接続数を増やしたい場合は、当社営業までお問い合わせください。

レスポンスタイムアウトについて

当社から加盟店への通知はタイムアウト設定があるため、速やかにレスポンスを返却してください。
エラーが発生した場合は、弊社提供の決済管理ツールを参照ください。

顧客IDについて

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

SPSTestUser0001　／　SPSTestUser0002　／　SPSTestUser0003　／　SPSTestUser0004　／　SPSTestUser0005

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

　各仕様の項目定義に記載の桁数はbyte数です。マルチバイト項目でもbyte数を記載しております。

　マルチバイト項目の場合は、エンコード前の桁数です。

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

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

このページは役に立ちましたか？