개발자센터

loadPaymentUI 요청 형식

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

loadPaymentUI 요청 데이터 정의

request: LoadPaymentUIRequest
uiType: PaymentUIType
"PAYPAL_SPB"
storeId: string

상점 아이디

포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔 > 연동 정보 우측 상단에서 확인할 수 있습니다.

paymentId: string

결제 ID

고객사에서 임의로 ID를 정합니다.

이미 결제 완료된 paymentId로 결제를 요청하는 경우 실패합니다.

orderName: string

주문명

나이스페이먼츠나이스페이먼츠

나이스페이먼츠의 경우 최대 40바이트까지 입력할 수 있으며, 사용 가능한 특수문자는 아래와 같습니다.

  • 사용 가능: _
  • 사용 불가: % & | $ - + = [ ]
  • 사용 가능하나 권장하지 않음: ( )
NHN KCPNHN KCP

NHN KCP에서는 최대 100바이트까지 입력할 수 있습니다.

스마트로스마트로

스마트로에서는 최대 40바이트까지 입력할 수 있습니다.

한국결제네트웍스한국결제네트웍스

한국결제네트웍스에서는 최대 256바이트까지 입력할 수 있습니다.

KG이니시스KG이니시스

KG이니시스에서는 최대 40바이트까지 입력할 수 있으며, 40바이트 초과시 37바이트에서 잘리고 "..."가 추가됩니다.

웰컴페이먼츠웰컴페이먼츠

웰컴페이먼츠에서는 최대 40바이트까지 입력할 수 있으며, 40바이트 초과시 37바이트에서 잘리고 "..."가 추가됩니다.

네이버페이네이버페이

네이버페이에서는 bypass.naverpay.productItems의 개수에 따라 주문명 뒤에 외 X개가 붙으므로, 주문명을 bypass.naverpay.productItems[0].name과 똑같이 입력하는 것이 권장됩니다.

하이픈하이픈

하이픈에서는 최대 1000바이트까지 입력할 수 있습니다.

totalAmount: number

결제 금액

결제 금액을 정수로 나타냅니다.

해외 통화의 경우 통화의 최소 단위(minor unit)를 기준으로 합니다. 예를 들어, USD의 최소 단위는 센트(0.01 USD)이므로, 6 USD의 경우 100배하여 600으로 입력합니다.

최소 단위는 ISO 4217에 표준화된 것을 기준으로 합니다.

  • KRW: 1배
  • USD: 100배
  • JPY: 1배
channelKey: string

채널 키

포트원에 등록된 결제 채널 중 하나를 지정합니다.

관리자 콘솔 > 연동 정보에서 채널 연동 후 채널 키를 확인할 수 있습니다.

채널 키와 채널 그룹 ID 중 하나를 지정해야 합니다.

taxFreeAmount?: number

면세 금액

미입력 시 0으로 취급됩니다.

vatAmount?: number

부가세 금액

미입력 시 과세 금액의 1/11로 자동 계산됩니다.

customer?: Customer
customerId?: string

구매자 ID

스마트로, KG이니시스 SBPS 일본결제에서 사용합니다.

토스페이먼츠와 스마트로의 빌링키 발급에서 사용합니다.

스마트로스마트로

스마트로에서는 20자 이내여야 합니다.

스마트로 간편결제에서 필수입니다. PINPAY 결제의 경우 고객별로 고유한 값이 필요합니다.

스마트로 빌링키 발급에서 필수입니다. 로마자, 숫자 사용 가능하며, 특수문자는 사용 불가능합니다.

KG이니시스KG이니시스

KG이니시스 SBPS 일본결제에서 필수입니다. 이 경우 30자 이내여야 합니다.

fullName?: string

구매자 전체 이름

fullName이 사용되는 PG에서 fullName이 없고 firstName과 lastName이 있는 경우 ${lastName} ${firstName}이 대신 사용됩니다.

나이스페이먼츠나이스페이먼츠

NICE페이먼츠에 전달됩니다. 최대 30바이트입니다. 알리페이 결제의 경우 필수입니다.

KG이니시스KG이니시스
웰컴페이먼츠웰컴페이먼츠

KG이니시스, 웰컴페이먼츠에서는 필수입니다. 최대 30바이트입니다.

NHN KCPNHN KCP

NHN KCP에 전달됩니다. 최대 30자입니다. 모바일에서 카드사 UI를 직접 호출할 경우 필수입니다.

