Link Type - Basic Specifications | Developer

Overview of connection method

This is a schematic diagram showing the integration and processing between the merchant's site using the API model and SBPS’s payment server.

Example: Credit Card Payment:

The above is a diagram to help you understand the overview. For details, please be sure to check the "Service Overview" and "API Type Interface Specifications" for each payment method.

XML Format

Basic Rules

The XML used in the API type complies with XML 1.0 recommended by W3C and uses Shift_JIS as character encoding (character sets). The basic structure is shown below. Make sure to write the XML declaration in the first tag. Also, make sure that child tags are nested within parent tags.

<?xml version="1.0" encoding="Shift_JIS"?>
 <親タグ>
  <子タグ1>～</子タグ1>
  <子タグ2>～</子タグ2>
  <子タグn>～</子タグn>
 </親タグ>

                     <?xml version="1.0" encoding="Shift_JIS"?>
 <親タグ>
  <子タグ1>～</子タグ1>
  <子タグ2>～</子タグ2>
  <子タグn>～</子タグn>
 </親タグ>

... 3Show all rows

Tag names are distinguished between upper- and lowercase letters, and so they must be specified correctly. You can omit optional child tags by using the following methods, unless otherwise stated. In requests/responses from SBPS, the notation in (2) is used.

Omit the tag itself.
<tag name></tag name>
<tag name/>

Outside tags, you can use comment tags, tab characters (09H), newlines (0AH), and carriage returns (0DH) as needed. Content within tags (tag values, actual data) should follow the following rules:

Single-byte and double-byte spaces before, within, or after character strings contained in tags are not deleted, but used as they are.
Single-byte and double-byte spaces before, within, or after numeric field values result in errors.
Tab characters (09H), newlines (0AH), and carriage returns (0DH) are not allowed. If used, they result in errors.
Pictographs specific to particular mobile phones are not allowed. If specified, they result in errors.
Forbidden characters in values must always be replaced with escape characters.
（　 < → <　& → &　> → >　” → "　’ → ' etc. ）

Sample XML Code

<?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>

                     <?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>

... 3Show all rows

Set the ID attribute of sps-api-request in the 2nd line to the function ID assigned to each API. For function IDs, see the payment method-specific API Type System Specifications.

Definitions of Available Data Types

The data types valid for interfaces using the API Type are as follows.

Notation in specification documents	Data type	Valid characters	Remarks
９	Numeric	One byte 0–9 (single-byte numbers)	Signs such as “-” are not allowed.
X	Single-byte characters	The following ASCII characters: Character Description A-Z (single-byte uppercase letters) a-z (single-byte lowercase letters) 0-9 (single-byte digits) (*) Asterisk (-) Hyphen (_) Underscore (@) at symbol Single-byte space (.) Period	Single-byte symbols other than the ones shown on the left are not allowed. (+, /, etc.) Double-byte characters will not automatically be replaced with single-byte characters.
M	Multi-byte character string	Double-byte characters: Hiragana Katakana Alphanumeric characters Symbols JIS level-1 kanji set JIS level-2 kanji set Single-byte characters: the single-byte characters shown in the X section above	As exceptions, the following eight characters are not allowed: Character Description JIS character encoding (―) Dash: Row 01, Code 2130, +D (＼) Backslash: Row 01, Code 2140, +0 (～) Wave dash: Row 01, Code 2140, +1 (‖) Parallel: Row 01, Code 2140, +2 (－) Nut dash: Row 01, Code 2150, +D (¢) Cent sign: Row 01, Code 2170, +1 (£) Pound sign: Row 01, Code 2170, +2 (¬) Negation arithmetic symbol: Row 02, Code 2240, +C * For details, see the JIS X 0208 Character Encoding Table. Platform dependent characters are not allowed. Characters that can be used for each field are limited. For details, see the payment method-specific API Type Interface Specifications. BASE64 encoding is required for multi-byte character fields when they are transmitted.

Encryption

