결제요청 파라미터

결제요청 파라미터를 확인할 수 있습니다.

결제요청 파라미터 정의

`storeId` * string

스토어 아이디

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

`paymentId` * string

고객사 주문 고유 번호

고객사가 채번하는 주문 고유 번호입니다.
이미 승인 완료 된 paymentId로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다.

`orderName` * string

주문명

주문명으로 고객사에서 자유롭게 입력합니다.

`totalAmount` * 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값을 필수로 입력해야 합니다.

`currency` * string

결제 통화

원화 결제 시 KRW로 입력해주세요.

`payMethod` * string

결제수단 구분코드

PG사별 지원되는 결제수단이 모두 상이합니다.

각 PG사별 결제 연동 가이드를 참고하세요

`channelKey` string

채널 키

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

pgProvider 파라미터가 없는 경우에 필수로 존재해야 합니다. 두 파라미터가 모두 존재하는 경우 channelKey을 적용하니 둘 중 하나만 제공해주세요.

`pgProvider` string (Deprecated 예정)

PG사 구분코드 (2024년 09월 30일부터 사용이 불가능한 파라미터 입니다.)

channelKey 파라미터가 없는 경우에 필수로 존재해야 합니다.

가능한 PG사 코드는 아래를 참고해주세요.

`isTestChannel` boolean (Deprecated 예정)

테스트 채널 정보로 결제할지 여부 (2024년 09월 30일부터 사용이 불가능한 파라미터 입니다.)

미입력 시 기본값은 false입니다.

선택하신 채널이 테스트 채널이 아닌 경우 에러가 발생합니다.

`taxFreeAmount` number

면세 금액

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

`vatAmount` number

부가세

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

`customer` * object

고객 정보

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 object

구매자 주소
- country string
  
  국가
- addressLine1 * string
  
  일반주소
- addressLine2 * string
  
  상세주소
- city string
  
  도시
- province string
  
  주, 도, 시
zipcode string

구매자 우편번호
gender string

구매자 성별

MALE, FEMALE, OTHER 중 하나를 입력해주세요.
birthYear string

구매자 출생년도

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

구매자 출생월

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

구매자 출생일

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

`windowType` object

결제 환경 별 제공되는 결제창 유형

PG사에 따라 가능한 결제창이 다릅니다.
전달되지 않았을 때 결정되는 기본 결제창이 다릅니다.
미입력 시, 해당 PG사의 기본 결제창 방식을 따릅니다.

pc string

PC에서의 결제창 유형 IFRAME, REDIRECTION, POPUP 중 하나를 입력해주세요.
mobile string

모바일에서의 결제창 유형 IFRAME, REDIRECTION, POPUP 중 하나를 입력해주세요.

`redirectUrl` string

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

결제창이 새로운 창으로 리다이렉트 되어 결제가 진행되는 결제 방식인 경우 필수 설정 항목 입니다.
대부분의 모바일 결제환경에서 결제창 호출시 필수 항목입니다.
리다이렉트 환경에서 해당 필드 누락시 에러가 발생합니다.

`noticeUrls` string[]

웹훅(Webhook) 수신 주소

유효한 형식의 문자열을 입력해주세요.

포트원 관리자 콘솔에 설정한 웹훅 주소 대신 사용할 웹훅 주소를 결제시마다 설정할 수 있습니다.
해당 값 설정시 관리자 콘솔에 설정한 주소로는 웹훅발송이 되지 않는점 유의하시기 바랍니다.

`confirmUrl` string

최종 결제 승인 요청 여부 확인 URL

유효한 URL 형식의 문자열을 입력해주세요.

confirm_process 사용 시 고객사 endpoint url 설정

기술지원 메일로 별도 요청이 필요합니다. (tech.support@portone.io)

`appScheme` string

모바일 결제 후 고객사 앱으로 복귀를 위한 URL scheme

WebView 환경 결제시 필수설정 항목 입니다.
ISP/앱카드 앱에서 결제정보인증 후 기존 앱으로 복귀할 때 사용합니다.

`isEscrow` boolean

에스크로 결제 여부

미입력 시 기본값: false

에스크로 설정은 PG사와 협의 이후 진행되어야 하는점 주의하세요

`products` object[]

구매 상품 상세 정보

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

상품 태그

`isCulturalExpense` boolean

문화비 지출 여부

도서, 공연, 박물관 등 문화비 지출 여부

`locale` string

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

`customData` object

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

`bypass` oneof object

PG사 결제창 호출 시 PG사로 그대로 bypass할 값들의 모음

tosspayments object

