개발자센터

requestIssueBillingKeyAndPay 요청 형식

requestIssueBillingKeyAndPay 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다.

아래의 경우 정책상 빌링키 발급과 초회 결제가 함께 일어나야 하므로 이용하는 함수입니다.

  • KG이니시스 휴대폰 결제
  • 웰컴페이먼츠 휴대폰 결제

위에 해당하지 않는 경우에는 requestIssueBillingKey 함수로 빌링키를 발급한 뒤, 별도로 결제를 호출해 주시기 바랍니다.

requestIssueBillingKeyAndPay 요청 데이터 정의

request: IssueBillingKeyAndPayRequest
storeId: string

스토어 아이디

  • 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다.
paymentId: string

주문 번호

orderName: string

주문명

totalAmount: number

결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor

예) $1.50 -> 150)

currency: Currency

결제 통화 코드

channelKey?: string

채널 키

콘솔에서 채널 연동 시 생성된 채널 키입니다.

billingKeyAndPayMethod: BillingKeyAndPayMethod

빌링키 발급 및 결제 수단

taxFreeAmount?: number

면세 금액

  • 결제 금액 중 면세금액에 해당하는 금액을 입력합니다.
  • 미입력 시 0으로 취급됩니다.
  • 결제 금액과 동일하게 통화별 scale factor가 적용된 금액으로 전달해주세요.
vatAmount?: number

부가세

  • 부가세 금액을 입력합니다.
  • 미입력 시 과세 금액의 1/11 로 자동 계산됩니다.
  • 결제 금액과 동일하게 통화별 scale factor가 적용된 금액으로 전달해주세요.
customer?: Customer
customerId?: string

구매자 고유 ID

fullName?: string

구매자 전체 이름

fullName과 firstName / lastName이 모두 입력된 경우 fullName으로 기록됩니다.

firstName?: string

구매자 이름

firstName을 입력하는 경우 lastName도 필수로 입력해야 합니다. fullName이 없고, firstName과 lastName이 존재하는 경우 {firstName} {lastName}으로 저장됩니다.

lastName?: string

구매자 성

lastName을 입력하는 경우 firstName도 필수로 입력해야 합니다.

phoneNumber?: string

구매자 연락처

email?: string

구매자 이메일 주소

유효한 이메일 주소를 입력해주세요.

address?: Address

주소 정보

country?: Country

국가

addressLine1: string

일반주소

addressLine2: string

상세주소

city?: string

도시

province?: string

주, 도, 시

zipcode?: string

구매자 우편번호

gender?: Gender

구매자 성별

birthYear?: string

구매자 출생년도

ex. "1990" 같은 형식으로 입력해주세요.

birthMonth?: string

구매자 출생월

ex. "12", "07" 같은 형식으로 입력해주세요.

birthDay?: string

구매자 출생일

ex. "25", "08" 같은 형식으로 입력해주세요.

firstNameKana?: string

구매자 이름 후리가나

일본어 읽는 법 표기

lastNameKana?: string

구매자 성 후리가나

일본어 읽는 법 표기

windowType?: WindowTypes

환경 별 제공되는 결제/본인인증 창 유형

  • PG사에 따라 가능한 창 유형이 다릅니다.
  • 전달되지 않았을 때 결정되는 기본 창이 다릅니다.
  • 미입력 시, 해당 PG사의 기본 창 방식을 따릅니다.
pc?: WindowType
mobile?: WindowType
redirectUrl?: string

리디렉션 방식에서 프로세스 완료 후 이동될 고객사 URL

  • 결제/본인인증 창이 새로운 창으로 리다이렉트 되어 프로세스가 진행되는 방식인 경우 필수 설정 항목 입니다.
  • 대부분의 모바일 환경에서 창 호출시 필수 항목입니다.
  • 리다이렉트 환경에서 해당 필드 누락시 에러가 발생합니다.
noticeUrls?: Array<string>

웹훅 URL

locale?: Locale

결제창 언어 (지원되지 않은 일부 PG사 존재)

isCulturalExpense?: boolean

문화비 지출 여부

customData?: json

결제 정보와 함께 관리하고 싶은 고객사 커스텀 JSON 데이터

offerPeriod?: OfferPeriod

서비스 제공 기간

range와 interval 중 하나를 입력해주세요.

  • range: 제공 기간 범위
  • interval: 제공 기간 주기

예1) 2023년 1월 1일 00시 00분 00초(KST) ~

range: {
 from: '2023-01-01T00:00:00+09:00'
}

예2) ~ 2023년 1월 1일 00시 00분 00초(KST)

range: {
 to: '2023-01-01T00:00:00+09:00'
}

