퀵 가이드

퀵 가이드 내용을 포함한 포트원 결제 연동 샘플 프로젝트를 GitHub 저장소에서 추가로 확인하실 수 있습니다.

브라우저 측

포트원 브라우저 SDK 불러오기

포트원 브라우저 SDK를 불러옵니다.

아래 명령어로 브라우저 SDK를 설치합니다.

NPM Version

npm install --save @portone/browser-sdk

yarn add @portone/browser-sdk

pnpm add @portone/browser-sdk

bun add @portone/browser-sdk

deno add npm:@portone/browser-sdk

ni @portone/browser-sdk

상품 정보 불러오기

서버로부터 결제할 상품의 정보를 불러옵니다.

결제 요청

포트원 브라우저 SDK를 사용하여 결제를 요청합니다.

storeId: string

상점 아이디

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

channelKey: string

채널키

관리자 콘솔 > 연동 정보에서 채널 연동 시 생성된 채널키입니다.

paymentId: string

고객사 주문 고유 번호

주문을 식별하는 고유 번호로, 포트원에서 제공하지 않고 직접 입력합니다.

이미 승인이 완료된 paymentId로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다.

토스페이먼츠의 경우 영문 대소문자, 숫자, -, _만 허용되며, 6자 이상 64자 이하로 입력합니다.

orderName: string

주문명

주문명으로 자유롭게 입력합니다.

totalAmount: number

결제 금액

결제 금액을 정수로 입력합니다.

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

currency: string

결제 통화

ISO 4217에 의해 표준화된 알파벳 통화 코드를 입력합니다.

토스페이먼츠는 KRW만을 지원합니다.

payMethod: string

결제 수단

사용할 결제 수단에 맞는 값을 입력합니다.

card?: object

카드 결제 추가 정보

payMethod가 CARD인 경우 카드 결제와 관련한 추가 정보를 입력할 수 있습니다.

cardCompany?: string

단독 노출 카드사

구매자가 카드사를 선택하지 않고 입력한 카드사 화면으로 바로 이동하도록 합니다.

토스페이먼츠의 경우 카드사 단독 노출과 동시에 할부를 설정하려면 card.installment.monthOption.fixedMonth를 반드시 전달해야 하며, 그렇지 않을 경우 일시불로 결제됩니다.

availableCards?: string[]

카드사 일부 노출

지정한 일부 카드사만을 목록에 노출할 수 있습니다. 상단의 카드사 식별 값 항목을 참고해주세요.

useFreeInterestFromMall?: boolean

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

토스페이먼츠의 경우 상점 분담 무이자 할부 이용 시 별도 계약이 필요합니다.

useInstallment?: boolean

할부 사용 여부

installment?: object

할부 설정

토스페이먼츠의 경우 신용카드 할부 이용 시 별도 계약이 필요합니다.

freeInstallmentPlans?: object[]

무이자 할부 설정

고객사가 부담하는 무이자 할부 설정입니다.

cardCompany: string

무이자 할부를 제공하는 카드사 식별 값

상단의 카드사 식별 값 항목을 참고해주세요.

months: number[]

무이자 할부를 제공하는 개월 수

monthOption?: object

할부 개월 수 설정

할부 결제 시 할부 개월 수를 설정할 수 있습니다.

fixedMonth와 availableMonthList 중 하나만 제공해주세요.

fixedMonth: number

구매자가 선택할 수 없도록 고정된 할부 개월 수

구매자가 할부 개월 수를 선택할 수 있도록 하려면 availableMonthList를 사용해주세요.

토스페이먼츠의 경우 현대카드는 1만원, 그 외는 5만원 이상 결제에 대해서만 적용됩니다.

availableMonthList: number[]

구매자가 선택할 수 있는 할부 개월 수 목록

useCardPoint?: boolean

카드사 포인트 사용 여부

토스페이먼츠의 경우 카드사 포인트 사용 시 별도 계약이 필요합니다.