토스페이먼츠 bypass 파라미터
- discountCode string
  
  토스페이먼츠 <-> 고객사 계약에 따라 프로모션 적용이 가능한 코드
- useInternationalCardOnly boolean
  
  해외 카드로만 결제가 가능하도록 할 지 여부
kakaopay object

카카오페이 bypass 파라미터
- custom_message string
  
  카카오페이 결제창에 띄워줄 사용자 정의 문구
smartro_v2 object

스마트로 V2 bypass 파라미터
- GoodsCnt number
  
  결제 상품 품목 개수
- SkinColor string
  
  UI 스타일 (기본값: "RED")
  
  "RED", "GREEN", "BLUE", "PURPLE" 중 하나의 값으로 입력해주세요.
- OpenType string
  
  해외 카드만 결제를 허용할지 여부(기본값: "KR")
  
  "KR", "EN" 중 하나의 값으로 입력해주세요.
naverpay object

네이버페이 bypass 파라미터
- useCfmYmdt string
  
  이용완료일 (YYYYMMDD)
- productItems object[]
  
  상품 정보
  - categoryType * string
    
    결제 상품 유형
  - categoryId * string
    
    결제 상품 분류
  - uid * string
    
    결제 상품 식별값
  - name * string
    
    상품명
  - payReferrer string
    
    결제 상품 유입경로
  - startDate string
    
    시작일(YYYYMMDD)
  - endDate string
    
    종료일(YYYYMMDD)
  - sellerId string
    
    하위 판매자 식별키
  - count * string
    
    결제 상품 개수
- deliveryFee number
  
  배송비
nice_v2 object

(신)나이스페이먼츠 bypass 파라미터
- LogoImage string
  
  결제창 로고 이미지 URL
- NPDisableScroll string
  
  결제창 스크롤 미사용 여부 (PC Only, Y: 미사용 / N(default): 사용)
- SkinType string
  
  결제창 스킨 색상 설정
  
  "red", "green", "purple", "gray", "dark" 중 하나의 값으로 입력해주세요.
- UserCI string
  
  문화 상품권 결제시 결제 고객 사용자 인증 CI 정보. 아이디/비밀번호 외 추가로 CI 인증이 필요한 경우 사용.
- MallUserID string
  
  상점 사용자 아이디. 문화 상품권 결제시 경우 필수 입력
- DirectCouponYN string
  
  신용카드 쿠폰 자동 적용 여부 (Y: 사전 등록된 선 할인 쿠폰을 자동 적용 / N: 쿠폰 미적용(기본값))
- DirectShowOpt string
  
  다이렉트 호출 결제 수단 (BANK: 계좌이체/CELLPHONE: 휴대폰 소액결제)
- CardShowOpt string
  
  카드사 별 호출 방식
  
  형식) 카드코드:노출유형|카드코드:노출유형
  
  예시) 08:3|02:3 → 롯데카드와 국민카드 선택시 앱 카드 직접 호출 방식으로 렌더링
  - 노출 유형: 1(안심클릭), 2(간편결제), 3(앱 카드 직접 호출)
  - 카드 코드: 02(국민), 04(삼성), 06(신한), 07(현대), 08(롯데), 12(NH), 15(우리)만 가능
- PaycoClientId string
  
  페이코 계정 자동 로그인 기능 사용하기 위해 페이코에서 고객사에 발급한 ClientId
- PaycoAccessToken string
  
  페이코 계정 자동 로그인 기능 사용을 위한 접속 토큰
- SamsungPayType string
  
  삼성페이 고객사 유형 (01: 삼성페이 內 쇼핑 / 99: 기타 (기본값))
inicis_v2 object

이니시스 bypass 파라미터

이니시스는 PC 결제 모듈과 모바일 결제 모듈이 분리되어 있기 때문에 bypass 파라미터 또한 PC용과 모바일용이 분리되어 있습니다.

PC용 파라미터
- logo_url string
  
  결제창에 삽입할 메인 로고 url
  
  결제창 중앙 상단에 표시됩니다. 이미지 권장 사이즈는 89*18 입니다.
- logo_2nd string
  
  결제창에 삽입할 서브 로고 url
  
  결제창 우측 상단에 표시됩니다. 이미지 권장 사이즈는 64*13 입니다.
- parentemail string
  
  보호자 이메일 주소
  
  14세 미만 고객의 경우 필수 입력입니다. "@", "." 외의 특수문자는 입력 불가합니다.
- Ini_SSGPAY_MDN string
  
  SSGPAY 결제요청 시 PUSH 전송 휴대폰번호
  
  - 없이 숫자만 허용합니다.
