이지페이(KICC) 국내결제

채널 설정하기

• 결제대행사 채널 설정하기 페이지의 안내에 따라 채널을 설정합니다. V2 결제 모듈을 사용하시려면 이지페이(KICC) 신모듈로 연동하셔야 합니다.

가능한 결제수단

• 결제창 일반결제: 신용카드, 실시간 계좌이체, 가상계좌, 휴대폰 소액결제, 간편결제
• 결제창 빌링키 발급: 카드, 네이버페이
• API 빌링키 결제: 결제창에서 발급한 빌링키를 사용한 일반결제, 예약 결제, 반복 결제
• 위챗페이, 알리페이 플러스, 라인페이 등 해외 결제수단은 이지페이(KICC) 해외결제를 참고해 주세요.

SDK 결제 요청하기

결제하려면 requestPayment 함수를 호출합니다. channelKey에는 콘솔에서 채널을 연동할 때 생성된 이지페이(KICC) 채널 키를 입력해 주세요. 이 문서에서 안내하는 바이트 길이는 EUC-KR 인코딩을 기준으로 합니다.

이지페이(KICC) 카드 결제 요청 예시는 다음과 같습니다.

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-${crypto.randomUUID()}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "KRW",
    payMethod: "CARD",
  });
}

주요 파라미터

카드 결제 유의사항

무이자 할부

installment.freeInstallmentPlans에 카드사와 무이자 개월 수를 지정하면 무이자 할부가 적용됩니다. card.cardCompany로 카드사를 다이렉트 호출하는지에 따라 입력 방법이 다릅니다.

카드사 다이렉트 호출을 사용하지 않는 경우

• 무이자 할부나 카드사 포인트(card.useCardPoint)를 사용하려면 card.availableCards에 대상 카드사를 지정합니다.
• card.availableCards에 지정한 카드사별로 무이자 할부 개월 수를 card.installment.freeInstallmentPlans에 입력합니다.

카드사 다이렉트 호출을 사용하는 경우

• 할부 개월 수는 card.installment.monthOption에 한 개만 지정합니다.
• 무이자 할부는 card.installment.freeInstallmentPlans에 설정합니다. 카드사는 card.cardCompany에 지정한 카드사와 같아야 하며, 할부 개월 수는 card.installment.monthOption에 지정한 값과 같아야 합니다.

간편결제

• easyPay.installment.monthOption에 선택 가능한 할부 개월 수를 지정합니다. 간편결제창에서 할부 개월 수를 선택합니다.
• 무이자 할부는 easyPay.availableCards에 카드사를 지정하고, easyPay.installment.freeInstallmentPlans에 해당 카드사의 무이자 개월 수를 지정합니다.

카드사 포인트

card.useCardPoint를 true로 설정하려면 card.cardCompany 또는 card.availableCards에 카드사를 1곳 이상 지정해야 합니다. card.availableCards에 지정한 카드사에는 모두 포인트 사용 설정이 적용됩니다.

대상 카드사를 입력하지 않으면 결제창 호출 전에 오류가 반환됩니다.

결제창 빌링키 발급

빌링키를 발급하려면 requestIssueBillingKey 함수를 호출합니다. 이지페이(KICC)는 카드와 네이버페이 빌링키 발급을 지원합니다.

import * as PortOne from "@portone/browser-sdk/v2";

function requestIssueBillingKey() {
  PortOne.requestIssueBillingKey({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해 주세요.
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔의 결제 연동 화면에서 채널을 연동할 때 생성된 채널 키를 입력해 주세요.
    billingKeyMethod: "CARD",
    issueId: `issue-${crypto.randomUUID()}`,
    issueName: "정기결제 카드 등록",
  });
}

import * as PortOne from "@portone/browser-sdk/v2";

function requestIssueBillingKey() {
  PortOne.requestIssueBillingKey({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해 주세요.
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔의 결제 연동 화면에서 채널을 연동할 때 생성된 채널 키를 입력해 주세요.
    billingKeyMethod: "EASY_PAY",
    issueId: `issue-${crypto.randomUUID()}`,
    issueName: "네이버페이 정기결제 등록",
    easyPay: {
      easyPayProvider: "NAVERPAY",
      availablePayMethods: ["CARD"],
    },
  });
}

