웰컴페이먼츠

웰컴페이먼츠 결제 연동 방법을 안내합니다.

채널 설정하기

사전 계약 안내

아래 기능을 사용하시려면 웰컴페이먼츠에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다.

  • 간편결제 사용
  • 면세 / 복합과세 / 지정금액 방식 사용
  • 할부 사용
  • 상점 부담 무이자 할부 사용
  • 카드사 포인트 사용
  • 에스크로 사용
  • 휴대폰 실물 / 컨텐츠 사용
  • 휴대폰 빌링키 발급과 동시에 결제 실물 / 컨텐츠 사용

가능한 결제 수단

  • 결제창 일반 결제

    payMethod 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

    • 카드 : CARD
    • 계좌이체 : TRANSFER
    • 가상계좌 : VIRTUAL_ACCOUNT
    • 상품권 : GIFT_CERTIFICATE
    • 휴대폰 소액 결제 : MOBILE
    • 간편결제 : EASY_PAY
  • 결제창 빌링키 발급 카드 결제는 requestIssueBillingKey 함수, 휴대폰 결제는 requestIssueBillingKeyAndPay 함수를 이용합니다. requestIssueBillingKeyAndPay 함수를 이용할 때에는 빌링키 발급과 동시에 결제가 일어납니다.

    billingKeyMethod 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

    • 카드: CARD
    • 휴대폰: MOBILE
  • API 수기(키인) 결제

    method 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

    • 카드: card 로 설졍하여 카드 관련 파라미터 입력
    • 가상계좌: virtualAccount 로 설정하여 가상계좌 관련 파라미터 입력

    자세한 파라미터 구성은 REST API Docs 를 참고해주시기 바랍니다.

  • API 빌링키 발급

    method 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.

    • 카드: card 로 설졍하여 카드 관련 파라미터 입력

    자세한 파라미터 구성은 REST API Docs를 참고해주시기 바랍니다.

SDK 결제 요청하기