- acceptmethod string[]
  
  추가 옵션
  
  아래 string 중 원하는 옵션들을 골라 array 형태로 입력합니다.
  - SKIN(${string}) string
    
    결제창 색상
    
    string 부분에는 #으로 시작하는 여섯자리 Hex 값을 입력합니다. (ex. SKIN(#C1272C))
  - below1000 string
    
    (카드결제 & 간편결제 시) 1000원 미만 결제 허용 옵션
  - ocb string
    
    (카드결제 시) 카드 메인화면에 OCB 적립을 위한 카드번호 창 표시옵션 (별도 계약시 이용 가능)
  - paypopup string
    
    (카드결제 시) 안심클릭계열 신용카드 POPUP 형태 표시옵션
  - hidebar string
    
    (카드결제 시) 프로그레스바 미노출 옵션
  - noeasypay string
    
    (카드결제 시) 간편결제 미노출 옵션
  - slimquota(${string}) string
    
    부분 무이자 설정 (별도 계약시 이용 가능)
    
    string 부분에는 코드-개월:개월^코드-개월:개월 와 같은 형식으로 입력합니다. (ex. slimquota(11-2:3^34-2:3)) 카드사 코드는 이니시스 통합 코드 페이지에서 "결제요청 시 카드코드" 섹션을 참고하시기 바랍니다.
  - mallpoint(${string}) string
    
    몰포인트 (별도 계약시 이용 가능)
    
    string 부분에는 카드코드:카드코드 와 같은 형식으로 입력합니다. (ex. mallpoint(11:34)) 카드사 코드는 이니시스 통합 코드 페이지에서 "결제요청 시 카드코드" 섹션을 참고하시기 바랍니다.
모바일용 파라미터
- P_CARD_OPTION string
  
  신용카드 우선선택 옵션
  
  설정한 카드코드에 해당하는 카드가 선택된 채로 Display 됩니다. selcode=카드코드 형식으로 입력합니다. (ex. selcode=14)
- P_MNAME string
  
  가맹점 이름
- P_RESERVED string[]
  
  추가 옵션
  
  아래 string 중 원하는 옵션들을 골라 array 형태로 입력합니다.
  - below1000=Y string
    
    (카드결제 & 간편결제 시) 1000원 미만 결제 허용 옵션
  - noeasypay=Y string
    
    (카드결제 시) 간편결제 미노출 옵션
  - global_visa3d=Y string
    
    해외카드 노출 옵션
  - apprun_check=Y string
    
    (android의 경우) custom url scheme 대신 intent schema(intent://) 호출
kpn object

KPN bypass 파라미터
- **CardSelect enum[]
  
  일부 렌더링할 결제방식 목록 특정 카드사로 구별되지 않는 결제수단을 지정할 때 사용합니다.
  - 해외카드 (VISA + MASTER + JCB) : GLOBAL
  - 구인증 : LEGACY_AUTH
  - 키인 : KEY_IN

`country` string

결제 국가

`productType` string

상품 유형

"PRODUCT_TYPE_REAL", "PRODUCT_TYPE_DIGITAL" 중 하나의 값을 입력해주세요.

`offerPeriod` string

서비스 제공 기간

range(기간 범위)와 interval(제공 주기) 중 하나를 입력해주세요.

range object

기간 범위
- from string
  
  시작 시점
- to string
  
  종료 시점
interval string

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

`storeDetails` object

상점 정보

ceoFullName string

상점 대표자 이름
phoneNumber string

상점 연락처
address string

상점 주소
zipcode string

상점 우편번호

`card` object

payMethod가 CARD인 경우에만 허용됩니다.

카드 정보

카드 결제 시, 카드 결제에 대한 세부 정보

cardCompany string

카드사 다이렉트 호출 시 필요한 카드사 식별 값
availableCards string[]

일부 카드사만 노출 설정

일부 카드사만을 선택 가능하게 하고 싶은 경우 사용하는 옵션입니다. 상단의 카드사 식별 값 항목을 참고해주세요.
useFreeInterestFromMall boolean

상점분담 무이자 활성화 여부
installment object

할부 설정
- freeInstallmentPlans object[]
  
  무이자 할부 설정
  
  고객사가 부담하는 무이자 할부 설정입니다.
  - cardCompany * string
    
    무이자 할부를 제공하는 카드사 식별 값
    
    상단의 카드사 식별 값 항목을 참고해주세요.
  - months * number[]
    
    무이자 할부를 제공하는 개월 수
- monthOption object
  
  할부 개월 수 설정
  
  할부 결제 시 할부 개월 수를 설정할 수 있습니다.
  
  fixedMonth와 availableMonthList 중 하나만 제공해주세요.
  - fixedMonth * number
    
    구매자가 선택할 수 없도록 고정된 할부 개월수
    
    구매자가 할부 개월 수를 선택할 수 있도록 하려면 availableMonthList를 사용해주세요.
  - availableMonthList * number[]
    
    구매자가 선택할 수 있는 할부 개월수 리스트
useCardPoint boolean

카드사 포인트 사용 여부
useAppCardOnly boolean

앱 카드만 허용할지 여부

`virtualAccount` object

payMethod가 VIRTUAL_ACCOUNT인 경우에만 허용됩니다.

가상계좌 정보

가상계좌 발급시 가상계좌 상세 옵션

cashReceiptType string

결제창에서 발급 가능한 현금영수증 발급 유형(소득공제용, 지출증빙용, 미발행)
customerIdentifier string

현금영수증 발행 대상 식별 정보
fixedOption oneof object

고정식 가상계좌 설정
- pgAccountId string
  
  PG사로부터 사전에 가상계좌에 대한 ID를 발급받아 사용하는 경우의 가상계좌 ID
- accountNumber string
  
  고정식으로 사용할 가상계좌 번호
bankCode string

가상계좌 은행 다이렉트 호출시 은행 코드
accountExpiry object

가상계좌 입금 만료기한

validHours와 dueDate 중 하나만 입력해주세요.
- validHours number
  
  가상계좌 입금 유효 시간
  
  가상계좌 입금 유효 시간
  
  예) 3을 전달하면 지금으로부터 3시간 후가 만료 기한으로 지정 됨