Triple DES using the encryption key assigned by SBPS is required for payment-specific parameters (such as credit card information and customer information). For testing or in environments where cooperation can be achieved through VPN or dedicated lines, configuration without Triple DES is also allowed. For fields that require encryption, see the payment method-specific API Type System Specifications.

The following shows the encryption procedure.

Encode required fields with Triple DES using an encryption key sent from SBPS.

Algorithm: 3DES-CBC (no padding)
Padding character string: Single-byte space

* For no automated padding, a complementary character is required for the last eight-byte block.

Example: Padding processing in the encryption of the character string "ABCDEFGHIJKLMN"ABCDEFGH IJKLMN□□ *□: (single-byte space)

ABCDEFGH　IJKLMN□□　　*□: Single-byte space

Key length: 192 bits

Content	Byte length	Remarks
Secret key	24	Provided by SBPS after application
Initialization vector (iv)	8	Provided by SBPS after application

Apply BASE64 encoding.

Hash Calculation

Concatenate the character string of each tag element value (other than the hash value) in the request according to the item definition order, convert the concatenated hash key assigned by SBPS lastly, and then perform the hash function on the given value using SHA1.

* It is necessary to concatenate every item value you set whether or not it is a value for a mandatory field.

* If single-byte spaces are included before and/or after the item value of each field, it is necessary to delete the spaces from the value before it is used for concatenation.

* The hash function must be performed on data to which URL encoding, BASE64 encoding, or Triple DES is not yet applied.

[Example Hash Generation]

12345 ①

001 ②

SPSUSR000001③

SPSODR000001 ④

ITEM001⑤

500SPSCCoin ⑥

500⑦

....⑧

b5bb3540cefd944cb9e9904 ⑨

(1) Merchant-specific code (Merchant ID) assigned by SBPS

(2) Merchant service code (Service ID) assigned by SBPS

(3) Merchant-specific customer code

(4) Merchant-specific order code

(5) Merchant-specific item code

(6) Merchant-specific product name

(7) Payment amount

(8)* Any other item you set should be concatenated according to the item definition order in the same way as the above items

(9) Hash key assigned by SBPS

As described above, the hash value should be generated by converting the character string concatenated according to the item definition order and then performing the hash function on the value using SHA1.

Special notes

Communication Environment

To use the API Type, an Internet connection via SSL, or connection through a dedicated line or VPN is required.

Communication Protocol

All communications in the API Type are performed using HTTPS/Post requests. SSL encryption is required.

Available Encryption Protocols

Due to the regulations of PCI DSS (which SBPS complies with), SSL 3.0 and TLS 1.0 cannot be used.

In addition, there is a high possibility that the use of TLS 1.1 will be prohibited in the future because its vulnerabilities as an encryption method have been disclosed. Therefore, Merchants shall use TLS 1.2.

Basic Access Authentication

For all communications in the API Type, Basic access authentication is required. The ID and password for Basic access authentication will be provided to the person in charge at the Merchant once the setup is completed.

Connection Target

The connection target information on the SBPS system will be sent to the person in charge at the Merchant once the setup is completed.

Maximum Number of Concurrent Connections

The maximum number of concurrent connections from the Merchant to SBPS is five. If you wish to increase the number, please contact our sales representative.

Response Timeout

Because notifications from SBPS to Merchants have a timeout setting, return a response swiftly.
If an error occurs, refer to the payment administration tool provided by SBPS.

Customer ID

Do not use the following strings in a customer ID:

SPSTestUser0001 / SPSTestUser0002 / SPSTestUser0003 / SPSTestUser0004 / SPSTestUser0005

Number of Digits Shown in Field Definitions in Specifications

The number of digits shown in field definitions in specifications is the number of bytes. Even the number of digits of a multi-byte field shows the number of bytes.

The number of digits of a multi-byte field shows the number of digits before encoded.

Load Testing in the test environment

Due to the specifications of the payment institution, load testing in the test environment is not possible. Please contact us for details.

AboutTracking ID

The tracking ID issued by us is a unique value for each payment method.

Introduction

Connection method

Billing method

Payment Services

Payment Services | Options

Payment management tool

Test

Notices

Basic Specifications