결제 요청 시에는 requestPayment 함수를 호출해야 합니다. channelKey파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
  PortOne.requestPayment({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    paymentId: `payment${crypto.randomUUID()}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "CURRENCY_KRW",
    payMethod: "CARD",
    customer: {
      fullName: "포트원",
      phoneNumber: "010-0000-1234",
      email: "test@portone.io",
    },
  });
}

주요 파라미터

storeId: string

상점 아이디

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

paymentId: string

고객사 주문 고유 번호

고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 paymentId로 결제를 시도하는 경우 에러가 발생합니다.

orderName: string

주문명

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

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

totalAmount: number

결제 금액

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

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

payMethod: string

결제수단 구분코드

결제 호출 시 결제수단을 지정할 때 사용됩니다.

  • 신용카드 : CARD
  • 실시간 계좌이체 : TRANSFER
  • 가상계좌 : VIRTUAL_ACCOUNT
  • 휴대폰 소액결제 : MOBILE
  • 간편 결제 : EASY_PAY
customer?: object

고객 정보

fullName?: string

구매자 전체 이름

  • 웰컴페이먼츠의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다.
phoneNumber?: string

구매자 연락처

  • 웰컴페이먼츠의 PC 결제의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional)
email?: string

구매자 이메일

  • 웰컴페이먼츠의 PC 결제의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional)
bypass?: oneof object

PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음

welcome?: WelcomeBypassOnPc & WelcomeBypassOnMobile

웰컴페이먼츠 bypass 파라미터

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

  • bypass 예시 코드

    {
      "bypass": {
        "welcome": {
          "logo_url": "https://portone.io/assets/portone.87061e94.avif",
          "logo_2nd": "https://admin.portone.io/assets/img/auth/lock.png",
          "acceptmethod": ["SKIN(#C1272C)", "below1000", "ocb"],
          "P_CARD_OPTION": "selcode=14",
          "P_NMANE": "포트원",
          "P_RESERVED": ["below1000=Y", "noeasypay=Y"]
        }
      }
    }
WelcomeBypassOnPc

PC용 파라미터

logo_url?: string

결제창에 삽입할 메인 로고 url

결제창 중앙 상단에 표시됩니다. 이미지 권장 사이즈는 89*18 입니다.

logo_2nd?: string

결제창에 삽입할 서브 로고 url

결제창 우측 상단에 표시됩니다. 이미지 권장 사이즈는 64*13 입니다.

acceptmethod?: string[]

PC - 카드 결제 전용 파라미터

형식설명
SKIN(색상코드)결제 창의 배경 색상
- 기본값 : #c1272c
- 예시: SKIN(#fc6b2d)
below10001,000원 미만 결제 허용 여부
- 기본값: 허용하지 않음
paypopup안심클릭을 팝업 형태로 렌더링 시킬지 여부
- 기본값: 레이어
onlyeasypaycode(간편 결제 리스트)카드 결제창 내 렌더링 될 간편 결제 리스트
예) 카카오페이, 엘페이, 페이코만 렌더링 → ”kakaopay:lpay:payco” 전달
- 카카오페이: kakaopay
- 엘페이: lpay
- 페이코: payco
- 토스페이: tosspay
SLIMQUOTA(슬림 할부 설정)부분 무이자 설정. 슬림 할부
- 형식) SLIMQUOTA(코드-개월:개월^코드-개월:개월
- 예시) SLIMQUOTA(11-2:3^34-2:3)

PC - 휴대폰 소액 결제 전용 파라미터

형식설명
hppdefaultcorp(통신사 코드)휴대폰 소액결제시 기본 선택되어있는 통신사
- 기본: 기본 선택되어있는 통신사 없음
예) KT 기본 선택 → ”hppdefaultcorp(KT)” 전달
- SKT: SKT
- KT: KTF
- LG 유플러스: LGT
- 알뜰폰 전체: MVNO
- 알뜰폰 CJ 헬로 모바일: CJH
- 알뜰폰 티플러스: KCT
- 알뜰폰 SK 세븐모바일: SKL
hppnofix(N 또는 Y)휴대폰 소액결제창에 자동 입력되는 buyer_tel값을 수정할 수 있는지 여부
- 기본값: 수정 가능
- Y : 수정 불가능
- N : 수정 가능(기본)
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "bypass": {
    "welcome": {
      "acceptmethod": [
        "SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d
        "below1000", // 1,000원 이하 결제 허용
        "paypopup", // 안심 클릭을 팝업으로 렌더링
        "onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링
        "hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택
        "hppnofix(Y)" // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능
      ]
    }
  }
}
WelcomeBypassOnMobile

모바일용 파라미터

P_CARD_OPTION?: string

신용카드 우선선택 옵션

설정한 카드코드에 해당하는 카드가 선택된 채로 Display 됩니다. selcode=카드코드 형식으로 입력합니다. (ex. selcode=14)

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://) 호출

유의사항

공통

카드 결제

간편 결제

계좌이체

가상계좌 결제

상품권 결제

휴대폰 소액 결제

SDK 카드 빌링키 발급 요청하기

카드 빌링키 발급 요청 시에는 requestIssueBillingKey 함수를 호출해야 합니다. channelKey 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

import * as PortOne from "@portone/browser-sdk/v2";
function requestIssueBillingKey() {
  PortOne.requestIssueBillingKey({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    billingKeyMethod: "CARD",
    issueId: "test-issueId",
    issueName: "test-issueName",
    customer: {
      fullName: "포트원",
      phoneNumber: "010-0000-1234",
      email: "test@portone.io",
    },
  });
}

주요 파라미터


storeId: string

상점 아이디

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

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

billingKeyMethod: string

빌링키 발급수단

웰컴페이먼츠는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는 CARD로 고정해야 합니다.

issueId: string

빌링키 발급 건 고유 ID

  • 고객사에서 채번하여 사용해야 합니다.
  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
issueName: string

빌링키 발급 시 결제창에 표시되는 제목

  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
customer?: object

고객 정보

fullName?: string

구매자 전체 이름

  • 웰컴페이먼츠의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다.
phoneNumber?: string

구매자 연락처

  • 웰컴페이먼츠의 PC 빌링키 발급의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional)
email?: string

구매자 이메일

  • 웰컴페이먼츠의 PC 빌링키 발급의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional)
offerPeriod?: object

제공 기간

  • 웰컴페이먼츠 모바일 빌링키 발급의 경우 필수로 입력해야 합니다. (PC인 경우에는 optional)
bypass?: oneof object

PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음

welcome?: object

웰컴페이먼츠에서 제공하는 파라미터 모음

carduse?: 'percard' | 'cocard'

개인/법인카드 사용 선택 옵션

  • 모바일에서만 동작하는 파라미터입니다.
  • 'percard' 혹은 'cocard'를 입력할 수 있습니다.
  • 'percard' 입력 시 개인 카드로만 결제를 진행할 수 있으며, 'cocard' 입력 시 법인 카드로만 결제를 진행 할 수 있습니다.

유의사항

SDK 휴대폰 빌링키 발급 및 결제 요청하기

휴대폰 빌링키 발급 및 결제 요청 시에는 requestIssueBillingKeyAndPay 함수를 호출해야 합니다. channelKey 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

import * as PortOne from "@portone/browser-sdk/v2";
function requestIssueBillingKeyAndPay() {
  PortOne.requestIssueBillingKeyAndPay({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    billingKeyAndPayMethod: "PHONE",
    totalAmount: 1000,
    currency: "KRW",
    paymentId: "test-paymentId",
    orderName: "test-orderName",
    customer: {
      fullName: "포트원",
      phoneNumber: "010-0000-1234",
      email: "test@portone.io",
    },
  });
}

주요 파라미터


storeId: string

상점 아이디

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

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

billingKeyAndPayMethod: string

빌링키 발급 및 결제수단

웰컴페이먼츠는 빌링키 발급 및 결제 수단으로 휴대폰 소액 결제만을 지원하므로 해당 파라미터는 PHONE로 고정해야 합니다.

paymentId: string

빌링키 발급 및 결제 건 고유 ID

  • 고객사에서 채번하여 사용해야 합니다.
  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
orderName: string

빌링키 발급 및 결제 시 결제창에 표시되는 제목

  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
customer?: object

고객 정보

fullName?: string

구매자 전체 이름

  • 웰컴페이먼츠의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다.
phoneNumber?: string

구매자 연락처

  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
email?: string

구매자 이메일

  • 웰컴페이먼츠의 경우 필수 입력해야 합니다.
offerPeriod?: object

제공 기간

  • 웰컴페이먼츠 모바일 빌링키 발급 및 결제의 경우 필수로 입력해야 합니다. (PC인 경우에는 optional)

유의사항

API 수기(키인)결제 요청하기

수기(키인)로 결제하기 위해서는 POST /payments/${PAYMENT_ID_HERE}/instant를 이용하여 결제 요청을 해야합니다.

// ... 수기(키인) 결제
const issueResponse = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    orderName: "나이키 와플 트레이너 2 SD",
    amount: {
      total: 10000,
    },
    currency: "KRW",
    customer: {
      name: {
        full: "홍길동",
      },
      email: "test@test.com",
      phoneNumber: "010-1234-0000",
    },
    method: {
      virtualAccount: {
        bank: `SHINHAN`,
        expiry: {
          dueDate: `2024-11-12T00:00:00+09+00`, //입금기한은 미래시간만 가능합니다.
        },
        cashReceipt: {
          type: `PERSONAL`,
          customerIdentityNumber: `010-1234-0000`,
        },
        remitteeName: `테스트`,
      },
    },
    productCount: 1,
  },
});

주요 파라미터

paymentId: string

고객사 주문 고유 번호

고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 paymentId로 결제를 시도하는 경우 에러가 발생합니다.

orderName: string

주문명

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

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

amount: object

결제 금액

total: number

총 결제 금액

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

taxFree?: number

면세액

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

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

method: object

결제수단 정보

virtualAccount?: object

가상계좌 결제 시 파라미터

bank: string

발급 은행

expiry: object

입금 만료 기한

validHours?: integer

유효 시간

dueDate?: string

만료 시점

시간은 ISO8601 형식으로 입력해야 합니다.

option: object

가상계좌 발급 방식

type: string

가상계좌 발급 유형

발급 유형은 ENUM으로 정의되어 있습니다.

  • 회전식 가상계좌 : NORMAL
  • 고정식 가상계좌 : FIXED
  • 회전식 가상계좌는 일반적으로 사용되는 방식이며 PG사에서 직접 채번한 가상계좌번호를 사용합니다.
fixed?: object

고정식 가상계좌 발급 유형

accountNumber?: string

고정식 가상계좌번호

  • PG사가 일정 개수만큼의 가상계좌번호를 발급하여 가맹점에게 미리 전달하고 가맹점이 그 중 하나를 선택하여 사용하는 방식입니다. 웰컴페이먼츠에서는 해당 방식만 지원하고 있습니다.
cashReceipt: object

현금영수증 정보

type: string

발급 유형

발급 유형은 ENUM으로 정의되어 있습니다.

  • 소득공제용 : PERSONAL
  • 지출증빙용 : CORPORATE
  • 미발행 : NO_RECEIPT
customerIdentityNumber: string

현금영수증 식별 번호

  • 소득공제인 경우 주민등록번호 혹은 휴대폰 번호를 입력해야 합니다.
  • 지출증빙인 경우 사업자등록번호를 입력해야 합니다.
remitteeName?: string

예금주명

card?: object
credential: object

인증 관련 정보

number: string

카드 번호

expiryYear: string

유효 기간 만료 연도 (YY 형식 ex. 24)

expiryMonth: string

유효기간 만료 월 (MM 형식 ex. 05)

birthOrBusinessRegistrationNumber?: string

생년월일 또는 사업자 등록 번호

passwordTwoDigits?: string

비밀번호 앞 두자리

customer?: object

고객 정보

name: object

고객 이름

웰컴페이먼츠의 경우 full 혹은 separated를 필수로 입력해야 합니다.

full?: string

한 줄 이름 형식 (ex. 김포트)

separated?: object

분리된 이름

first: string

이름

last: string

phoneNumber: string

구매자 연락처

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
email: string

구매자 이메일

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
productCount?: integer

상품 개수

API 빌링키 발급 요청하기

빌링키를 발급하기 위해서는 POST /billing-keys를 이용하여 빌링키 발급 요청을 해야합니다.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

const issueResponse = await axios({
  url: "https://api.portone.io/billing-keys",
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
    },
    method: {
      card: {
        credential: {
          number: "1111111111111111",
          expiryMonth: "01",
          expiryYear: "20",
          birthOrBusinessRegistrationNumber: "900101",
          passwordTwoDigits: "00",
        },
      },
    },
  },
});

주요 파라미터

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

method: object

결제수단 정보

card?: object
credential: object

인증 관련 정보

number: string

카드 번호

expiryYear: string

유효 기간 만료 연도 (YY 형식 ex. 24)

expiryMonth: string

유효기간 만료 월 (MM 형식 ex. 05)

birthOrBusinessRegistrationNumber?: string

생년월일 또는 사업자 등록 번호

passwordTwoDigits?: string

비밀번호 앞 두자리

customer: object

고객 정보

name: object

고객 이름

웰컴페이먼츠의 경우 full 혹은 separated를 필수로 입력해야 합니다.

full?: string

한 줄 이름 형식 (ex. 김포트)

separated?: object

분리된 이름

first: string

이름

last: string

phoneNumber: string

구매자 연락처

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
email: string

구매자 이메일

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.

API 빌링키 단건 결제 요청하기

발급된 빌링키로 단건 결제를 하기 위해 POST /payments/${PAYMENT_ID_HERE}/billing-key를 이용하여 결제를 요청합니다.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/billing-key`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
    orderName: "월간 이용권 정기결제",
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      phoneNumber: `010-1234-5678`,
      email: `test@test.com`,
    },
    amount: {
      total: 10000,
    },
    currency: "KRW",
    productCount: 1,
  },
});