useAppCardOnly?: boolean

앱 카드만 허용할지 여부

토스페이먼츠의 경우 씨티카드는 적용이 불가능합니다.

taxFreeAmount?: number

면세 금액

결제 금액 중 면세금액에 해당하는 금액을 입력합니다.

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

토스페이먼츠의 경우 면세 및 복합과세 이용 시 별도 계약이 필요합니다.

vatAmount?: number

부가세

부가세 금액을 입력합니다.

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

customer?: object

구매자 정보

customerId?: string

구매자 고유 아이디

구매자를 식별하는 고유 번호로, 자유롭게 입력합니다.

fullName?: string

구매자 전체 이름

fullName과 (firstName, lastName) 쌍 중 하나만 입력해 주세요.

firstName?: string

구매자의 성을 제외한 이름

firstName과 lastName은 함께 입력해야 합니다. 전체 이름은 {firstName} {lastName}으로 기록됩니다.

lastName?: string

구매자의 성

firstName과 lastName은 함께 입력해야 합니다. 전체 이름은 {firstName} {lastName}으로 기록됩니다.

phoneNumber?: string

구매자 연락처

email?: string

구매자 이메일 주소

address?: object

구매자 주소

country?: string

국가

ISO 3166-1 alpha-2에 의해 표준화된 2글자 국가 코드입니다.

addressLine1: string

일반 주소

addressLine2: string

상세 주소

city?: string

도시

province?: string

주, 도, 시

zipcode?: string

구매자 우편번호

gender?: string

구매자 성별

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

birthYear?: string

구매자 출생년도

1990과 같이 숫자 4자리로 입력해 주세요.

birthMonth?: string

구매자 출생월

07과 같이 숫자 2자리로 입력해 주세요.

birthDay?: string

구매자 출생일

08과 같이 숫자 2자리로 입력해 주세요.

customData?: object

customData에는 임의의 데이터를 저장할 수 있습니다. 서버에서 결제건 조회 시에 확인할 수 있으며, 상품 정보를 전달하여 서버가 인식한 상품 정보와 일치하는지 확인할 수 있습니다.

bypass?: object

결제대행사 고유 기능

tosspayments?: object

discountCode?: string

결제수단에 프로모션을 적용할 경우 토스페이먼츠로부터 제공받은 코드를 입력합니다.

useInternationalCardOnly?: boolean

true로 설정하면 해외 카드로만 결제를 허용합니다.

redirectUrl?: string

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

대부분의 모바일 결제환경에서 반드시 입력해야 합니다.

noticeUrls?: string[]

결제 웹훅 수신 URL

관리자 콘솔에서 설정한 웹훅 주소 대신 사용할 주소입니다.

해당 값 설정시 관리자 콘솔에 설정한 주소로는 웹훅이 발송되지 않습니다.

appScheme?: string

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

ISP/앱카드에서 결제 완료 후 고객사 앱으로 복귀할 때 사용합니다.

토스페이먼츠의 경우 myappscheme:// 형식으로 입력해 주세요.

productType?: string

상품 유형

휴대폰 소액결제 시 productType는 필수 입력이며, 상점에 설정된 상품 유형과 입력된 상품 유형이 다른 경우 결제가 실패합니다.

실물 상품: PRODUCT_TYPE_REAL
디지털 상품: PRODUCT_TYPE_DIGITAL

offerPeriod?: oneof object

서비스 제공 기간

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

range?: object

서비스 제공 기간 범위

from?: string

시작 시점

to?: string

종료 시점

interval?: string

제공 기간

{number}d ({number}일)
{number}m ({number}분)
{number}y ({number}년)

products?: object[]

구매 상품 상세 정보

id: string

상품 아이디

name: string

상품명

code?: string

상품 코드

토스페이먼츠의 경우 반드시 입력해주세요.

amount: number

상품 단위 가격

결제 금액과 동일하게 통화별 scale factor가 적용된 금액으로 전달해주세요.

