KSNET

1. KSNET 채널 설정하기

결제대행사 채널 설정하기 페이지의 내용을 참고하여 채널 설정을 진행합니다.

2. 결제 요청하기

JavaScript SDK (신규)의 IMP.request_pay(param, callback)을 호출하여 KSNET 결제창을 호출할 수 있습니다. 결제결과는 PC의 경우 IMP.request_pay(param, callback) 호출 후 callback으로 수신되고 모바일의 경우 m_redirect_url로 리디렉션됩니다.

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

JavaScript SDK
IMP.request_pay(
  {
    channelKey: "{콘솔 내 연동 정보의 채널키}",
    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 로직
    //* ...중략... *//
  },
);

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

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

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

3. API 기능

승인 취소(환불)

결제 승인 완료 건에 대해 승인 취소(환불)를 할 수 있는 API입니다.
REST API POST /payments/cancel를 호출하여 승인 취소(환불)을 요청합니다.

현금영수증 등록

포트원을 통한 거래건이지만 결제창에서 현금영수증 등록을 하지 못한 경우 API를 통해 현금영수증을 등록할 수 있습니다.
REST API POST /receipts/{imp_uid}를 호출하여 현금영수증을 요청합니다.

• product_type(디지털: "digital", 실물: "real"), buyer_name 파라미터는 KSNET 필수 입력 대상입니다.

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}를 호출하여 현금영수증을 요청합니다.

• product_type, pg, buyer_name 파라미터는 KSNET 필수 입력 대상입니다.

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. 부가기능

할부개월수 렌더링

결제창 호출 시 표시할 할부개월수를 설정할 수 있습니다.

{
  //...중략
  "display": {
    "card_quota": [5, 6] // 할부개월 5,6개월만 활성화
  }
}

상점 부담 무이자 할부의 경우 card.detail 파라미터를 사용하여 최대 할부개월수 설정이 가능합니다.

{
  "card": {
    "detail": [
      { "card_code": "366", "max_month": 5 }, // 특정 카드사 (신한카드) 상점 부담 무이자 최대 5개월 할부 설정
      { "card_code": "381", "max_month": 3 } // 특정 카드사 (KB국민카드) 상점 부담 무이자 최대 3개월 할부 설정
    ]
  }
}

자세한 상점 부담 무이자 할부 설정 가이드는 [API&SDK] - [브라우저 SDK] - [결제요청 파라미터] - [상점 부담 무이자 할부 최대 개월수 설정하기 에서 확인 가능합니다.

파라미터 설명

카드사 다이렉트 호출

카드사 다이렉트 호출 시 결제대행사의 통합결제창을 거치지 않고, 지정한 카드사의 결제화면이 호출됩니다.

{
  //...중략
  "card": {
    "direct": {
      "code": "361" // 카드사 지정
    }
  }
}

파라미터 설명

유의사항

간편결제 다이렉트 호출

{
  //...중략
  "bypass": {
    "ksnet": {
      "easyPayDirect": true
    }
  },
  "pay_method": "naverpay",
  "storeDetails": {
    "ceoFullName": "홍길동",
    "address": "서울시 ...",
    "phoneNumber": "01000000000",
    "businessName": "상호명",
    "businessRegistrationNumber": "000000000"
  }
}

• KSNET 간편결제 다이렉트는 아래의 결제 방식을 지원합니다.

  • 네이버페이 카드
  • 카카오페이 카드 및 머니
  • 페이코
  • L페이 카드

• 네이버페이 머니·포인트의 경우 현재 KSNET에서는 다이렉트 호출을 지원하지 않습니다.

• 간편결제 다이렉트를 사용하기 위해서는 bypass.ksnet.easyPayDirect를 true로 설정하고, pay_method를 naverpay, kakaopay, payco, lpay 중 하나로 지정합니다.

• 구매자 이름(buyer_name)을 입력해야 합니다.

• 네이버페이의 경우

  • 현재 카드 결제만 가능
  • 상점명(storeDetails.businessName) 필수
  • buyer_email, buyer_tel 선택
  • 할부 개월 수 표시 설정 가능
  • 이용 가능 카드사 설정 가능 (신한, BC, 국민, 농협, 롯데, 삼성, 시티, 우리, 하나, 현대)

• 카카오페이의 경우

  • 상점 대표자명(storeDetails.ceoFullName) 필수
  • 상점 주소(storeDetails.address) 필수
  • 상점 전화번호(storeDetails.phoneNumber) 필수
  • buyer_email, buyer_tel 필수
  • 할부 개월 수 표시 설정 가능
  • 이용 가능 카드사 설정 가능 (신한, BC, 국민, 농협, 롯데, 삼성, 시티, 우리, 하나, 현대)

• 페이코의 경우

  • 상점명(storeDetails.businessName) 필수
  • 사업자등록번호(storeDetails.businessRegistrationNumber) 필수
  • buyer_email, buyer_tel 필수

• L페이의 경우

  • buyer_email, buyer_tel 선택