주요 파라미터

paymentId: string

결제 주문 번호

  • 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
  • URL path에 포함하여 요청해야 합니다.
billingKey: string

빌링키 결제에 사용할 빌링키

orderName: string

주문명

amount: object

결제 금액

total: number

총 결제 금액

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

taxFree?: number

면세액

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

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

customer: object

고객 정보

name: object

고객 이름

웰컴페이먼츠의 경우 full 혹은 separated를 필수로 입력해야 합니다.

full?: string

한 줄 이름 형식 (ex. 김포트)

phoneNumber: string

구매자 연락처

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
email: string

구매자 이메일

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
productCount?: integer

상품 개수

API 빌링키 예약/반복 결제 요청하기

예약 결제를 하기 위해서는 POST /payments/${PAYMENT_ID_HERE}/schedule 를 이용하여 결제를 예약합니다.

웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/schedule`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    payment: {
      billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
      orderName: "월간 이용권 정기결제",
      customer: {
        id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      },
      amount: {
        total: 10000,
      },
      currency: "KRW",
    },
    timeToPay: "2023-01-01 00:00:00", // 결제를 시도할 시각
  },
});

주요 파라미터

paymentId: string

결제 주문 번호

  • 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
  • URL path에 포함하여 요청해야 합니다.
payment: object

빌링키 결제 요청 입력정보

billingKey: string

빌링키 결제에 사용할 빌링키

orderName: string

주문명

amount: object

결제 금액

total: number

총 결제 금액

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

taxFree?: number

면세액

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

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

timeToPay: string

결제 예정 시점

customer: object

고객 정보

name: object

고객 이름

웰컴페이먼츠의 경우 full 혹은 separated를 필수로 입력해야 합니다.

full?: string

한 줄 이름 형식 (ex. 김포트)

phoneNumber: string

구매자 연락처

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.
email: string

구매자 이메일

  • 웰컴페이먼츠의 경우 필수로 입력해야 합니다.

유의사항

공통

에스크로