개발자센터

결제요청 파라미터

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

결제요청 파라미터 정의

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을 적용하니 둘 중 하나만 제공해주세요.

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 설정

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 데이터

popup object

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

  • center boolean

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

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

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