# (주)케이에스넷

{% hint style="warning" %}
**Deprecated**

이 문서는 더 이상 관리되지 않습니다.

[PortOne 개발자센터](https://developers.portone.io/)를 이용해주세요.
{% endhint %}

<figure><img src="https://2409678497-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwWX2hlvRZLZrXeH1aacF%2Fuploads%2FGJaqWSOGtOi1G4y3wfra%2Fimage.png?alt=media&#x26;token=d8179d39-1b07-4667-a189-a3484629b580" alt=""><figcaption><p>(주)케이에스넷</p></figcaption></figure>

### 1. (주)케이에스넷 PG 설정하기

[**KSNET 설정**](https://portone.gitbook.io/docs/ready/2.-pg/payment-gateway/ksnet) 페이지의 내용을 참고하여 PG 설정을 진행합니다.

### 2. 결제 요청하기

[JavaScript SDK (신규))](https://portone.gitbook.io/docs/sdk/javascript-sdk) IMP.**request\_pay**(param, callback)을 호출하여 KSNET 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request\_pay(param, callback) 호출 후 <mark style="color:red;">**callback**</mark>으로 수신되고 모바일의 경우 <mark style="color:red;">**m\_redirect\_url**</mark>로 리디렉션됩니다.

{% hint style="warning" %}
기존 JavaScript SDK를 사용 중이신 경우 [JavaScript SDK (신규))](https://portone.gitbook.io/docs/sdk/javascript-sdk) 문서를 참고하여 업데이트를 진행해주세요.
{% endhint %}

(주)케이에스넷 결제는 최신 SDK에서만 지원되는 기능입니다.

{% code title="JS SDK" %}

```javascript
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>
```

{% endcode %}

{% hint style="info" %}
**(주)케이에스넷을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다**
{% endhint %}

{% hint style="danger" %}
**기존에 deprecated된 응답들은 모두 제거됐습니다. ⚠️**

케이에스넷 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 dprecated 로 명시된 파라미터는 모두 삭제되었습니다.)

해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다.

**imp\_uid, merchant\_uid**

따라서 해당 SDK를 사용하실때는 IMP.request\_pay로부터 응답된 객체(또는 쿼리 파라미터)에서 imp\_uid를 가지고 **아임포트 REST API(GET /payments/imp\_uid)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 응답파라미터중 status 파라미터로 결제 상태를 파악하셔야 합니다.
{% endhint %}

{% hint style="info" %}

```
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>

위 JS SDK 를 이용하여 토스페이먼츠,케이에스넷 연동시 callback Data는 
아래와 같이 두가지 형태로만 내려갑니다.

imp_uid
merchant_uid

위 PG사를 제외한 다른 PG사는 imp_success 파라미터가 기존처럼 내려가지만 
해당 파리미터는 deprecated 된 값이기 때문에 해당 값에 의존성을 가진 프로그램 로직은 모두 삭제하시는
방향성을 잡아가셔야 하는점 유념하시기 바랍니다.
```

{% endhint %}

{% tabs %}
{% tab title="인증결제창 요청" %}
{% code title="Javascript SDK" %}

```javascript
IMP.request_pay({
  pg: "ksnet.{PG 상점 아이디}", // 테스트인경우 ksnet.2999199999
  pay_method: "card",
  merchant_uid: "order_id_1667634130160", // 상점에서 채번하는 고유 주문 번호
  name: "나이키 와플 트레이너 2 SD",
  pay_method: "card",
  escrow: false,
  amount: "109000",
  tax_free: 3000,
  buyer_name: "홍길동",
  buyer_email: "buyer@example.com",
  buyer_tel: "02-1670-5176",
  buyer_addr: "성수이로 20길 16",
  buyer_postcode: "04783",
  app_scheme: "portone://",
  m_redirect_url: "https://helloworld.com/payments/result",
  notice_url: "https://helloworld.com/api/v1/payments/notice",
  confirm_url: "https://helloworld.com/api/v1/payments/confirm",
  currency: "KRW",
  digital: false,
  period: {
    from: "2022-12-01",
    to: "2023-01-01",
  },
  custom_data: { userId: 30930 },
  display: { card_quota: [0, 6] },
  bypass: {
    ksnet: {
      sndQpayType: "0",
    },
  },
}, function (rsp) { // callback 로직
  //* ...중략... *//
});
```

{% endcode %}

**주요 파라미터 설명**

**`pg`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**PG사 구분코드**

`ksnet.{PG 상점 아이디}`

**`pay_method`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**결제수단 구분코드**

* card (신용카드)
* vbank (가상계좌)
* trans (계좌이체)
* phone (휴대폰소액결제)
* lpay (LPAY)
* ssgpay (SSGPAY)
* kakaopay (카카오페이)
* naverpay (네이버페이)
* payco (페이코 허브형)

**`merchant_uid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**가맹점 채번 주문 고유번호**

가맹점에서 매번 고유하게 채번되어야 합니다.

**`amount`** <mark style="color:green;">**string**</mark>

**결제금액**

지정하지 않은 경우 0원입니다.

**`tax_free`** <mark style="color:purple;">**integer**</mark>

**면세금액**

지정하지 않은 경우 0원입니다.

{% hint style="info" %}
포트원을 통해 KSNET를 사용하는 경우 과세 설정이 `복합과세`이므로 면세금액을 반드시 입력해야 합니다.
{% endhint %}

**`digital`** <mark style="color:orange;">**boolean**</mark>

**디지털 상품 유형 여부**

{% hint style="info" %}
해당 필드는 **휴대폰 결제**에서만 사용되며, 상점이 `디지털 상품유형`으로 설정된 경우 항상 `true`로 전달해야 합니다.
{% endhint %}

**`bypass.ksnet`**

**KSNET 전용 파라미터**

상단의 `request_pay` 예제를 참고하여 KSNET 전용 파라미터를 기입할 수 있습니다.

> **`sndQpayType`** <mark style="color:green;">**string**</mark>
>
> **카드 결제 시 결제창에 간편 결제 수단 표시 여부**
>
> * `"0"`: 간편결제 수단 표시하지 않음
> * `"1"`: 간편결제 수단 표시함
>   {% endtab %}

{% tab title="비인증 결제창 요청" %}
**(주)케이에스넷은 결제창 기반 비인증 결제를 지원하지 않습니다.**
{% endtab %}

{% tab title="API 결제" %}

#### 일회성 결제 요청하기

REST [**API POST /subscribe/payments/onetime**](https://portone.gitbook.io/docs/api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/onetime
```

#### 빌링키 발급 요청하기

REST [**API POST /subscribe/customers/{customer\_uid}**](https://portone.gitbook.io/docs/api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \
     https://api.iamport.kr/subscribe/customers/your-customer-unique-id
```

#### 빌링키 발급 및 최초 결제 요청하기

REST [**API POST /subscribe/payments/onetime**](https://portone.gitbook.io/docs/api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다.

* **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/onetime 
```

#### 빌링키로 결제 요청하기

빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](https://portone.gitbook.io/docs/api/api-4/api)) REST API를 다음과 같이 호출합니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
     https://api.iamport.kr/subscribe/payments/again
```

{% endtab %}
{% endtabs %}

## 3. API 기능

### 승인 취소(환불)

결제 승인 완료 건에 대해 승인 취소(환불)를 할 수 있는 API입니다.\
REST [**API POST /payments/cancel**](https://portone.gitbook.io/docs/api/api-1/api)를 호출하여 승인 취소(환불)을 요청합니다.

### 현금영수증 등록

포트원을 통한 거래건이지만 결제창에서 현금영수증 등록을 하지 못한 경우 API를 통해 현금영수증을 등록할 수 있습니다.\
REST [**API POST /receipts/{imp\_uid}**](https://portone.gitbook.io/docs/api/api-8/api-2)를 호출하여 현금영수증을 요청합니다.

* `product_type`, `buyer_name` 파라미터는 KSPAY 필수 입력 대상입니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"identifier": "1178178260", "identifier_type": "business", "type": "company", "product_type": "digital"}' \
     https://api.iamport.kr/receipts/{imp_uid}
```

### 외부 현금영수증 등록

포트원을 통한 거래건이 아닌 현금성 거래의 경우에도 API를 통해 현금영수증을 등록할 수 있습니다.\
REST [**API POST /receipts/external/{merchant\_uid}**](https://portone.gitbook.io/docs/api/api-8/api-5)를 호출하여 현금영수증을 요청합니다.

* `product_type`, `pg`, `buyer_name` 파라미터는 KSPAY 필수 입력 대상입니다.

```
curl -H "Content-Type: application/json" \   
     -X POST -d '{"merchant_uid": "order_id_1667643230720", "name": "나이키 와플 트레이너 2 SD", "amount": 109000, "identifier": "1178178260",  "identifier_type": "business", "type": "company", "product_type": "digital", "tax_free": "3000", "pg": "ksnet"}' \
     https://api.iamport.kr/receipts/external/{merchant_uid}
```

## 4. 부가기능

{% code title="javascript" %}

```javascript
display: {
    card_quota: [6]  // 할부개월 6개월까지만 활성화
}
```

{% endcode %}

**파라미터 설명**

* **card\_quota :**
  * `[]`: 일시불만 결제 가능
  * `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\\

{% hint style="info" %}
할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다.
{% endhint %}

할부개월수 <mark style="color:red;">**3개월**</mark>**까지 활성화 예제**

{% embed url="<https://codepen.io/chaiport/pen/yLpMvYJ>" %}