- dueDate string
  
  가상계좌 입금 유효 시각
  - YYYYMMDD
  - YYYYMMDDHHmmss
  - YYYY-MM-DD
  - YYYY-MM-DD HH:mm:ss

`transfer` object

payMethod가 TRANSFER인 경우에만 허용됩니다.

계좌이체 결제시 계좌이체 상세 옵션

가상계좌 발급시 가상계좌 상세 옵션

cashReceiptType string

결제창에서 발급 가능한 현금영수증 발급 유형(소득공제용, 지출증빙용, 미발행)
customerIdentifier string

현금영수증 발행 대상 식별 정보
bankCode string

계좌이체 은행 다이렉트 호출시 은행 코드

`mobile` object

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

휴대폰 소액결제 정보

휴대폰 소액결제시 휴대폰 소액결제 상세 옵션

carrier string

휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값
availableCarriers string[]

일부 통신사만 노출 설정 일부 통신사만을 선택 가능하게 하고 싶은 경우 사용하는 옵션입니다. 상단의 통신사 구분 값 항목을 참고해주세요.

`giftCertificate` object

payMethod가 GIFT_CERTIFICATE인 경우에만 허용됩니다.

상품권 정보

상품권 결제시 상품권 결제 상세 옵션

giftCertificateType string

상품권 결제시, 상품권을 특정할 수 있는 값

`easyPay` object

payMethod가 EASY_PAY인 경우에만 허용됩니다.

간편결제 정보

간편결제시, 간편 결제에 대한 세부 정보

easyPayProvider string

간편결제 수단
useFreeInterestFromMall boolean

상점분담 무이자 활성화 여부
useCardPoint boolean

카드사 포인트 사용 여부
availableCards string[]

일부 카드사만 노출 설정

일부 카드사만을 선택 가능하게 하고 싶은 경우 사용하는 옵션입니다. card 섹션의 카드사 식별 값 항목을 참고해주세요.
installment object

할부 설정
- freeInstallmentPlans object[]
  
  무이자 할부 설정
  
  고객사가 부담하는 무이자 할부 설정입니다.
  - cardCompany * string
    
    무이자 할부를 제공하는 카드사 식별 값
    
    상단의 카드사 식별 값 항목을 참고해주세요.
  - months * number[]
    
    무이자 할부를 제공하는 개월 수
- monthOption object
  
  할부 개월 수 설정
  
  할부 결제 시 할부 개월 수를 설정할 수 있습니다.
  
  fixedMonth와 availableMonthList 중 하나만 제공해주세요.
  - fixedMonth * number
    
    구매자가 선택할 수 없도록 고정된 할부 개월수
    
    구매자가 할부 개월 수를 선택할 수 있도록 하려면 availableMonthList를 사용해주세요.
  - availableMonthList * number[]
    
    구매자가 선택할 수 있는 할부 개월수 리스트
cashReceiptType string

결제창에서 발급 가능한 현금영수증 발급 유형

PERSONAL: 소득공제용, CORPORATE: 지출증빙용, ANONYMOUS: 미발행
customerIdentifier string

현금영수증 발행 대상 식별 정보

결제요청 파라미터