카카오페이

카카오페이 연동 방법을 안내합니다.

이 문서는 V1(구 아임포트) 연동 고객사 대상입니다. 신규 연동의 경우 V2 버전 사용을 권장합니다.

1. 카카오페이 채널 설정하기

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

2.결제 요청하기

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

Javascript SDK
IMP.request_pay(
  {
    channelKey: "{콘솔 내 연동 정보의 채널키}",
    pay_method: "card", // 생략가
    merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호
    name: "주문명:결제테스트",
    amount: 1004,
    buyer_email: "test@portone.io",
    buyer_name: "구매자이름",
    buyer_tel: "010-1234-5678",
    buyer_addr: "서울특별시 강남구 삼성동",
    buyer_postcode: "123-456",
    m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}",
  },
  function (rsp) {
    // callback 로직
    /* ...중략... */
  },
);

주요 파라미터 설명

channelKey: string

채널키

결제를 진행할 채널을 지정합니다.

포트원 콘솔 내 [결제 연동] - [연동 정보] - [채널 관리] 에서 확인 가능합니다.

(최신 JavaScript SDK 버전부터 사용 가능합니다.)

pg(deprecated)?: string

PG사 구분코드

kakaopay 로 지정하면 됩니다.

pg 파라미터는 지원 중단 예정입니다.

JS SDK를 가장 최신 버전으로 업그레이드 후 channelKey 파라미터로 채널 설정(PG사 구분)을 대체해주세요.

pay_method?: string

결제수단 구분코드

생략가능

(호출 시 선택된 값은 무시되며 카카오페이 앱에서 신용카드와 카카오머니 중 선택한 옵션으로 설정됩니다.)

merchant_uid: string

주문번호

매번 고유하게 채번되어야 합니다.

name: string

주문명

amount: number

결제금액

string 이 아닌점에 유의하세요

buyer_name?: string

구매자 이름

buyer_email?: string

구매자 이메일

buyer_tel?: string

구매자 연락처

buyer_addr?: string

구매자 주소

buyer_postcode?: string

구매자 우편번호

tax_free?: number

면세금액

m_redirect_url?: string

모바일 결제 후 리디렉션 될 URL

app_scheme?: string

모바일 앱 URL scheme (모바일 전용, iOS만 지원)

카카오페이 정책에 따라 iOS에서만 사용 가능합니다.

notice_url?: string | string[]

웹훅 수신 URL

confirm_url?: string

Confirm process URL

custom_data?: object

가맹점 커스텀 데이터

customer_id?: string

구매자 고유 ID

display?: object

카드 할부 설정

card_quota?: number[]

할부 개월수

단일 값만 지정 가능합니다. 지정 시 해당 개월수로 고정됩니다.

card?: object

카드 필터링

detail?: object[]

사용 가능한 카드사 목록

card_code?: string

카드사 코드

enabled?: boolean

활성화 여부

kakaopayMobileAsPC?: boolean

모바일에서 PC URL 사용 여부 (모바일 전용)

true 설정 시 모바일 환경에서 PC용 결제 URL을 사용합니다.

bypass?: object

PG사 전용 파라미터

kakaopay?: object

카카오페이 전용 파라미터

payment_method_type?: string

사용 허용할 결제수단 지정

CARD: 카드결제만 허용
MONEY: 포인트결제만 허용

미입력 시 사용 가능한 전체 결제수단 허용

custom_message?: string

카카오페이 결제 UI에 표시되는 커스텀 메시지

인증결제창 호출 파라미터에서 customer_uid 값을 추가하면 정기결제창을 호출할 수 있습니다.

amount 금액

카카오페이 간편결제는 빌링키 발급시 amount 파라미터에 금액이 설정되는 경우 실 결제와 동시에 빌링키가 발급됩니다.

실결제를 원하지 않은 경우 amount 금액을 0원으로 설정합니다.

Javascript SDK
IMP.request_pay(
  {
    channelKey: "{콘솔 내 연동 정보의 채널키}",
    merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호
    name: "최초인증결제",
    amount: 0, // 결제창에 표시될 금액. 실제 승인이 이뤄지지는 않습니다.
    customer_uid: "your-customer-unique-id", // 필수 입력.
    buyer_email: "test@portone.io",
    buyer_name: "포트원",
    buyer_tel: "02-1234-1234",
    m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}",
  },
  function (rsp) {
    if (rsp.success) {
      alert("빌링키 발급 성공");
    } else {
      alert("빌링키 발급 실패");
    }
  },
);