quantity: number

상품 수량

tag?: string

상품 태그

link?: string

상품 링크

storeDetails?: object

상점 정보

ceoFullName?: string

상점 대표자 이름

phoneNumber?: string

상점 연락처

address?: string

상점 주소

zipcode?: string

상점 우편번호

businessName?: string

상점 사업자명

businessRegistrationNumber?: string

상점 사업자 번호

isCulturalExpense?: boolean

문화비 지출 여부

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

isEscrow?: boolean

에스크로 결제 여부

true로 설정하면 에스크로를 사용합니다.

토스페이먼츠의 경우 에스크로 사용 시 별도 계약이 필요합니다.

country?: string

결제 국가

ISO 3166-1 alpha-2에 의해 표준화된 2글자 국가 코드입니다.

promotionId?: string

프로모션 아이디

popup?: object

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

center?: boolean

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

결제 오류 처리

결제 중 오류가 발생하여 결제가 완료되지 않은 경우를 처리합니다.

SDK의 반환 값에 code가 있는 경우 오류 상태로 message 필드에 오류 메시지가 존재합니다. 결제대행사로부터 오류를 전달받은 경우 code는 FAILURE_TYPE_PG이고, 결제대행사의 오류 코드인 pgCode를 기반으로 결제 오류를 처리할 수 있습니다.

서버 측으로 결제 완료 요청

완료된 결제의 paymentId를 서버로 전송하여 결제 상태를 반영합니다.

결제 완료 상태 처리

서버로부터 검증 후 결제가 완료된 경우를 처리합니다.

결제 실패 상태 처리

서버로부터 검증 결과를 획득하여, 결제가 최종적으로 실패한 경우를 처리합니다.

서버 측

포트원 서버 SDK 불러오기

포트원 서버 SDK를 불러옵니다.

아래 명령어로 서버 SDK를 설치합니다.

NPM Version

JSR Version

npm install --save @portone/server-sdk

yarn add @portone/server-sdk

pnpm add @portone/server-sdk

bun add @portone/server-sdk

deno add jsr:@portone/server-sdk

ni @portone/server-sdk

Node.js의 경우 v20 이상에서 정상 동작하며, v20 미만 버전은 폴리필이 필요합니다.

포트원 API Secret 설정

서버 SDK를 사용하기 위해 포트원 V2 API Secret을 설정합니다. API Secret은 포트원 관리자콘솔의 결제 연동 > 연동 정보 > 식별코드 ・ API Keys > V2 API에서 발급받으실 수 있습니다.

결제 완료 요청

완료된 결제의 실제 상태를 조회해 시스템에 반영합니다. 브라우저 SDK를 통해 결제하는 경우 모든 결제 과정이 브라우저에서 진행되므로 결제가 조작되는 것을 막기 위해 서버에서 검증이 필요합니다.

결제 정보 조회

브라우저에서 전송한 paymentId를 통해 실제 결제 상태를 조회합니다.

ISP/페이북을 통한 결제 시 토스페이먼츠가 실제 카드 번호와 다른 카드 번호를 전달하고 있어 결제 내역 단건 조회시 응답되는 payment_method_detail.card.detail.bin 정보가 정확하지 않을 수 있습니다.

결제 정보 일치 검증

포트원에 전달한 customData로 조회한 상품 정보와 결제 정보가 일치하는지 검증합니다.

웹훅 수신

결제 상태의 변화를 실시간으로 확인해야 한다면 웹훅을 사용할 수 있습니다.

HTTP Body 수신 설정

웹훅 내용을 검증하기 위해서는 HTTP Body를 문자열 형태로 수신해야 합니다.

웹훅 검증

수신한 웹훅이 위조되지 않았는지 포트원 서버 SDK를 사용하여 검증합니다.

결제 상태 업데이트

검증된 웹훅 결과를 바탕으로 결제 상태를 업데이트합니다.