스마트로스마트로

스마트로에서는 최대 30자입니다.

KSNETKSNET

KSNET에서는 필수입니다. 최대 50바이트입니다.

한국결제네트웍스한국결제네트웍스

한국결제네트웍스에 전달됩니다. 최대 100자입니다.

하이픈하이픈

하이픈에서는 필수입니다.

firstName?: string

구매자 성이 아닌 이름

페이팔에서 구매자 페이팔 계정 소유자의 이름을 지정합니다.

lastName?: string

구매자 성

페이팔에서 구매자 페이팔 계정 소유자의 성을 지정합니다.

phoneNumber?: string

구매자 휴대전화 번호

숫자만 입력합니다.

나이스페이먼츠나이스페이먼츠

NICE페이먼츠에 전달됩니다.

KG이니시스KG이니시스
웰컴페이먼츠웰컴페이먼츠

KG이니시스, 웰컴페이먼츠에서는 필수입니다.

NHN KCPNHN KCP

NHN KCP에 전달됩니다.

스마트로스마트로

스마트로에 전달됩니다.

email?: string

구매자 이메일 주소

올바른 형식의 이메일 주소여야 합니다.

나이스페이먼츠나이스페이먼츠

NICE페이먼츠에 전달됩니다.

KG이니시스KG이니시스
웰컴페이먼츠웰컴페이먼츠

KG이니시스, 웰컴페이먼츠에서는 필수입니다.

NHN KCPNHN KCP

NHN KCP에 전달됩니다. PC에서 카드사 UI를 직접 호출할 경우 필수입니다.

스마트로스마트로

스마트로에 전달됩니다. 최대 60자입니다.

address?: Address

구매자 주소

country?: Country

국가

ISO 3166-1 alpha-2 코드입니다.

addressLine1: string

주소 첫째 줄

addressLine2: string

주소 둘째 줄

city?: string

도시

province?: string

주, 도, 시

zipcode?: string

구매자 우편번호

gender?: Gender

구매자 성별

정보성 필드입니다.

"GENDER_MALE"

남성

"GENDER_FEMALE"

여성

"GENDER_OTHER"

기타

birthYear?: string

구매자 출생년도

"1990"과 같은 형식입니다.

KG이니시스 통합인증에서 flgFixedUser가 Y인 경우 필수입니다.

birthMonth?: string

구매자 출생월

"12", "07"과 같은 형식입니다.

KG이니시스 통합인증에서 flgFixedUser가 Y인 경우 필수입니다.

birthDay?: string

구매자 출생일

"25", "08"과 같은 형식입니다.

KG이니시스 통합인증에서 flgFixedUser가 Y인 경우 필수입니다.

firstNameKana?: string

구매자 일본어 성이 아닌 이름 후리가나(읽는 법)

KG이니시스 JPPG 일본 편의점 결제에서 필수입니다. 최대 20바이트입니다.

lastNameKana?: string

구매자 일본어 성 후리가나(읽는 법)

KG이니시스 JPPG 일본 편의점 결제에서 필수입니다. 최대 20바이트입니다.

redirectUrl?: string

리디렉션 방식에서 결제 완료 후 이동할 URL

결제사 페이지로 이동하여 진행하는 리디렉션 방식의 경우 필수로 설정해야 합니다. 대부분의 모바일 환경이 리디렉션 방식에 해당됩니다.

noticeUrls?: Array<string>

웹훅 URL

confirmUrl?: string

Confirm URL

appScheme?: string

앱 URL Scheme

isEscrow?: boolean

에스크로 결제 여부

products?: Array<Product>

구매 상품 상세 정보

id: string

상품 ID

name: string

상품명

code?: string

상품 코드

  • 토스페이먼츠의 경우 필수로 입력해주세요.
amount: number

상품 단위 가격

결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.

  • 1000 만큼 원화(KRW) 결제를 하는 경우, scale factor가 0이기 때문에 1000 * (10의 0승) = 1000을 전달해야 합니다.
  • 1.50 만큼 달러(USD) 결제를 하는 경우, scale factor가 2이기 때문에 1.50 * (10의 2승) = 150을 전달해야 합니다.

이렇게 전달 된 값은 실제로 PG사에 결제를 요청할때 currency에 따라 올바른 값으로 변환되기 때문에 반드시 currency값을 필수로 입력해야 합니다.

