한국결제네트웍스(KPN)

채널 설정하기

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

사전 계약 안내

아래 기능을 사용하시려면 한국결제네트웍스(KPN)에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다.

• API를 통한 수기(키인) 결제 (카드, 가상계좌)
• API를 통한 빌링키 발급
• 에스크로 결제 (결제창)
• 가상계좌 입금통보 설정 (백노티)
• 상점분담무이자 설정
• 부분무이자 설정
• 비과세 금액 직접 설정
• 간편결제 다이렉트 호출
• 결제 취소 시 계좌 환불 서비스 설정

가능한 결제 수단

• 결제창 일반 결제

  payMethod 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

  • 카드 : CARD
  • 계좌이체 : TRANSFER
  • 가상계좌 : VIRTUAL_ACCOUNT
  • 휴대폰 소액 결제 : MOBILE
  • 간편결제 : EASY_PAY

• 결제창 빌링키 발급

  billingKeyMethod 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

  • 카드: CARD

• API 수기(키인) 결제

  method 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

  • 카드: card 로 설졍하여 카드 관련 파라미터 입력
  • 가상계좌: virtualAccount 로 설정하여 가상계좌 관련 파라미터 입력

  자세한 파라미터 구성은 REST API Docs 를 참고해주시기 바랍니다.

• API 빌링키 발급

  method 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

  • 카드: card 로 설졍하여 카드 관련 파라미터 입력

  자세한 파라미터 구성은 REST API Docs를 참고해주시기 바랍니다.

SDK 결제 요청하기

결제 요청 시에는 requestPayment 함수를 호출해야 합니다. channelKey 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 한국결제네트웍스(KPN) 채널 사용을 명시해주세요.

한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다.

SDK 결제 요청
import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
  PortOne.requestPayment({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    paymentId: `payment${Math.random().toString(36).slice(2)}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "CURRENCY_KRW",
    payMethod: "CARD",
  });
}

주요 파라미터

유의사항

공통

카드 결제

간편 결제

계좌이체

가상계좌 결제

휴대폰 소액결제

SDK 빌링키 발급 요청하기

빌링키 발급 요청 시에는 requestIssueBillingKey 함수를 호출해야 합니다. channelKey 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 한국결제네트웍스(KPN) 채널 사용을 명시해주세요.

한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다.

SDK 빌링키 발급 요청
import * as PortOne from "@portone/browser-sdk/v2";
function requestIssueBillingKey() {
  PortOne.requestIssueBillingKey({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    billingKeyMethod: "CARD",
    issueId: "test-issueId",
    issueName: "test-issueName",
    customer: {
      customerId: "uniqueCustomerId",
      fullName: "포트원",
    },
  });
}

주요 파라미터

유의사항

API 수기(키인) 결제 요청하기

수기(키인)로 결제하기 위해서는 POST /payments/${PAYMENT_ID_HERE}/instant API를 통해 결제를 요청해야 합니다.

API 수기(키인) 결제 요청
// ... 수기(키인) 결제
const issueResponse = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    paymentId: `payment${Math.random().toString(36).slice(2)}`,
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    orderName: "나이키 와플 트레이너 2 SD",
    amount: {
      total: 10000,
      taxFree: 3000,
    },
    currency: "KRW",
    customer: {
      name: {
        full: "홍길동",
      },
      phoneNumber: "010-1234-0000",
    },
    method: {
      virtualAccount: {
        bank: `SHINHAN`,
        expiry: {
          dueDate: `2024-11-12T00:00:00+09+00`, // 입금기한은 미래시간만 가능합니다.
        },
        cashReceipt: {
          type: `PERSONAL`,
          customerIdentityNumber: `010-1234-0000`,
        },
      },
    },
  },
});

주요 파라미터

유의사항

API 빌링키 발급 요청하기

빌링키를 발급하기 위해서는 POST /billing-keys API를 이용하여 빌링키 발급을 요청해야 합니다.

한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다.

API 빌링키 발급 요청
const issueResponse = await axios({
  url: "https://api.portone.io/billing-keys",
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      name: {
        full: "홍길동",
      },
      phoneNumber: "010-1234-0000",
    },
    method: {
      card: {
        credential: {
          number: "1111111111111111",
          expiryMonth: "01",
          expiryYear: "20",
          birthOrBusinessRegistrationNumber: "900101",
          passwordTwoDigits: "00",
        },
      },
    },
  },
});

주요 파라미터

유의사항

API 빌링키 단건 결제 요청하기

발급된 빌링키로 단건 결제를 진행하려면 POST /payments/${PAYMENT_ID_HERE}/billing-key API를 이용하여 결제를 요청하실 수 있습니다.

한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다.

API 빌링키 단건 결제
const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/billing-key`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
    orderName: "월간 이용권 정기결제",
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      phoneNumber: `010-1234-5678`,
      email: `test@test.com`,
    },
    amount: {
      total: 10000,
    },
    currency: "KRW",
    productCount: 1,
  },
});

주요 파라미터

API 빌링키 예약/반복 결제 요청하기

예약 결제를 진행하려면 POST /payments/${PAYMENT_ID_HERE}/schedule API를 이용하여 결제를 예약하실 수 있습니다.

한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다.

API 예약/반복 결제
const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/schedule`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    payment: {
      billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
      orderName: "월간 이용권 정기결제",
      customer: {
        id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      },
      amount: {
        total: 10000,
        taxFree: 3000,
      },
      currency: "KRW",
    },
    timeToPay: "2023-01-01 00:00:00", // 결제를 시도할 시각이며 미래 시각만 가능합니다.
  },
});

주요 파라미터

공통 유의사항