주요 파라미터

API 빌링키 결제 요청하기

발급된 빌링키로 결제하려면 POST /payments/{paymentId}/billing-key를 호출합니다. 예약 결제와 반복 결제는 POST /payments/{paymentId}/schedule을 이용합니다.

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", // 결제창으로 발급받은 빌링키
    orderName: "월간 이용권 정기결제",
    amount: {
      total: 10000,
    },
    currency: "KRW",
  },
});

주요 파라미터

API 지원 기능

이지페이(KICC)는 포트원 V2 API에서 다음 기능을 지원합니다.

• 카드와 네이버페이 빌링키 결제
• 예약 결제
• 빌링키 삭제
• 결제 취소
• 에스크로 배송 정보 등록
• 현금영수증 발급, 조회, 취소
• 가상계좌 말소

에스크로 API 유의사항

• 에스크로 배송 정보는 등록만 지원합니다. 배송 정보 수정과 조회 API는 지원하지 않습니다.

• 구매자에게 발송된 이지페이(KICC) 메일에서만 구매를 확정할 수 있습니다. 포트원의 구매 확정 API로는 처리할 수 없습니다.

• 배송 정보 등록 시 물류 회사(logistics.company)는 필수입니다. 송장 번호(logistics.invoiceNumber)는 30바이트 이내로 입력해야 합니다.

• 배송 정보를 등록하면 이지페이(KICC)가 결제 요청 시 입력한 customer.email로 물품 수령 확인 메일을 발송합니다.

• 지원하는 물류 회사는 다음과 같습니다.

  • CJ대한통운: CJ
  • 롯데글로벌로지스: LOTTE
  • 로젠택배: LOGEN
  • 동원로엑스: DONGWON
  • 우체국: POST
  • 한진택배: HANJIN
  • 기타: ETC

현금영수증 API 유의사항

• 포트원을 거치지 않고 결제한 건에도 현금영수증을 발급하거나 취소할 수 있습니다.

• 현금영수증 발급 시 다음 파라미터는 필수입니다.

  • amount.vat: 부가세 금액
  • customer.identityNumberType: 식별 정보 유형 (CARD, PHONE, BUSINESS)

• customer.identityNumber는 숫자만 사용하여 50자 이내로 입력해야 합니다.

• customer.email에 이메일 주소를 20자 이내로 입력해야 하며, 영문 대소문자와 숫자 외에는 @, ., _, -만 사용할 수 있습니다.

• paymentId는 영문 대소문자, 숫자, 하이픈(-), 밑줄(_)만 사용하여 40자 이내로 입력해야 합니다.

• customer.name은 20바이트까지, orderName은 50바이트까지만 전달됩니다.

결제 취소 API 유의사항

비동기 취소

가상계좌 입금 후 환불과 휴대폰 소액결제 익월 환불은 비동기 방식으로 처리됩니다. 이지페이(KICC)가 취소 요청을 접수한 뒤 실제 환불을 처리합니다. 휴대폰 소액결제 당월 환불과 그 외 결제수단의 취소는 실시간으로 처리됩니다.

• 응답의 status가 REQUESTED(취소 요청)로 반환되며, 이 시점에는 취소가 확정되지 않습니다. 응답만 보고 주문 상태를 취소로 변경하지 마세요.

• 환불 계좌(refundAccount)를 필수로 입력해야 합니다. 환불 금액은 요청일의 다음 영업일에 해당 계좌로 입금됩니다.

에스크로

• 에스크로 결제는 부분 취소할 수 없으며 전액 취소만 지원합니다.

• 다음 경우에는 결제 취소 API로 취소할 수 없으므로, 이지페이(KICC) 가맹점관리자에서 직접 취소해 주세요.

  • 구매를 확정한 경우
  • 계좌이체 에스크로의 배송정보를 등록한 경우