예3) 2023년 1월 1일 00시 00분 00초(KST) ~ 2023년 12월 31일 23시 59분 59초(KST)

range: {
 from: '2023-12-31T23:59:59+09:00'
 to: '2023-01-01T00:00:00+09:00'
}

예4) 30일 주기 interval: '30d'

예5) 6개월 주기 interval: '6m'

예6) 1년 주기 interval: '1y'

range?: { from } | { to } | { from, to }

기간 범위

{ from }
from: string

시작 시점

{ to }
to: string

종료 지점

{ from, to }
from: string

시작 시점

to: string

종료 지점

interval?: string

제공 주기

제공 주기 (${number}d | ${number}m | ${number}y 형태로 입력할 수 있습니다.)

appScheme?: string

앱 URL Scheme

productType?: ProductType

상품 유형

storeDetails?: StoreDetails

상점 정보

  • KSNET 카카오페이의 경우 필수 입력
  • (신)나이스페이의 경우 매출 전표에 표기 할 용도로 선택 입력
  • 이니시스 일본결제의 경우 JPPG(gmoPayment) 결제의 상점정보로 사용되거나 편의점 결제 시 영수증 표시 정보로 사용됨.
ceoFullName?: string

상점 대표자 이름

phoneNumber?: string

상점 연락처

address?: string

상점 주소

zipcode?: string

상점 우편번호

email?: string

상점 이메일

businessName?: string

상점 사업자 명

businessRegistrationNumber?: string

상점 사업자 등록 번호

storeName?: string

상점명

storeNameShort?: string

상점명 약어

storeNameEn?: string

상점명 영문

storeNameKana?: string

상점명 후리카나 (일본어 읽는법 표기)

openingHours?: { open, close }

상점 영업시간 (HH:mm)

open?: string

영업 시작 시간

close?: string

영업 종료 시간

contactName?: string

상점 연락처 정보 이름

ex: 문의창구, 연락처, 지원창구

country?: Country

국가

bypass?: IssueBillingKeyAndPayBypass
welcome?: WelcomeIssueBillingKeyAndPayBypass
acceptmethod?: Array<string>

acceptmethod 파라미터는 휴대폰 소액결제 시 기본 선택할 통신사를 설정하며, 추가로 buyer_tel 값의 수정 가능 여부를 지정할 수 있습니다.

통신사 기본 선택 설정:

  • 특정 통신사를 기본 선택하려면 hppdefaultcorp(통신사코드) 형식으로 전달합니다.
  • 예시: KT를 기본 선택 → hppdefaultcorp(KTF)

가능한 통신사 코드:

  • SKT: SK 텔레콤
  • KTF: KT
  • LGT: LG 유플러스
  • MVNO: 알뜰폰 전체
  • CJH: 알뜰폰 CJ 헬로 모바일
  • KCT: 알뜰폰 티플러스
  • SKL: 알뜰폰 SK 세븐 모바일

휴대폰 소액결제창에 자동 입력되는 buyer_tel 수정 가능 여부 설정:

  • 수정 불가능으로 설정하려면 hppnofix(Y)를 전달합니다.
  • 수정 가능으로 설정하려면 hppnofix(N)를 전달합니다. (기본값)
P_RESERVED?: Array<string>

P_RESERVED 파라미터는 휴대폰 소액결제 시 기본 선택할 통신사를 설정하며, 추가로 buyer_tel 값의 수정 가능 여부를 지정할 수 있습니다.

통신사 기본 선택 설정:

  • 특정 통신사를 기본 선택하려면 hpp_default_corp=통신사코드 형식으로 전달합니다.
  • 예시: KT를 기본 선택 → hpp_default_corp=KTF

가능한 통신사 코드:

  • SKT: SK 텔레콤
  • KTF: KT
  • LGT: LG 유플러스
  • MVNO: 알뜰폰 전체
  • CJH: 알뜰폰 CJ 헬로 모바일
  • KCT: 알뜰폰 티플러스
  • SKL: 알뜰폰 SK 세븐 모바일

휴대폰 소액결제창에 자동 입력되는 buyer_tel 수정 가능 여부 설정:

  • 수정 불가능으로 설정하려면 hpp_nofix=Y를 전달합니다.
  • 수정 가능으로 설정하려면 hpp_nofix=N를 전달합니다. (기본값)
popup?: Popup

결제창이 팝업 방식일 경우 결제창에 적용할 속성

center?: boolean

true로 설정하면 결제창이 브라우저 화면의 정중앙에 표시됩니다.

mobile: { carrier, avaliableCarriers }

billingKeyAndPayMethod가 MOBILE인 경우에만 허용됩니다.