quantity: number

상품 수량

tag?: string

상품 태그

link?: string

상품 판매 URL

isCulturalExpense?: boolean

문화비 지출 여부

currency: Currency

화폐

ISO 4217 화폐 코드

대한민국 원, 일본 엔이 아닌 화폐를 사용할 때에는 금액을 minor unit 단위로 입력해야 함에 유의하세요.

locale?: Locale

UI 언어

KG이니시스, 스마트로, KSNET, 웰컴페이먼츠 (PC), 한국결제네트웍스, 엑심베이에서 설정 가능하며, PG마다 지원하는 언어 목록은 차이가 있습니다.

"KO_KR"

한국어

  • KG이니시스
  • 스마트로
  • KSNET
  • 웰컴페이먼츠 (PC)
  • 한국결제네트웍스
  • 엑심베이
"EN_US"

영어

  • KG이니시스
  • 스마트로
  • KSNET
  • 웰컴페이먼츠 (PC)
  • 한국결제네트웍스
  • 엑심베이
"ZH_CN"

중국어 (중국 본토)

  • KG이니시스 (PC)
  • 웰컴페이먼츠 (PC)
  • 엑심베이
"ZH_TW"

중국어 (대만)

  • 엑심베이
"JA_JP"

일본어

  • 엑심베이
"RU_RU"

러시아어

  • 엑심베이
"TH_TH"

타이어

  • 엑심베이
"VI_VN"

베트남어

  • 엑심베이
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?: OfferPeriodRange

기간 범위

OfferPeriodRangeFrom

시작 시점만 있는 기간 범위

from: string

시작 시점

OfferPeriodRangeTo

종료 지점만 있는 기간 범위

to: string

종료 지점

OfferPeriodRangeFromTo

시작 지점과 종료 지점이 모두 있는 기간 범위

from: string

시작 시점

to: string

종료 지점

interval?: string

제공 주기

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

productType?: ProductType

상품 유형

"PRODUCT_TYPE_REAL"

실물

"PRODUCT_TYPE_DIGITAL"

디지털

bypass?: LoadPaymentUIBypass
paypal_v2?: PaypalV2LoadPaymentUIBypass

Paypal bypass 파라미터

style?: PaypalV2Style

SPB 버튼 렌더링에 필요한 파라미터

color?: PaypalV2StyleColor

버튼 색상

"gold"
"blue"
"silver"
"white"
"black"
height?: number

버튼 높이

label?: PaypalV2StyleLabel

버튼 라벨

"paypal"
"checkout"
"buynow"
"pay"
"installment"
"subscribe"
"donate"
layout?: PaypalV2StyleLayout

버튼 렌더링 방향

"vertical"
"horizontal"
shape?: PaypalV2StyleShape

버튼 모양

"rect"
"pill"
period?: string

label이 installment일 때 할부 결제 되는 월

tagline?: boolean

버튼 하위에 문구 노출 여부

enable-funding?: string

허용할 결제 수단 (예: "card, credit, bancontact")

disable-funding?: string

차단할 결제 수단 (예: "venmo, mercadopago")

purchase_units?: Array<PaypalV2PurchaseUnit>

create order API 호출에 필요한 파라미터

shipping?: PaypalV2PurchaseUnitShipping

구매 상품 정보

address?: PaypalV2PurchaseUnitShippingAddress

수령지 정보

address_line_1: string

수령지 주소. 미 입력 시 입력된 주소로 override되지 않음

address_line_2?: string
admin_area_1?: string
admin_area_2: string

필수 입력. 미 입력 시 create order 실패

postal_code?: string
country_code: Country

국가 코드

payer?: PaypalV2Payer
tax_info?: PaypalV2PayerTaxInfo

구매자 정보

tax_id: string

구매자 세금 정보 (브라질 구매자의 경우 필수 입력)

tax_id_type: string
address?: PaypalV2PayerAddress
address_line_1?: string

구매자 주소지 정보

address_line_2?: string
admin_area_1?: string
admin_area_2?: string
postal_code?: string

우편번호

country_code: Country

국가 코드

additional_data?: Array<PaypalV2AdditionalData>

STC 파라미터

key: string
value: string
country?: Country

국가

ISO 3166-1 alpha-2 코드입니다.

promotionGroupId?: string

프로모션 그룹 ID

promotionIds?: Array<string>

프로모션 ID 목록