# 포트원 개발자센터 문서 > 포트원(PortOne)은 온라인 결제, 본인인증, 파트너 정산 자동화 및 재무/회계 업무를 위한 API와 SDK를 제공하는 서비스입니다. 1. 포트원 개발자센터 개별 문서 파일은 각각 경로(pathname), 제목(title), 설명(description)을 가지며, 이를 통해 해당 문서의 내용을 유추할 수 있습니다. - `opi/`: 원 페이먼트 인프라(결제, 본인인증) 관련 문서 - `platform/`: 파트너정산 자동화 관련 문서 - `api/`: 포트원이 제공하는 API 관련 문서 - `sdk/`: 포트원이 제공하는 SDK 관련 문서 - `schema/`: 포트원 API, SDK 스키마 파일 - `blog/posts/`: 블로그 포스트 - `release-notes/`: 릴리즈노트 2. 온라인 결제 및 본인인증에 관련해서는 버전(V1, V2)을 올바르게 파악하는 것이 아주 중요합니다. 사용자 질의에 관련된 섹션(V1, V2, 공통 등)을 확실하게 파악한 후 해당 버전의 문서와 공통 문서 내용을 제공 및 활용하세요. - 버전이 파악되지 않은 경우 사용자에게 질의하여 버전을 먼저 확인하고, 그럴 수 없는 불가피한 경우 공통 문서 또는 최신 버전인 V2 문서를 우선적으로 활용하세요. 3. API 및 SDK 스키마를 조회하고 싶은 경우 해당 버전의 스키마 파일에서 YAML, JSON, GraphQL SDL 형식으로 정확하게 확인할 수 있습니다. 4. 사용자에게 문서 레퍼런스를 URL로 제공할 때는 마크다운 파일 링크가 아닌, 개발자센터 웹사이트 URL을 사용하세요. - `.md`로 끝나는 URL은 마크다운 파일 링크입니다. 마크다운 파일 링크에서 마지막 `.md`를 제거하면 웹사이트 URL로 사용할 수 있습니다. - 사용자가 원하는 버전(V1, V2)이 특정되었다면 `?v=v2`, `?v=v1` 쿼리 파라미터를 추가하여 URL로 제공하세요. - hostname이 누락된 URL의 경우 `https://developers.portone.io`를 추가하여 공유하세요. 5. 이미지, 파일 다운로드 링크 등이 마크다운 문서에서는 대부분 누락됩니다. 해당 내용을 조회해야 하는 경우 개발자센터 웹사이트에서 확인해야 합니다. ## 목차 ### V2 스키마 파일 - [V2 브라우저 SDK 스키마](https://developers.portone.io/schema/browser-sdk.yml) - [V2 GraphQL 스키마](https://developers.portone.io/schema/v2.graphql) - [V2 OpenAPI YAML](https://developers.portone.io/schema/v2.openapi.yml) - [V2 OpenAPI JSON](https://developers.portone.io/schema/v2.openapi.json) ### V2 SDK - [모바일 SDK 레퍼런스](https://developers.portone.io/sdk/ko/v2-mobile-sdk/readme): 결제창 연동시 사용되는 SDK에 대한 설명 문서입니다. - [requestIssueBillingKeyAndPay 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/billing-key-and-pay-request): requestIssueBillingKeyAndPay 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [requestIssueBillingKeyAndPay 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/billing-key-and-pay-response): requestIssueBillingKeyAndPay 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [requestIssueBillingKey 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/billing-key-request): requestIssueBillingKey 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [requestIssueBillingKey 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/billing-key-response): requestIssueBillingKey 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [버전별 Changelog](https://developers.portone.io/sdk/ko/v2-sdk/changelog): @portone/browser-sdk 패키지의 버전별 변경 사항을 확인하세요. - [requestIdentityVerification 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/identity-verification-request): requestIdentityVerification 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [requestIdentityVerification 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/identity-verification-response): requestIdentityVerification 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [loadIssueBillingKeyUI 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/load-issue-billing-key-ui-request): loadIssueBillingKeyUI 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [loadIssueBillingKeyUI 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/load-issue-billing-key-ui-response): loadIssueBillingKeyUI 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [loadPaymentUI 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/load-payment-ui-request): loadPaymentUI 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [loadPaymentUI 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/load-payment-ui-response): loadPaymentUI 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [requestPayment 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/payment-request): requestPayment 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [requestPayment 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/payment-response): requestPayment 호출 결과로 받는 데이터의 형식을 확인할 수 있습니다. - [JavaScript SDK 레퍼런스](https://developers.portone.io/sdk/ko/v2-sdk/readme): 결제창 연동시 사용되는 SDK에 대한 설명 문서입니다. - [updateLoadIssueBillingKeyUIRequest 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/update-load-issue-billing-key-ui-request): updateLoadIssueBillingKeyUIRequest 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [updateLoadPaymentUIRequest 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/update-load-payment-ui-request): updateLoadPaymentUIRequest 호출 시 사용되는 파라미터의 형식을 확인할 수 있습니다. - [서버 SDK 레퍼런스](https://developers.portone.io/sdk/ko/v2-server-sdk/readme): 웹훅 및 REST API 연동시 사용되는 SDK에 대한 설명 문서입니다. - [포트원 SDK 소개](https://developers.portone.io/sdk/ko/readme): 포트원에서 제공하는 SDK 가이드입니다. ### V2 API 레퍼런스 - [API 하위호환성 지원](https://developers.portone.io/api/backward-compatibility): 포트원이 보장하는 V1, V2 API 하위호환성에 대한 내용입니다. ### V2 통합 가이드 - [스마트 라우팅](https://developers.portone.io/opi/ko/console/guide/smartrouting): 포트원 스마트 라우팅을 사용하기 위한 그룹 설정을 관리할 수 있습니다. 관리자콘솔 내 스마트 라우팅 그룹 설정 방법을 안내합니다. - [컨펌 프로세스](https://developers.portone.io/opi/ko/extra/confirm-process/readme-v2): 결제 승인 직전에 고객사 측에 결제 의사를 최종적으로 확인하는 기능입니다. - [본인인증 연동하기](https://developers.portone.io/opi/ko/extra/identity-verification/readme-v2): 포트원을 이용하여 간편하게 본인인증을 연동하는 방법을 확인합니다. - [수동 승인](https://developers.portone.io/opi/ko/extra/manual-confirm/readme-v2): 고객사 서버에서 API를 호출하여 결제를 승인하는 연동 방식입니다. - [모바일 앱에서 결제 연동하기](https://developers.portone.io/opi/ko/extra/mobile-payment/readme-v2): 모바일 앱(Android, iOS, Flutter, React Native)에서 포트원 결제를 연동하는 방법을 안내합니다. - [결제취소(환불) 연동하기](https://developers.portone.io/opi/ko/integration/cancel/v2/readme): 포트원 V2 결제취소 API를 이용한 결제취소 방법을 안내합니다. - [다날 본인인증](https://developers.portone.io/opi/ko/integration/pg/v2/danal-identity-verification): 다날 본인인증 연동 방법을 안내합니다. - [엑심베이](https://developers.portone.io/opi/ko/integration/pg/v2/eximbay-v2): 엑심베이 결제 연동 방법을 안내합니다. - [갤럭시아머니트리](https://developers.portone.io/opi/ko/integration/pg/v2/galaxia): 갤럭시아머니트리 결제 연동 방법을 안내합니다. - [KG이니시스 일본결제](https://developers.portone.io/opi/ko/integration/pg/v2/inicis-jp): KG이니시스 일본결제 연동 방법을 안내합니다. - [KG이니시스 통합인증](https://developers.portone.io/opi/ko/integration/pg/v2/inicis-unified-identity-verification): KG이니시스 통합인증 연동 방법을 안내합니다. - [KG이니시스](https://developers.portone.io/opi/ko/integration/pg/v2/inicis-v2): KG이니시스 결제 연동 방법을 안내합니다. - [카카오페이](https://developers.portone.io/opi/ko/integration/pg/v2/kakaopay): 카카오페이 간편결제 연동 방법을 안내합니다. - [KCP 본인인증](https://developers.portone.io/opi/ko/integration/pg/v2/kcp-v2-identity-verification): KCP 본인인증 연동 방법을 안내합니다. - [NHN KCP](https://developers.portone.io/opi/ko/integration/pg/v2/kcp-v2): NHN KCP 연동 방법을 안내합니다. - [이지페이(KICC) 해외결제](https://developers.portone.io/opi/ko/integration/pg/v2/kicc-v2): 이지페이(KICC) 해외결제 연동 방법을 안내합니다. - [한국결제네트웍스(KPN)](https://developers.portone.io/opi/ko/integration/pg/v2/kpn): 한국결제네트웍스(KPN) 결제 연동 방법을 안내합니다. - [KSNET](https://developers.portone.io/opi/ko/integration/pg/v2/ksnet): KSNET 결제 연동 방법을 안내합니다. - [네이버페이 (결제형)](https://developers.portone.io/opi/ko/integration/pg/v2/naverpay): 네이버페이 간편결제 연동 방법을 안내합니다. - [나이스정보통신](https://developers.portone.io/opi/ko/integration/pg/v2/nice-v2): 나이스정보통신 결제 연동 방법을 안내합니다. - [페이레터 해외결제](https://developers.portone.io/opi/ko/integration/pg/v2/payletter-global): 페이레터 해외결제 연동 방법을 안내합니다. - [페이먼트월](https://developers.portone.io/opi/ko/integration/pg/v2/paymentwall): 페이먼트월 결제 연동 방법을 안내합니다. - [페이팔](https://developers.portone.io/opi/ko/integration/pg/v2/paypal-v2): 페이팔 결제 연동 방법을 안내합니다. - [결제대행사 선택하여 연동하기](https://developers.portone.io/opi/ko/integration/pg/v2/readme): 각 PG사별 결제 연동 방법을 확인할 수 있습니다. - [스마트로](https://developers.portone.io/opi/ko/integration/pg/v2/smartro-v2): 스마트로 결제 연동 방법을 안내합니다. - [토스페이](https://developers.portone.io/opi/ko/integration/pg/v2/tosspay-v2): 토스페이 간편결제 연동 방법을 안내합니다. - [토스페이먼츠](https://developers.portone.io/opi/ko/integration/pg/v2/tosspayments): 토스페이먼츠 결제 연동 방법을 안내합니다. - [Triple-A](https://developers.portone.io/opi/ko/integration/pg/v2/triple-a): Triple-A 결제 연동 방법을 안내합니다. - [웰컴페이먼츠](https://developers.portone.io/opi/ko/integration/pg/v2/welcome): 웰컴페이먼츠 결제 연동 방법을 안내합니다. - [1. 빌링키 발급하기](https://developers.portone.io/opi/ko/integration/start/v2/billing/issue): 결제창 또는 API를 이용하여 빌링키를 발급할 수 있습니다. - [2. 결제 요청하기](https://developers.portone.io/opi/ko/integration/start/v2/billing/payment): 포트원 빌링키 결제 API를 사용해 바로 결제를 요청합니다. - [빌링키 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/billing/readme): 카드 혹은 휴대 전화 정보를 이용하여 빌링키를 발급하고, 빌링키를 이용해 결제를 요청하는 방법을 안내합니다. - [3. 예약/반복결제 구현하기](https://developers.portone.io/opi/ko/integration/start/v2/billing/schedule): 발급한 빌링키로 예약/반복결제를 구현하는 방법을 안내합니다. - [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/checkout): PG 결제창을 이용하는 인증 결제를 연동합니다. - [수기(키인) 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/keyin): 구매자 인증 없이 결제 수단 정보만으로 결제를 요청합니다. - [결제 연동 시작하기](https://developers.portone.io/opi/ko/integration/start/v2/readme): 새롭게 출시된 V2 결제 서비스를 소개합니다. - [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2): 웹훅 알림을 받아 결제 정보를 동기화할 수 있습니다. - [퀵 가이드](https://developers.portone.io/opi/ko/quick-guide/payment): 결제연동 퀵 가이드 - [상점 계정 관리](https://developers.portone.io/opi/ko/console/guide/account): 포트원 콘솔에서 하위 상점을 생성하여 상점별로 결제 거래 건을 분리하여 관리할 수 있으며, 해당 상점을 관리할 수 있는 계정을 별도로 생성하여 권한을 나눌 수 있습니다. 이에 대해 안내합니다. - [빌링결제 내역 조회](https://developers.portone.io/opi/ko/console/guide/billing-payments): 포트원을 통해 발생한 빌링키 결제 내역을 상태별로 조회하고 결제 예약일 변경, 예약 해지, 결제 재시도, 결제 재예약 기능을 이용하여 빌링 결제 건을 관리할 수 있으며, 결제 실패 건에 대한 일괄 재시도를 자동화해주는 리커버리 기능에 대해 안내합니다. - [연동 정보](https://developers.portone.io/opi/ko/console/guide/channel-manage): 포트원 결제 모듈을 사용하기 위한 연동 설정을 관리할 수 있습니다. 결제대행사 채널 관리, 식별코드 및 API Keys, 결제알림(웹훅) 관리, 추가 설정 관리 방법에 대해 안내합니다. - [홈](https://developers.portone.io/opi/ko/console/guide/home): 포트원 콘솔 홈화면에서는 결제 현황 대시보드, 공지사항, FAQ, 포트원 새소식, 포트원 서비스 가이드 링크를 제공하고 있으며, 이에 대해 안내합니다. - [연동 관리](https://developers.portone.io/opi/ko/console/guide/integration): 포트원 결제 모듈을 사용하기 위한 연동 설정을 관리할 수 있습니다. 결제대행사 채널 관리, 식별코드 및 API Keys, 결제알림(웹훅) 관리, 추가 설정 관리 방법에 대해 안내합니다. - [결제](https://developers.portone.io/opi/ko/console/guide/pay): 포트원을 관리자콘솔을 통해 발생한 거래를 조회 및 관리하는 방법을 안내합니다. - [결제 내역 조회](https://developers.portone.io/opi/ko/console/guide/payments): 포트원을 통해 발생한 결제 내역을 상태별로 조회하고, 부분 취소 및 전체 취소 기능을 이용하여 결제 건을 관리할 수 있으며, 이에 대해 안내합니다. - [프로모션](https://developers.portone.io/opi/ko/console/guide/promotion): 카드사 할인을 사용하기 위한 프로모션 설정을 관리할 수 있습니다. 관리자콘솔 내 프로모션 설정 방법을 안내합니다. - [관리자 콘솔 소개](https://developers.portone.io/opi/ko/console/guide/readme): 포트원 관리자 콘솔 사용법을 안내합니다. - [전자결제 신청](https://developers.portone.io/opi/ko/console/guide/reg): 결제대행사 및 결제수단을 선택하고 전자결제를 신청하는 과정을 안내합니다. - [PG 거래대사 가이드](https://developers.portone.io/opi/ko/etc/recon): PG 거래대사는 PG사와 간편결제사로부터 정산 받는 금액 및 상세내역을 포트원 콘솔에서 PG가 여러 개여도 한 번에 자동 대사된 데이터를 확인할 수 있는 통합 조회 서비스입니다. - [프로모션 생성하기](https://developers.portone.io/opi/ko/extra/promotion/console-guide): 프로모션 기간, 예산, 할인 조건 등 설정 방법을 안내합니다. - [프로모션 결제 연동하기](https://developers.portone.io/opi/ko/extra/promotion/integration): 프로모션 할인금액을 적용하는 방법을 안내합니다. - [프로모션](https://developers.portone.io/opi/ko/extra/promotion/intro): 카드 즉시 할인을 쉽게 운영 및 관리할 수 있는 서비스입니다. - [프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund): 프로모션을 적용하여 승인된 결제건들에 대하여 취소/환불하는 방법을 안내합니다. - [스마트 라우팅 - 콘솔 가이드](https://developers.portone.io/opi/ko/extra/smart-routing/console-guide): 멀티PG 환경을 클릭 한 번으로 쉽게 만들 수 있는 결제 트래픽 분산 자동화 서비스입니다. - [스마트 라우팅 - 연동하기](https://developers.portone.io/opi/ko/extra/smart-routing/integration): 멀티PG 환경을 클릭 한 번으로 쉽게 만들 수 있는 결제 트래픽 분산 자동화 서비스입니다. - [스마트 라우팅](https://developers.portone.io/opi/ko/extra/smart-routing/intro): 멀티PG 환경을 클릭 한 번으로 쉽게 만들 수 있는 결제 트래픽 분산 자동화 서비스입니다. - [결제 연동 준비하기](https://developers.portone.io/opi/ko/integration/ready/readme): 포트원을 이용한 연동 개발이 처음이시라면 아래 안내 사항에 따라 진행하세요. - [AI 도구 활용하기](https://developers.portone.io/opi/ko/integration/using-ai-tools): AI 도구를 활용하여 쉽고 빠르게 포트원을 연동하세요. 연동 코드 작성은 물론, 24시간 언제나 관련 질의에 대한 답변을 받을 수 있습니다. - [가상계좌 입금통보 설정](https://developers.portone.io/opi/ko/integration/virtual-account/readme): 결제대행사별 입금통보 URL을 안내합니다. - [포트원 결제 연동 Doc](https://developers.portone.io/opi/ko/readme): 포트원 결제 연동 가이드입니다. 빠른 시간 안에 결제를 연동할 수 있게 도와드립니다. - [직접 문의하기](https://developers.portone.io/opi/ko/support/contact): 기술지원 문의를 위한 연락처 정보입니다. - [용어 사전](https://developers.portone.io/opi/ko/support/pg-terms): 온라인 결제 시스템에서 자주 사용되는 용어들을 설명합니다. - [TLS 지원 범위](https://developers.portone.io/opi/ko/support/tls-support): 포트원 v1 API의 TLS 지원 범위 및 설정 가이드를 확인할 수 있습니다. ### 파트너정산 - [용어 사전](https://developers.portone.io/platform/ko/guides/dictionary): 파트너 정산 자동화 솔루션에서 자주 사용되는 용어를 설명합니다. - [서비스 프로세스](https://developers.portone.io/platform/ko/guides/process) - [세금계산서 웹훅 가이드](https://developers.portone.io/platform/ko/guides/webhook): 세금계산서 상태 변화 웹훅의 사용 방법과 설정 가이드입니다. - [파트너 정산 자동화 서비스 가이드](https://developers.portone.io/platform/ko/readme) - [고객사 예시](https://developers.portone.io/platform/ko/usages/client) - [계약 예시](https://developers.portone.io/platform/ko/usages/contract) - [할인 예시](https://developers.portone.io/platform/ko/usages/discount) - [추가수수료 예시](https://developers.portone.io/platform/ko/usages/fee) - [주문정산 예시](https://developers.portone.io/platform/ko/usages/order) - [파트너 예시](https://developers.portone.io/platform/ko/usages/partner) - [AI 도구 활용하기](https://developers.portone.io/platform/ko/using-ai-tools): AI 도구를 활용하여 쉽고 빠르게 포트원을 연동하세요. 연동 코드 작성은 물론, 24시간 언제나 관련 질의에 대한 답변을 받을 수 있습니다. ### 릴리스 노트 - [API / SDK 2023-04-24](https://developers.portone.io/release-notes/api-sdk/2023-04-24) - [API / SDK 2023-05-08](https://developers.portone.io/release-notes/api-sdk/2023-05-08) - [API / SDK 2023-05-12](https://developers.portone.io/release-notes/api-sdk/2023-05-12) - [API / SDK 2023-05-22](https://developers.portone.io/release-notes/api-sdk/2023-05-22) - [API / SDK 2023-05-25](https://developers.portone.io/release-notes/api-sdk/2023-05-25) - [API / SDK 2023-06-19](https://developers.portone.io/release-notes/api-sdk/2023-06-19) - [API / SDK 2023-07-03](https://developers.portone.io/release-notes/api-sdk/2023-07-03) - [API / SDK 2023-07-10](https://developers.portone.io/release-notes/api-sdk/2023-07-10) - [API / SDK 2023-07-17](https://developers.portone.io/release-notes/api-sdk/2023-07-17) - [API / SDK 2023-07-31](https://developers.portone.io/release-notes/api-sdk/2023-07-31) - [API / SDK 2023-08-31](https://developers.portone.io/release-notes/api-sdk/2023-08-31) - [API / SDK 2023-12-15](https://developers.portone.io/release-notes/api-sdk/2023-12-15) - [API / SDK 2024-01-08](https://developers.portone.io/release-notes/api-sdk/2024-01-08) - [API / SDK 2024-01-11](https://developers.portone.io/release-notes/api-sdk/2024-01-11) - [API / SDK 2024-01-25](https://developers.portone.io/release-notes/api-sdk/2024-01-25) - [API / SDK 2024-01-30](https://developers.portone.io/release-notes/api-sdk/2024-01-30) - [API / SDK 2024-02-23](https://developers.portone.io/release-notes/api-sdk/2024-02-23) - [API / SDK 2024-03-08](https://developers.portone.io/release-notes/api-sdk/2024-03-08) - [API / SDK 2024-03-15](https://developers.portone.io/release-notes/api-sdk/2024-03-15) - [API / SDK 2024-03-25](https://developers.portone.io/release-notes/api-sdk/2024-03-25) - [API / SDK 2024-04-01](https://developers.portone.io/release-notes/api-sdk/2024-04-01) - [API / SDK 2024-04-05](https://developers.portone.io/release-notes/api-sdk/2024-04-05) - [API / SDK 2024-04-12](https://developers.portone.io/release-notes/api-sdk/2024-04-12) - [API / SDK 2024-05-08](https://developers.portone.io/release-notes/api-sdk/2024-05-08) - [API / SDK 2024-05-14](https://developers.portone.io/release-notes/api-sdk/2024-05-14) - [API / SDK 2024-06-03](https://developers.portone.io/release-notes/api-sdk/2024-06-03) - [API / SDK 2024-06-17](https://developers.portone.io/release-notes/api-sdk/2024-06-17) - [API / SDK 2024-06-19](https://developers.portone.io/release-notes/api-sdk/2024-06-19) - [API / SDK 2024-06-20](https://developers.portone.io/release-notes/api-sdk/2024-06-20) - [API / SDK 2024-07-04](https://developers.portone.io/release-notes/api-sdk/2024-07-04) - [API / SDK 2024-07-11](https://developers.portone.io/release-notes/api-sdk/2024-07-11) - [API / SDK 2024-09-05](https://developers.portone.io/release-notes/api-sdk/2024-09-05) - [API / SDK 2024-09-27](https://developers.portone.io/release-notes/api-sdk/2024-09-27) - [API / SDK 2024-12-19](https://developers.portone.io/release-notes/api-sdk/2024-12-19) - [API / SDK 2025-01-15](https://developers.portone.io/release-notes/api-sdk/2025-01-15) - [API / SDK 2025-05-19](https://developers.portone.io/release-notes/api-sdk/2025-05-19) - [관리자콘솔 2023-04-24](https://developers.portone.io/release-notes/console/2023-04-24) - [관리자콘솔 2023-05-08](https://developers.portone.io/release-notes/console/2023-05-08) - [관리자콘솔 2023-05-22](https://developers.portone.io/release-notes/console/2023-05-22) - [관리자콘솔 2023-07-05](https://developers.portone.io/release-notes/console/2023-07-05) - [관리자콘솔 2023-07-07](https://developers.portone.io/release-notes/console/2023-07-07) - [관리자콘솔 2023-07-17](https://developers.portone.io/release-notes/console/2023-07-17) - [관리자콘솔 2023-08-23](https://developers.portone.io/release-notes/console/2023-08-23) - [관리자콘솔 2023-09-12](https://developers.portone.io/release-notes/console/2023-09-12) - [관리자콘솔 2023-12-27](https://developers.portone.io/release-notes/console/2023-12-27) - [관리자콘솔 2024-09-05](https://developers.portone.io/release-notes/console/2024-09-05) - [관리자콘솔 2025-10-17](https://developers.portone.io/release-notes/console/2025-10-17) - [파트너 정산 자동화 2023-08-31](https://developers.portone.io/release-notes/platform/2023-08-31) - [파트너 정산 자동화 2023-11-08](https://developers.portone.io/release-notes/platform/2023-11-08) - [파트너 정산 자동화 2023-11-14](https://developers.portone.io/release-notes/platform/2023-11-14) - [파트너 정산 자동화 2023-12-15](https://developers.portone.io/release-notes/platform/2023-12-15) - [파트너 정산 자동화 2024-05-20](https://developers.portone.io/release-notes/platform/2024-05-20) - [파트너 정산 자동화 2024-05-29](https://developers.portone.io/release-notes/platform/2024-05-29) - [파트너 정산 자동화 2024-06-05](https://developers.portone.io/release-notes/platform/2024-06-05) - [파트너 정산 자동화 2024-07-05](https://developers.portone.io/release-notes/platform/2024-07-05) - [파트너 정산 자동화 2024-07-11](https://developers.portone.io/release-notes/platform/2024-07-11) - [파트너 정산 자동화 2024-07-30](https://developers.portone.io/release-notes/platform/2024-07-30) - [파트너 정산 자동화 2024-08-07](https://developers.portone.io/release-notes/platform/2024-08-07) - [파트너 정산 자동화 2024-08-22](https://developers.portone.io/release-notes/platform/2024-08-22) - [파트너 정산 자동화 2024-10-21](https://developers.portone.io/release-notes/platform/2024-10-21) - [파트너 정산 자동화 2024-11-07](https://developers.portone.io/release-notes/platform/2024-11-07) - [파트너 정산 자동화 2024-11-25](https://developers.portone.io/release-notes/platform/2024-11-25) - [파트너 정산 자동화 2024-12-10](https://developers.portone.io/release-notes/platform/2024-12-10) - [파트너 정산 자동화 2025-01-16](https://developers.portone.io/release-notes/platform/2025-01-16) - [파트너 정산 자동화 2025-02-10](https://developers.portone.io/release-notes/platform/2025-02-10) - [파트너 정산 자동화 2025-02-13](https://developers.portone.io/release-notes/platform/2025-02-13) - [파트너 정산 자동화 2025-03-04](https://developers.portone.io/release-notes/platform/2025-03-04) - [파트너 정산 자동화 2025-03-17](https://developers.portone.io/release-notes/platform/2025-03-17) - [파트너 정산 자동화 2025-04-03](https://developers.portone.io/release-notes/platform/2025-04-03) - [파트너 정산 자동화 2025-04-08](https://developers.portone.io/release-notes/platform/2025-04-08) - [파트너 정산 자동화 2025-05-14](https://developers.portone.io/release-notes/platform/2025-05-14) - [파트너 정산 자동화 2025-07-02](https://developers.portone.io/release-notes/platform/2025-07-02) - [파트너 정산 자동화 2025-07-07](https://developers.portone.io/release-notes/platform/2025-07-07) - [파트너 정산 자동화 2025-07-23](https://developers.portone.io/release-notes/platform/2025-07-23) - [파트너 정산 자동화 2025-08-13](https://developers.portone.io/release-notes/platform/2025-08-13) - [파트너 정산 자동화 2025-08-21](https://developers.portone.io/release-notes/platform/2025-08-21) - [파트너 정산 자동화 2025-08-28](https://developers.portone.io/release-notes/platform/2025-08-28) - [파트너 정산 자동화 2025-10-02](https://developers.portone.io/release-notes/platform/2025-10-02) - [파트너 정산 자동화 2026-02-19](https://developers.portone.io/release-notes/platform/2026-02-19) - [파트너 정산 자동화 2026-03-06](https://developers.portone.io/release-notes/platform/2026-03-06) ### 블로그 - [포트원 V2 이야기 - OOM 이슈 탐방기](https://developers.portone.io/blog/posts/2024-02/v2-oom): ZIO를 사용하면서 발생했던 OOM 이슈에 대해 원인을 분석합니다. - [포트원 V2 이야기 - 웹훅 재시도, 어디까지 고도화해 보셨나요?](https://developers.portone.io/blog/posts/2024-02/v2-webhook): 웹훅의 중요성과 한계점을 살펴보고 포트원 V2에서 웹훅 시스템을 고도화한 이야기를 소개합니다. - [포트원 V2 이야기 - Scala와 ZIO로 안정적인 결제 시스템 만들기](https://developers.portone.io/blog/posts/2024-02/v2-zio): 안정적인 결제 시스템을 만들기 위해 기술적으로 의사결정한 내용에 대해 소개합니다. - [포트원이 여러 PG사의 인터페이스를 연동하는 방법](https://developers.portone.io/blog/posts/2024-03/tgs): 여러 PG사의 인터페이스를 효율적으로 연동하기 위한 결정사항들을 소개합니다. - [Data Evolution: The Shift from AWS DMS to GCP Datastream](https://developers.portone.io/blog/posts/2024-04/gcp-datastream): Gives an overview of the PortOne Data Infrastructure and the migration story from AWS DMS to GCP Datastream. - [Solid로 간결하게 고성능 웹앱 만들기](https://developers.portone.io/blog/posts/2024-04/solid): 포트원에서 사용하는 프론트엔드 웹 프레임워크 중 하나인 Solid에 대해 소개하고, 포트원 내에서의 활용 사례를 다룹니다. - [포트원 V2 이야기 - Event Sourcing으로 결제 시스템 만들기 (기본편)](https://developers.portone.io/blog/posts/2024-07/v2-event-sourcing-basic): 포트원 V2 시스템의 근간을 이루고 있는 기술 중 하나인 Event Sourcing에 대해 소개합니다. - [포트원 AI 챗봇이 반복되는 기술 문의를 획기적으로 단축한 비결](https://developers.portone.io/blog/posts/2025-12/portone-chatbot): 잘 만든 AI 서비스 하나로 1000개의 기술 문의를 대신한 이야기 # https://developers.portone.io/opi/ko/console/guide/smartrouting --- title: 스마트 라우팅 description: 포트원 스마트 라우팅을 사용하기 위한 그룹 설정을 관리할 수 있습니다. 관리자콘솔 내 스마트 라우팅 그룹 설정 방법을 안내합니다. targetVersions: - v2 ---
스마트 라우팅 기능이 궁금하다면 [스마트 라우팅 기능 소개](https://developers.portone.io/opi/ko/extra/smart-routing/intro)를 확인해 보세요!
## 스마트 라우팅 그룹 생성하기 스마트 라우팅을 사용하기 위해서는 포트원 관리자콘솔 내 \[연동 관리] - \[스마트 라우팅]에서 그룹 설정이 필요합니다. 1. (관련 이미지 첨부) 포트원 콘솔 내에서 \[연동 관리] - \[스마트 라우팅]을 클릭하세요. 2. \[스마트 라우팅 그룹 생성하기]를 클릭하세요. 3. (관련 이미지 첨부) 연동할 환경을 선택하세요. \[실연동], \[테스트] 선택 시 해당 환경으로 등록된 채널만 표시됩니다. 스마트 라우팅 그룹 내에 동일한 환경의 채널끼리만 설정이 가능합니다. 4. \[그룹 이름]은 필수로 입력해야 합니다. 그룹 이름은 별칭과 같이 사용되므로 그룹의 특징을 잘 나타내는 이름으로 작성하시길 권장드립니다. 5. \[그룹 아이디]의 경우 그룹 생성 후 자동으로 채번되며, 결제 요청 시 사용됩니다. 6. \[+채널 추가]를 클릭하세요. 7. (관련 이미지 첨부) 그룹에 사용할 채널을 선택하세요. [지원 PG사 확인 바로가기](https://developers.portone.io/opi/ko/extra/smart-routing/intro?v=v2) 8. 채널은 최소 1개부터 최대 10개까지 설정이 가능합니다. 9. 채널 추가 후 **비활성화** 하는 경우 해당 채널은 입력된 비율과 상관없이 라우팅 시 배제됩니다. 10. 비율의 합은 100% 미만이거나 초과될 수 없습니다. 총 합이 100%여야만 합니다. 11. 채널 설정을 완료하였으면 \[저장] 버튼을 클릭하여 그룹을 생성합니다. ## 스마트 라우팅 그룹 수정하기 1. (관련 이미지 첨부) 생성된 그룹은 위와 같이 표시됩니다. 2. 그룹 설정을 변경하고 싶으신 경우 해당 그룹을 클릭하세요. 3. (관련 이미지 첨부) 이미 생성된 그룹 내에서 결제대행사를 추가 혹은 삭제할 수 있습니다. 4. 결제대행사별 비율을 변경할 수 있습니다. 5. \[예약 시간 설정]을 체크한 후 시간을 설정하면 변경 시점을 예약할 수 있습니다. 예약 시간은 시간 단위로 선택 가능하며, 미래 시점으로만 예약할 수 있습니다. 6. 즉시 적용을 원하시는 경우 \[예약 시간 설정]을 체크하지 않은 채 \[저장]을 클릭하세요. ## 스마트 라우팅 그룹 삭제하기 1. 수정 모드에서 \[그룹 삭제]를 클릭하세요. 2. 삭제된 그룹은 복원되지 않으며, 결제 요청 파라미터 변경 없이 그룹을 삭제하는 경우 결제가 원활하지 않을 수 있습니다. 삭제 시 신중히 진행하시길 권장드립니다. # https://developers.portone.io/opi/ko/extra/confirm-process/readme-v2 --- title: 컨펌 프로세스 description: 결제 승인 직전에 고객사 측에 결제 의사를 최종적으로 확인하는 기능입니다. targetVersions: - v2 versionVariants: v1: /opi/ko/extra/confirm-process/readme-v1 --- 결제 승인 직전에 고객사 측에 결제 의사를 최종적으로 확인하는 기능입니다.
**수동 승인 기능 안내** V2 신규 연동 시에는 컨펌 프로세스와 동일한 목적으로 사용할 수 있는 [수동 승인](https://developers.portone.io/opi/ko/extra/manual-confirm/readme-v2) 기능을 이용하시기를 권장합니다. 수동 승인은 더 간편한 연동 방식을 제공하며, 채널 설정에서 간단히 켤 수 있습니다.
## 컨펌 프로세스란? - 결제 승인 직전 고객사에 결제 승인 요청 의사를 마지막으로 확인하는 서비스입니다. - 기본적인 결제 플로우상 고객사에서 결제 요청 후 별도의 확인 없이 결제 승인되는 구조입니다. 하지만 해당 서비스 이용 시 고객사가 최종적으로 결제 승인 요청의 주체가 될 수 있습니다. (이미지 첨부: 컨펌 프로세스 플로우)
**해당 서비스가 반드시 필요한 고객사는 아래와 같은 경우입니다.** (관련 이미지 첨부) - 판매 제품의 재고가 소량으로 재고파악이 필요한 경우 (한정된 상품 또는 고가 제품 판매시) - 선착순 방식으로 결제가 진행되어야 하는 경우 - 결제 승인 전 마지막으로 고객사에서 처리하고 싶은 로직이 존재하는 경우
## 컨펌 프로세스 사용 케이스 ### 판매 제품의 재고가 소량으로 재고파악이 필요한 경우 고객사의 판매 제품이 재고가 충분하지 않을 경우 구매자가 동시에 구매를 요청할 수 있기 때문에 결제 직전 고객사 서버에서 재고 수량을 한 번 더 확인하고 수량이 있는 경우에만 결제가 승인되도록 처리할 수 있습니다.\ 만약 컨펌 프로세스를 설정하지 않는 경우 실제 결제 승인 후 재고가 부족하여 제품 발송이 늦어지거나 주문을 취소 처리가 발생하여 고객의 결제 경험 만족도를 저하시키는 상황이 반복될 수 있습니다. ![]() ### 선착순 방식으로 결제가 진행되어야 하는 경우 마라톤 참가 신청, 인기 콘서트 티켓팅 또는 OO Day 같은 특별 할인 행사처럼 특정 시간에 매우 많은 고객이 동시에 결제 요청을 하는 경우 한정된 수량을 초과하지 않도록 고객사에서 최종적으로 수량을 확인한 후 결제가 승인되도록 처리할 수 있습니다. ![]() ### 결제 승인 전 마지막으로 고객사에서 처리하고 싶은 로직이 존재하는 경우 이밖에 다른 사유로 고객사에서 결제 승인 완료 직전 자체 업무 처리가 필요한 경우(결제 직전 고객사 서버 헬스체크 등) 해당 서비스를 이용할 수 있습니다. ![]()
**컨펌 프로세스 신청 방법** 기술지원 메일()로 **상점 아이디**를 기재하여 메일 발송 포트원 콘솔 로그인 후 \[결제연동] 페이지 상단에서 상점 아이디를 확인 하실 수 있습니다.
엑심베이의 경우 컨펌 프로세스 사용이 불가능합니다.
## 컨펌 프로세스 이용 방법 컨펌 프로세스 이용시 고객사는 `PortOne.requestPayment()`, `PortOne.loadPaymentUI()` 함수 호출 시 `confirmUrl` 파라미터를 정의하고 해당 파라미터에 고객사 EndPoint URL을 설정합니다. ```json title="JavaScript SDK" { //...중략 "confirmUrl": "고객사 EndPoint URL 기재" //...중략 } ``` ## Payload Schema 콘솔에서 설정하신 웹훅 버전에 따라 상이한 형식의 payload가 송신됩니다. ### `2024-01-01` 사용 시 - `payment_id`: 고객사에서 채번한 결제건의 고유 주문 번호입니다. - `tx_id`: 포트원에서 채번한 결제건의 고유 거래 번호입니다. - `total_amount`: 결제건의 결제 요청 금액입니다. **컨펌 웹훅 payload 예시:** ```json { "payment_id": "example-payment-id", "tx_id": "55451513-9763-4a7a-bb43-78a4c65be843", "total_amount": 1000 } ``` ### `2024-04-25` 사용 시 - `type`: 웹훅을 트리거한 이벤트의 타입입니다. 컨펌 웹훅의 경우 `type`의 값은 `Transaction.Confirm`으로 고정됩니다. - `timestamp`: 해당 웹훅을 트리거한 이벤트의 발생 시각(RFC 3339 형식)입니다. - `data`: 웹훅을 트리거한 이벤트의 실제 세부 내용입니다. 컨펌 웹훅의 경우 해당 필드의 상세 스키마는 아래와 같습니다. - `paymentId`: 고객사에서 채번한 결제건의 고유 주문 번호입니다. - `transactionId`: 포트원에서 채번한 결제건의 고유 거래 번호입니다. - `totalAmount`: 결제건의 결제 요청 금액입니다. **컨펌 웹훅 payload 예시:** ```json { "type": "Transaction.Confirm", "timestamp": "2024-04-25T10:00:00.000Z", "data": { "paymentId": "example-payment-id", "transactionId": "55451513-9763-4a7a-bb43-78a4c65be843", "totalAmount": 1000 } } ``` ## SDK 실패 응답에 특정 에러 메세지 포함시키기 고객사는 재고 부족 등의 이유로 포트원이 보낸 컨펌 프로세스 요청에 실패 응답을 보낼 수 있고, 이러한 실패 사유를 서비스를 이용하는 고객들에게 보여주고 싶을 수 있습니다. 이러한 경우 Response Body에 `errorMessage` 라는 필드를 포함하여 에러 응답을 보내주시면 해당 메세지를 포함해 SDK 응답으로 리턴해드리고 있습니다. **Error Response Body 예시:** ```json { "errorMessage": "재고가 모두 소진되었습니다. 관리자에게 문의하세요." } ``` ## 컨펌 웹훅 요청 검증하기 컨펌 프로세스 웹훅 또한 다른 일반적인 웹훅과 동일한 방식으로 검사하시는 것을 권장합니다. [웹훅 연동하기 - 웹훅 요청 검증하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2#웹훅-메시지-검증하기)를 참고하셔서 컨펌 웹훅을 신뢰할 수 있는지를 검사하세요. # https://developers.portone.io/opi/ko/extra/identity-verification/readme-v2 --- title: 본인인증 연동하기 description: 포트원을 이용하여 간편하게 본인인증을 연동하는 방법을 확인합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/extra/identity-verification/v1/readme --- **본인인증 서비스**란 인증 절차를 거쳐 본인 여부와 입력한 정보의 정확성을 확인하여 주는 서비스입니다. 현재 지원하는 본인인증 서비스는 아래와 같습니다. - 다날 휴대폰 본인인증 - KCP 휴대폰 본인인증 - KG이니시스 통합인증 ## 휴대폰 본인인증 휴대폰 본인인증 서비스란 본인 명의로 개통한 휴대폰을 이용하여 최소한의 개인정보를 입력하는 인증 절차를 거쳐 본인 여부와 입력한 정보의 정확성을 확인하여 주는 서비스입니다. 고객은 웹사이트에 가입, 결제, 또는 성인 인증 등을 위해 본인인증을 시행합니다. 본인인증은 모바일 기기에 설치된 본인인증 전용 앱을 이용하거나 사용자 본인 정보(이름, 생년월일, 휴대폰번호)를 인증요청 페이지에 입력한 후 문자로 온 인증번호를 기입하는 방식으로 이루어집니다. (이미지 첨부: 휴대폰 본인인증 화면 예시) 포트원을 이용한 휴대폰 본인인증의 Flow는 JavaScript SDK를 이용하여 휴대폰 본인인증을 완료하고 고객사 서버에서 포트원 REST API를 이용하여 **인증완료정보를 획득**하는 방법으로 진행됩니다.
**API를 이용한 본인인증** 다날 및 KCP의 경우 수기결제처럼 API 호출만으로 진행하는 본인인증도 지원하고 있습니다. REST API 문서의 해당 부분 설명을 참고해 주세요.
## 통합인증 통합인증 서비스란 카카오톡 인증서, 네이버 인증서 등의 민간 인증서를 통한 인증 절차를 거쳐 본인 여부와 입력한 정보의 정확성을 확인하여 주는 서비스입니다. 통합인증은 **KG이니시스**를 통해 제공되며 민간 인증서를 이용하거나 사용자 본인이 가입된 간편인증을 통해 인증요청을 보내고 간편인증 페이지에서 인증처리를 하는 방식으로 이루어집니다. > **이용가능 수단 : 네이버 / PASS / TOSS / 금융인증서 / 카카오 / 신한 / KB모바일 / 삼성패스** (이미지 첨부: 휴대폰 본인인증 화면 예시) ## SDK를 사용한 본인인증 포트원을 이용한 본인인증의 Flow는 휴대폰 본인인증, 통합인증 모두 JavaScript SDK를 이용하여 본인인증을 완료하고 고객사 서버에서 포트원 REST API를 이용하여 **인증완료정보를 획득**하는 방법으로 진행됩니다. ### 1. 포트원 SDK 설치 포트원 SDK를 설치하는 방법은 [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/checkout) 문서를 참고하세요. ### 2. 본인인증 요청하기 SDK의 `PortOne.requestIdentityVerification()` 함수를 호출하여 본인인증창을 열 수 있습니다. 먼저, 관리자 콘솔의 결제 연동 페이지에서 **Store ID**와 사용할 채널의 **채널 키**를 확인해 주세요. 그리고 아래와 같이 파라미터들을 설정하여 호출합니다. ```ts PortOne.requestIdentityVerification({ // 고객사 storeId로 변경해주세요. storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", identityVerificationId: `identity-verification-${crypto.randomUUID()}`, // 연동 정보 메뉴의 채널 관리 탭에서 확인 가능합니다. channelKey: "channel-key-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", }); ``` **identityVerificationId**는 본인인증 건을 구분하는 문자열로, 본인인증 요청 및 조회에 필요합니다. 같은 identityVerificationId에 대해 여러 번의 본인인증 시도가 가능하나, 최종적으로 인증에 성공하는 것은 단 한 번만 가능합니다. ### 3. 본인인증 완료 처리 (브라우저) `PortOne.requestIdentityVerification()` 함수의 반환값을 통해 본인인증 요청의 결과를 확인합니다. `code`가 있으면 본인인증 과정에서 오류가 발생한 것이므로 적절히 처리하여야 합니다. 본인인증이 성공한 경우 identityVerificationId를 서버에 전달하여 서버측 본인인증 완료 처리를 하도록 합니다. ```ts const response = await PortOne.requestIdentityVerification({ /* 객체 생략 */ }); // 프로세스가 제대로 완료되지 않은 경우 에러 코드가 존재합니다 if (response.code !== undefined) { return alert(response.message); } const verificationResult = await fetch("{서버의 인증 정보를 받는 endpoint}", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ identityVerificationId, }), }); ``` 본인인증 요청 및 응답 파라미터는 [브라우저 SDK 문서](https://developers.portone.io/sdk/ko/v2-sdk/readme)를 참조해 주세요. #### 3-1. redirect 방식의 경우 모바일 환경에서의 본인인증은 대부분 redirect 방식으로 이루어집니다. redirect 방식에서는 브라우저가 본인인증창으로 리다이렉트되었다가, 인증창에서의 작업이 끝나면 지정한 `redirectUrl`로 다시 리다이렉트됩니다. 이 경우에는 함수 호출 결과를 이용할 수 없고, 인증 성공 여부 등은 [쿼리 문자열](http://en.wikipedia.org/wiki/Query_string)로 전달받게 됩니다. ```ts PortOne.requestIdentityVerification({ /* 파라미터 생략 */ redirectUrl: `${BASE_URL}/identity-verification-redirect`, }); ``` 쿼리 문자열로 전달되는 내용은 [브라우저 SDK 응답 형식](https://developers.portone.io/sdk/ko/v2-sdk/identity-verification-response)과 동일합니다. 예를 들어 identityVerificationId가 `identity-verification-39ecfa97`, redirectUrl이 `https://example.com/identity-verification-redirect`인 경우, 본인인증 성공 시에 `https://example.com/identity-verification-redirect?identityVerificationId=identity-verification-39ecfa97`로 리다이렉트됩니다. ### 4. 인증 완료 처리 (서버) 본인인증 완료 이후 획득한 `identityVerificationId`를 이용하여 고객 인증정보를 조회할 수 있습니다. ```ts title="server-side" app.use(bodyParser.json()); // "/identity-verifications"에 대한 POST 요청을 처리하는 controller app.post("/identity-verifications", async (req, res) => { // request의 body에서 identityVerificationId 추출 const { identityVerificationId } = req.body; try { // 포트원 본인인증 내역 단건조회 API 호출 const verificationResponse = await fetch({ url: `https://api.portone.io/identity-verifications/${encodeURIComponent(identityVerificationId)}`, headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, }); if (!verificationResponse.ok) throw new Error( `verificationResponse: ${await verificationResponse.json()}`, ); const identityVerification = await verificationResponse.json(); if (identityVerification.status !== "VERIFIED") { // 인증 실패 } } catch (e) { console.error(e); } }); ``` #### 인증 정보 활용하기 조회한 인증 정보에서 다음의 고객 정보를 추출하는 서비스 코드 예제입니다. 아래 파라미터들은 모두 본인인증 단건 조회의 결과가 인증 완료 상태일 때 (status = `VERIFIED`) 제공되는 `verifiedCustomer` 필드 내에 존재합니다. - `ci`: 연계 정보(Connecting Information). - 사람마다 고유하고 서비스별로 달라지지 않기 때문에, 서비스 간 연계에 사용할 수 있음. - 다날의 경우 항상 제공. - KCP의 경우 가맹점 설정에 따라 제공. - KG이니시스의 경우 카카오를 제외한 인증 업체에서 항상 제공. 카카오의 경우 별도 서류 작성이 필요합니다. - `di`: 중복 가입 확인 정보(Duplication Information). - 해당 서비스 안에서만 사람마다 고유함. - 이용자의 중복 가입을 확인하는 데 사용할 수 있음. - 다날의 경우 항상 제공. - KCP의 경우 항상 제공. - KG이니시스의 경우 제공되지 않음. - `name`: 이름 - `gender`: 성별 - 다날의 경우 항상 제공. - KCP의 경우 항상 제공. - KG이니시스의 경우 카카오톡 인증을 제외하고 항상 제공합니다. - 카카오톡 인증의 경우 인증기관 검증 절차 없이 사용자가 직접 입력한 정보를 제공합니다. - `FRGNDInfo` 파라미터를 `N`으로 설정한 경우, 카카오톡 인증 시에 성별 정보를 사용자에게 입력받지 않으며, 인증 결과에 성별을 제공하지 않습니다. [참고](https://developers.portone.io/opi/ko/integration/pg/v2/inicis-unified-identity-verification#kg이니시스-특수-파라미터-안내) - `birthDate`: 생년월일 (YYYY-MM-DD) - `operator`: 통신사 - 다날의 경우 하기 안내를 따라 추가 계약 후 제공. - KCP의 경우 항상 제공. - KG이니시스의 경우 미제공. - `phoneNumber`: 숫자로만 구성된 전화번호 - 다날의 경우 하기 안내를 따라 추가 계약 후 제공. - KCP의 경우 항상 제공. - KG이니시스의 경우 항상 제공. - `isForeigner`: 외국인 여부. - 다날의 경우 하기 안내를 따라 추가 계약 후 제공. - KCP의 경우 항상 제공. - KG이니시스의 경우 카카오톡, 네이버 인증을 제외하고 항상 제공합니다. - 카카오톡, 네이버 인증의 경우 인증기관 검증 절차 없이 사용자가 직접 입력한 정보를 제공합니다. - `FRGNDInfo` 파라미터를 `N`으로 설정한 경우, 네이버와 카카오톡 인증 시에 외국인 여부를 사용자에게 입력받지 않으며, 인증 결과에 외국인 여부를 제공하지 않습니다. [참고](https://developers.portone.io/opi/ko/integration/pg/v2/inicis-unified-identity-verification#kg이니시스-특수-파라미터-안내)
다날의 외국인(**`isForeigner`**) 여부는 **API 방식** 본인인증에 한하여 **개인정보 제공동의 약관을 사이트에 게재**한 후 **로 신청**하여 취득할 수 있습니다. 해당 부분은 당사 계약 이후 다날PG사로 요청 후 승인이 완료되면 이용 가능한 점 참고해 주시기 바랍니다. **메일 요청 신청 양식** - 상호명 : - 사업자번호 : - 본인인증용 다날 상점ID(CPID) : - 업종 : - 필요사유 : - 개인정보취급방침 url : 앱서비스로 URL형태로 전달이 어려우신 경우 '개인정보취급방침' 경로를 캡쳐하여 전달주시기 바랍니다. **참고 - 포트원 이용 고객사의 개인정보처리방침 적용 예시** - `(주)마플 : https://marpple.shop/kr/@/privacy` - `(주)브레이브모바일 / 숨고 : https://soomgo.com/terms/privacy` - `(주)마켓잇 : https://static.marketit.asia/static/privacy-terms.pdf`
```ts title="Express" // "/identity-verifications"에 대한 POST 요청을 처리하는 controller app.post("/identity-verifications", async (req, res) => { // request의 body에서 identity_verification_id 추출 const { identityVerificationId } = req.body; try { // 인증 토큰 발급 받기 // identityVerificationId로 인증 정보 조회 const { ci, di, name, gender, birthDate } = identityVerification.verifiedCustomer; // 연령 제한 로직 예시 if (new Date(birthDate).getFullYear() <= 1999) { // 연령 만족 } else { // 연령 미달 } // 1인 1계정 허용 로직 예시 if (di == null) { // PG사에서 di를 미제공 } else { // DB에서 di 조회 후 가입여부 검사 const user = await Users.find({ di }); if (user == null) { // 신규 고객 } else { // 이미 가입된 고객 } } } catch (e) { console.error(e); } }); ``` # https://developers.portone.io/opi/ko/extra/manual-confirm/readme-v2 --- title: 수동 승인 description: 고객사 서버에서 API를 호출하여 결제를 승인하는 연동 방식입니다. targetVersions: - v2 --- 포트원을 통해 PG의 결제 UI를 표시하면, 구매자는 UI에서 정보 입력 및 인증을 진행합니다. 이 과정이 끝나고 UI가 닫히면 자동으로 결제 승인(또는 가상계좌 발급, 빌링키 발급)이 일어납니다. 그러나 채널 설정에서 **수동 승인**을 켜면, 결제 UI가 완료되더라도 고객사 서버에서 포트원의 **수동 승인** API를 호출하지 않으면 결제 승인 등이 일어나지 않습니다.
**수동 승인을 사용할 수 없는 PG** 엑심베이, 페이레터 해외결제, 이지페이(KICC)의 경우 수동 승인을 지원하지 않고, 채널 설정에서도 해당 항목이 보이지 않습니다. 이는 근본적으로 위챗 결제와 같이 일부 해외 결제수단이 수동 승인을 지원하지 않기 때문입니다. 따라서 추후 포트원에 추가되는 PG가 이러한 결제수단을 지원한다면, 해당 PG에서는 수동 승인을 이용할 수 없을 가능성이 높습니다.
**컨펌 프로세스와의 비교** 수동 승인은 컨펌 프로세스와 동일한 목적의 기능이며, V2 신규 연동에서는 더 간편한 수동 승인 이용을 권장합니다. 컨펌 프로세스를 이용할 수 있는 PG의 목록도 수동 승인과 동일합니다.
## 수동 승인이 유용한 경우 - 결제 승인 전 마지막으로 재고 확인이 필요할 때 - 수량이 한정된 선착순 판매일 때 - 결제 완료 상태를 웹훅으로 수신하기보다, 직접 API를 호출해서 결제를 완료시키는 것을 선호할 때 - 수동 승인 방식으로 타 결제사를 연동한 상태에서 포트원도 같은 구조로 연동하고 싶을 때 ## 자동 승인이 유용한 경우 - 수동 승인을 지원하지 않는 PG를 이용할 때 - 수동 승인을 지원하지 않는 PG를 추후 연동할 가능성이 높을 때 (특히, 위챗 등 다양한 해외 결제수단 연동을 고려하고 있을 때) - 결제 완료 등 결제 상태를 웹훅으로 수신하는 데 불편함이 없을 때 ## 인증 결제 수동 승인 이용 방법 채널 설정에서 수동 승인을 켭니다. 수동 승인 설정은 채널별로 적용됩니다. 수동 승인이 켜진 채널로 `PortOne.requestPayment`를 호출하면 응답에 `paymentToken` 필드가 포함됩니다. (수동 승인을 켜지 않은 채널이면 `paymentToken` 필드는 포함되지 않습니다.) 이렇게 UI 호출 응답으로 받은 `paymentToken`을 이용해 서버에서 [인증 결제 수동 승인](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fconfirm) API를 호출하면 결제가 승인됩니다. (가상계좌 발급 건의 경우 수동 승인 API 호출 시에 가상계좌가 발급됩니다.) ## 빌링키 발급 수동 승인 이용 방법 채널 설정에서 수동 승인을 켭니다. 수동 승인 설정은 채널별로 적용됩니다. 수동 승인이 켜진 채널로 `PortOne.requestIssueBillingKey`나 `PortOne.requestIssueBillingKeyAndPay`를 호출하면 응답에 `billingIssueToken` 필드가 포함됩니다. (수동 승인을 켜지 않은 채널이면 `billingIssueToken` 필드는 포함되지 않습니다.) 이때 빌링키는 아직 발급된 상태가 아닙니다. 따라서 응답으로 전달되는 `billingKey` 값은 `NEEDS_CONFIRMATION`입니다. `requestIssueBillingKeyAndPay`를 사용한 경우에는 `txId` 값 또한 `NEEDS_CONFIRMATION`으로 전달됩니다. 이렇게 UI 호출 응답으로 받은 `billingIssueToken`을 이용해 서버에서 포트원 API를 호출하면 빌링키가 발급됩니다. `requestIssueBillingKeyAndPay`의 경우 빌링키 발급과 함께 초회 결제도 일어납니다. - `requestIssueBillingKey`의 경우 [빌링키 발급 수동 승인](https://developers.portone.io/api/rest-v2/payment.billingKey?v=v2#post%20%2Fbilling-keys%2Fconfirm) API를 호출합니다. - `requestIssueBillingKeyAndPay`의 경우 [빌링키 발급 및 초회 결제 수동 승인](https://developers.portone.io/api/rest-v2/payment.billingKey?v=v2#post%20%2Fbilling-keys%2Fconfirm-issue-and-pay) API를 호출합니다.
**수동 승인 API 호출 시점** 수동 승인 API는 가능한 한 즉시 호출하는 것을 권장합니다. 타임아웃 시간은 PG별로 상이하지만, 오래 대기하면 승인이 실패할 수 있습니다.
# https://developers.portone.io/opi/ko/extra/mobile-payment/readme-v2 --- title: 모바일 앱에서 결제 연동하기 description: 모바일 앱(Android, iOS, Flutter, React Native)에서 포트원 결제를 연동하는 방법을 안내합니다. targetVersions: - v2 --- 포트원은 Android, iOS, Flutter, React Native용 공식 V2 SDK를 제공하고 있으며, V2 SDK가 제공되지 않는 플랫폼이나, 앱이 이미 WebView로 구성되어 있는 경우에는 WebView에서 직접 연동할 수 있습니다. ([WebView 앱 연동 사례](https://github.com/portone-io/iamport-react-native/blob/HEAD/exampleForWebView/README.md)) ## 연동원리 모바일 앱에서 결제를 연동하기 전에, 모바일 결제가 어떻게 동작하는지 이해해야 합니다. ### 왜 WebView를 사용하는가? 대부분의 PG사(카드사, 간편결제 등)는 **웹 기반 결제 UI만 제공**합니다. 카드 번호 입력 폼, 3DS 인증, 간편결제 동의 화면은 모두 웹 페이지로 구현되어 있습니다. 따라서 모바일 앱에서도 네이티브 UI가 아닌 **WebView 안에서 결제 UI를 표시**하게 됩니다. 포트원의 모바일 SDK는 이 WebView를 자동으로 관리하는 얇은 래퍼이며, SDK 없이 연동할 경우 WebView를 직접 구성해야 합니다. ### 결제 흐름 사용자가 앱에서 결제를 시작하면 다음 과정이 진행됩니다. ```markdown 1. 앱이 WebView를 열고, 포트원 Browser SDK가 포함된 페이지를 로드 2. Browser SDK가 PG 결제 UI를 WebView에 표시 3. 사용자가 카드 정보 입력 / 간편결제 인증 진행 4. (필요시) 외부 앱 실행 — 은행 앱, 카카오페이 등 5. 외부 앱에서 인증 완료 → Deep Link로 앱 복귀 6. PG가 결제 결과와 함께 redirectUrl로 리다이렉트 7. 앱이 리다이렉트를 가로채서 결과 추출 8. 서버에서 결제 검증 후 주문 완료 ``` 포트원 모바일 SDK는 1\~7단계를 자동으로 처리합니다. ### 웹 결제와의 차이점 `PortOne.requestPayment()`는 결제창이 뜨기 전에 발생하는 오류(파라미터 형식 오류, 네트워크 통신 실패 등)를 Promise에서 throw합니다. 이는 모바일 WebView에서도 동일하지만, 결제 결과는 웹 브라우저와 달리 **리다이렉트 방식**으로 받아야 합니다. ```typescript PortOne.requestPayment({ // ... 결제 파라미터 redirectUrl: "myapp://payment-complete", appScheme: "myapp://", }); ``` 1. `redirectUrl`에 결제 완료 후 리다이렉트될 URL을 지정합니다. 결제 내에서 사용하지 않을 URL이면 됩니다. 2. `appScheme`에 앱의 URL scheme을 지정합니다. 이 값은 카드사 앱에 전달되어, 인증 완료 후 앱으로 복귀할 때 사용됩니다. 3. 결제 완료 시 WebView가 `redirectUrl`로 이동하며, 쿼리 파라미터에 결제 결과가 포함됩니다. 4. 앱이 이 URL을 가로채서 쿼리 파라미터에서 결과를 추출합니다.
모바일 결제에서는 `redirectUrl` 설정이 필수입니다. 설정하지 않으면 결제 UI가 정상적으로 표시되지 않을 수 있습니다.
결제 파라미터에 대한 자세한 내용은 [리다이렉트 방식의 경우](https://developers.portone.io/opi/ko/integration/start/v2/checkout?v=v2#3-1-리다이렉트-방식의-경우) 문서를 참고하세요.
### 외부 앱 처리 결제 도중 PG사의 결제 페이지가 카드사 앱카드, ISP 인증, 계좌이체 앱 등을 실행하기 위해 `kftc-bankpay://`, `ispmobile://`, `intent://` 같은 URL로 WebView를 이동시키는 경우가 있습니다. **모바일 브라우저**(Safari, Chrome)에서는 이러한 커스텀 URL scheme을 만나면 OS에 자동으로 전달하여 해당 앱을 실행합니다. 하지만 **앱 내 WebView는 웹 콘텐츠 렌더링 전용**이므로 이 동작이 기본적으로 지원되지 않습니다. - iOS `WKWebView`: HTTP/HTTPS가 아닌 scheme으로의 네비게이션을 차단합니다. - Android `WebView`: 알 수 없는 scheme에 대해 오류 페이지(`ERR_UNKNOWN_URL_SCHEME`)를 표시합니다. 따라서 WebView의 URL 네비게이션 이벤트를 가로채서, 네이티브 코드에서 OS API를 호출하여 외부 앱을 직접 실행해야 합니다. |URL 유형 |예시 |처리 방법 | |-------------------|--------------------|--------------------------| |일반 웹 URL |`https://...` |WebView에서 정상 로드 | |PG/카드사 앱 scheme|`kftc-bankpay://...`|해당 외부 앱 실행 | |Android Intent |`intent://...` |Intent URI 파싱 후 앱 실행| |커스텀 scheme |`myapp://...` |결제 완료 — 결과 추출 | 포트원 모바일 SDK는 이 URL 인터셉트 및 외부 앱 실행을 자동으로 처리합니다. ## SDK를 사용한 연동 포트원은 Android, iOS, React Native, Flutter용 공식 모바일 SDK를 제공합니다. SDK가 위 연동원리에서 설명한 WebView 생성, 외부 앱 실행, 결제 결과 수신을 모두 자동으로 처리하므로 가장 간편한 연동 방식입니다. SDK를 지원하는 플랫폼이라면 SDK를 사용하는 것을 권장합니다. |플랫폼 |SDK |설치 방법 |레퍼런스 | |------------|---------------------------|---------------------|--------------------------------------------------------| |Android |`android-sdk` |JitPack |[GitHub](https://github.com/portone-io/android-sdk) | |iOS |`PortOneSDK` |Swift Package Manager|[GitHub](https://github.com/portone-io/ios-sdk) | |React Native|`@portone/react-native-sdk`|npm |[GitHub](https://github.com/portone-io/react-native-sdk)| |Flutter |`portone_flutter` |pub.dev |[GitHub](https://github.com/portone-io/portone_flutter) |
각 SDK의 설치 및 사용법은 [모바일 SDK 레퍼런스](https://developers.portone.io/sdk/ko/v2-mobile-sdk/readme)를 참고하세요.
다양한 플랫폼의 연동 예시는 [portone-sample GitHub 저장소](https://github.com/portone-io/portone-sample)에서 확인하실 수 있습니다.
--- ## SDK 없이 직접 연동하기 V2 SDK가 제공되지 않는 플랫폼이나 WebView를 직접 제어하고 싶은 경우, 아래 단계를 따라 연동할 수 있습니다. ### Step 1. 의존성 설치 WebView를 표시하고 외부 앱을 실행하기 위한 라이브러리를 설치합니다.
```yaml title="pubspec.yaml" dependencies: flutter_inappwebview: ^6.1.5 # WebView url_launcher: ^6.3.1 # 외부 앱 실행 ``` ```shell flutter pub get ```
Android의 `WebView`는 기본 제공되므로 별도 의존성이 필요하지 않습니다. `build.gradle`에서 minSdk 21 이상을 확인하세요. ```kotlin title="build.gradle.kts" android { defaultConfig { minSdk = 21 } } ```
iOS의 `WKWebView`는 WebKit 프레임워크에 기본 포함되어 있으므로 별도 의존성이 필요하지 않습니다. 배포 대상은 iOS 14 이상을 권장합니다.
`react-native-webview`로 WebView를 표시하고, `Linking` API로 외부 앱을 실행합니다. ```shell npm install react-native-webview ``` iOS의 경우 추가로 Pod을 설치합니다. ```shell cd ios && pod install ```
### Step 2. 플랫폼 필수 설정 결제 과정에서 은행 앱, 간편결제 앱 등 외부 앱이 실행됩니다. OS 정책상 실행 가능한 외부 앱을 사전에 선언해야 하며, **이 설정이 없으면 외부 앱 실행이 실패합니다.**
Flutter와 React Native는 크로스 플랫폼 프레임워크이므로 Android와 iOS 설정을 **모두** 적용해야 합니다.
Flutter 프로젝트에서는 각 플랫폼의 네이티브 설정 파일에 직접 추가합니다. - **Android**: `android/app/src/main/AndroidManifest.xml` — Android 탭의 `queries` 내용을 추가합니다. - **iOS**: `ios/Runner/Info.plist` — iOS 탭의 `LSApplicationQueriesSchemes`와 `CFBundleURLTypes` 내용을 추가합니다.
Android 11(API 30) 이상에서는 **패키지 가시성** 정책에 따라 AndroidManifest.xml에 결제 앱 패키지를 선언해야 합니다. ```xml title="AndroidManifest.xml" ``` 앱이 외부 결제 앱에서 복귀할 수 있도록 커스텀 URL scheme도 등록합니다. 결제를 시작하는 Activity의 `intent-filter`에 앱의 URL scheme을 추가합니다. ```xml title="AndroidManifest.xml" ```
Info.plist에 `LSApplicationQueriesSchemes`를 등록하여 결제 앱의 URL scheme을 선언해야 합니다. iOS 15 이상에서는 최대 50개까지 등록할 수 있으므로, 필요한 항목만을 추가합니다. ```xml title="Info.plist" LSApplicationQueriesSchemes kftc-bankpay ispmobile hdcardappcardansimclick shinhan-sr-ansimclick shinhan-sr-ansimclick-payco shinhan-sr-ansimclick-lpay kb-acp kbbank mpocket.online.ansimclick lotteappcard lmslpay cloudpay nhallonepayansimclick citimobileapp kakaotalk payco com.wooricard.wcard newsmartpib supertoss naversearchthirdlogin kakaobank tauthlink ktauthexternalcall upluscorporation kn-bankpay yonseipay line alipays alipayhk weixin ascendmoney ``` 앱이 외부 결제 앱에서 복귀할 수 있도록 커스텀 URL scheme도 등록합니다. ```xml title="Info.plist" CFBundleURLTypes CFBundleURLSchemes myapp ```
React Native 프로젝트에서는 각 플랫폼의 네이티브 설정 파일에 직접 추가합니다. - **Android**: `android/app/src/main/AndroidManifest.xml` — Android 탭의 `queries` 내용을 추가합니다. - **iOS**: `ios/<프로젝트명>/Info.plist` — iOS 탭의 `LSApplicationQueriesSchemes`와 `CFBundleURLTypes` 내용을 추가합니다.
### Step 3. WebView에서 결제 페이지 로드 WebView를 생성하고 포트원 Browser SDK가 포함된 HTML을 로드합니다. `redirectUrl`에 결제 완료 후 리다이렉트될 URL을, `appScheme`에 카드사 앱 등에서 복귀할 때 사용할 앱 URL scheme을 지정합니다.
WebView에 HTML 텍스트를 직접 로드하는 경우 `data:` 또는 `file:` 등의 opaque URL이 사용됩니다. 이 상태에서 `postMessage`를 사용하면 [정상 동작하지 않을 수 있으니](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#targetorigin) 주의하세요. `baseUrl`을 `https://` URL로 임의 설정하여 해소할 수 있습니다.
```html ```
위 예시는 이해를 돕기 위한 최소 구성입니다. 실제 연동 시에는 [결제대행사별 연동 가이드](https://developers.portone.io/opi/ko/integration/pg/v2/readme?v=v2)및 [브라우저 SDK 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/payment-request?v=v2)에 따라 파라미터를 추가하세요.
Android `WebView`는 JavaScript가 기본 비활성화이므로 `settings.javaScriptEnabled = true` 설정이 필요합니다. (iOS `WKWebView`와 Flutter `InAppWebView`는 기본 활성화입니다.) 결제 완료 시 WebView가 `redirectUrl`로 이동하므로, 다음 Step의 URL 네비게이션 처리에서 해당 URL을 구분할 수 있어야 합니다.
### Step 4. URL 네비게이션 처리 WebView에서 발생하는 URL 네비게이션을 프로토콜별로 분기 처리해야 합니다. 아래 코드는 분기 처리의 핵심 로직만 발췌한 것입니다. |URL 프로토콜 |처리 방법 | |------------------------------------------|-------------------------------------------| |`http://`, `https://` |WebView에서 정상 로드 | |커스텀 scheme (`myapp://`) |결제 완료 — URL 쿼리 파라미터에서 결과 추출| |`intent://` (Android) |Intent URI를 파싱하여 해당 앱 실행 | |PG/카드사 앱 scheme (`kftc-bankpay://` 등)|해당 외부 앱 실행 |
엑심베이 GCash 결제는 `intent://`나 `gcash://`가 아닌 `https://gcash.onelink.me` URL을 사용하며, 이때 `gcash://com.mynt.gcash/app`을 직접 호출해야 합니다. 자세한 처리는 [React Native SDK의 해당 부분](https://github.com/portone-io/react-native-sdk/blob/03dac55/src/SdkDelegate.tsx#L96-L103)을 참고하세요.
`InAppWebView`의 `shouldOverrideUrlLoading` 콜백에서 URL scheme별로 분기합니다.
전체 동작하는 예시는 [portone\_flutter SDK의 portone\_webview.dart](https://github.com/portone-io/portone_flutter/blob/233b101/lib/v2/widget/portone_webview.dart#L114-L151)를 참고하세요. ```dart InAppWebView( initialSettings: InAppWebViewSettings( useShouldOverrideUrlLoading: true, resourceCustomSchemes: ["intent"], ), shouldOverrideUrlLoading: (controller, navigateAction) async { // URI 파서는 플랫폼마다 동작이 다를 수 있으므로 (예: 페이북), // rawValue에서 직접 protocol을 추출합니다. final uri = navigateAction.request.url!.rawValue; var protocol = uri.substring(0, uri.indexOf(':')); switch (protocol) { case 'http': case 'https': return NavigationActionPolicy.ALLOW; case 'myapp': // 결제 완료 — 쿼리 파라미터에서 결과 추출 return NavigationActionPolicy.CANCEL; case 'intent': // intent:// URI에서 scheme을 추출하여 앱 실행 // 미설치 시 마켓으로 이동 return NavigationActionPolicy.CANCEL; default: // PG/카드사 앱 등 외부 앱 실행 if (await canLaunchUrlString(uri)) launchUrlString(uri); return NavigationActionPolicy.CANCEL; } }, ) ```
`WebViewClient`의 `shouldOverrideUrlLoading`에서 URL scheme별로 분기합니다.
전체 구현은 [Android SDK의 PortOneWebView.kt](https://github.com/portone-io/android-sdk/blob/c3aeec4/sdk/src/main/java/io/portone/sdk/android/PortOneWebView.kt#L75-L111)를 참고하세요. ```kotlin webView.settings.javaScriptEnabled = true webView.webViewClient = object : WebViewClient() { override fun shouldOverrideUrlLoading( view: WebView, request: WebResourceRequest ): Boolean { val url = request.url return when (url.scheme) { "http", "https" -> false // WebView에서 정상 로드 "myapp" -> { // 결제 완료 — 쿼리 파라미터에서 결과 추출 handlePaymentResult(url) true } "intent" -> { // Intent URI 파싱 후 앱 실행, 미설치 시 마켓 이동 launchIntentOrMarket(url) true } else -> { // PG/카드사 앱 등 외부 앱 실행 startActivity(Intent(Intent.ACTION_VIEW, url)) true } } } } ```
`WKNavigationDelegate`의 `decidePolicyFor`에서 URL scheme별로 분기합니다.
전체 구현은 [iOS SDK의 PaymentWebView.swift](https://github.com/portone-io/ios-sdk/blob/a88175c/Sources/PortOneSdk/PaymentWebView.swift#L117-L181)를 참고하세요. ```swift func webView( _ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void ) { guard let url = navigationAction.request.url else { decisionHandler(.allow) return } switch url.scheme { case "http", "https": decisionHandler(.allow) case "myapp": // 결제 완료 — 쿼리 파라미터에서 결과 추출 handlePaymentResult(url: url) decisionHandler(.cancel) default: // PG/카드사 앱 등 외부 앱 실행 UIApplication.shared.open(url) decisionHandler(.cancel) } } ```
`react-native-webview`의 `onShouldStartLoadWithRequest`에서 URL scheme별로 분기합니다.
전체 구현은 [React Native SDK의 SdkDelegate.tsx](https://github.com/portone-io/react-native-sdk/blob/deea773/src/SdkDelegate.tsx#L83-L156)를 참고하세요. ```tsx import { Linking } from "react-native"; import { WebView } from "react-native-webview"; { const url = request.url; const protocol = url.split(":", 2)[0]; switch (protocol) { case "http": case "https": return true; case "myapp": // 결제 완료 — 쿼리 파라미터에서 결과 추출 handlePaymentResult(url); return false; case "intent": // intent:// URI에서 scheme을 추출하여 앱 실행 // 미설치 시 마켓으로 이동 launchIntentOrMarket(url); return false; default: // PG/카드사 앱 등 외부 앱 실행 Linking.openURL(url).catch(() => {}); return false; } }} />; ```
### Step 5. 결제 결과 처리 결제가 완료되면 `redirectUrl`로 리다이렉트되며, 쿼리 파라미터에 결제 결과가 포함됩니다. 파라미터에 대한 자세한 내용은 [리다이렉트 방식의 경우](https://developers.portone.io/opi/ko/integration/start/v2/checkout?v=v2#3-1-리다이렉트-방식의-경우) 문서를 참고하세요.
`redirectUrl`로 이동하기 전에 앱이 종료되는 경우도 있습니다. 이 경우 앱이 결제 종료를 서버에 알릴 수 없으므로, 서버에서 [웹훅](https://developers.portone.io/opi/ko/integration/start/v2/checkout#5-웹훅-연동하기) 또는 [수동 승인](https://developers.portone.io/opi/ko/integration/start/v2/checkout#3-1-리다이렉트-방식의-경우) 기능을 함께 사용하는 것을 권장합니다.
클라이언트 측 결제 결과만으로 주문을 확정하면 안됩니다. 서버에서 [결제 조회 API](https://developers.portone.io/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D)를 호출하여 결제 상태와 금액을 검증해야 합니다.
서버 측 결제 검증 방법은 [인증 결제 연동하기 - 결제 완료 처리 (서버)](https://developers.portone.io/opi/ko/integration/start/v2/checkout#4-결제-완료-처리-서버)를 참고하세요. ## 참고 링크 - [모바일 SDK 레퍼런스](https://developers.portone.io/sdk/ko/v2-mobile-sdk/readme) - [결제 연동 샘플 프로젝트](https://github.com/portone-io/portone-sample) - [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/checkout) (웹 결제 연동 가이드) - [결제 조회 API](https://developers.portone.io/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D) (서버 측 검증) # https://developers.portone.io/opi/ko/integration/cancel/v2/readme --- title: 결제취소(환불) 연동하기 description: 포트원 V2 결제취소 API를 이용한 결제취소 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/cancel/v1/basic --- ## 결제 취소 정책
**중요: 결제와 취소는 반드시 포트원 대시보드나 API를 통해서만 진행하세요** PG사를 통해 직접 취소할 경우 포트원과 결제 상태가 동기화되지 않아 데이터 불일치 문제가 발생할 수 있습니다.
### 가상계좌 환불
**가상계좌 환불을 위해서는 PG사 가상계좌 특약서비스에 가입되어 있어야 합니다.** 신용카드와는 달리 가상계좌의 경우 결제/환불에 대한 수수료는 환불대상에서 제외됩니다. 예를 들어 10,000원 결제건에 대해서 고객사는: - 결제 시: 9,700원(10,000원 - 가상계좌 발행 수수료 300원)을 PG사로부터 정산받습니다. - 환불 시: 10,300원(환불되어야할 10,000원 + 환불 계좌로의 송금 수수료 300원)을 PG사로 지불합니다. PG사는 이런 과정에서 발생할 수 있는 혼란을 미연에 방지하고자 **가상계좌 특약서비스에 가입한 고객사에 한해서만 가상계좌 환불을 제공**하고 있습니다. 단, **토스페이먼츠**의 경우 별도의 특약 가입 없이도 가상계좌 환불이 가능합니다. 이 경우 환불 시 기존 거래에서 발생한 수수료는 환불되지 않습니다.
- **필수 정보**: 환불 계좌 정보 (`refundAccount.bank`, `refundAccount.number`, `refundAccount.holderName`) - 가상계좌는 단방향 결제수단이므로 환불 계좌 지정이 필수입니다 - 스마트로 가상계좌는 `refundAccount.holderPhoneNumber`도 필수입니다 - **처리 시간**: 영업일 기준 1\~2일 - **취소 기한**: 제한 없음 - **수수료**: 건당 300원 (결제 수수료와 별도) ### 휴대폰 소액결제 - **취소 기한**: 결제월과 취소월이 동일한 경우에만 가능 ### 카드 - **취소 기한**: 통상 1년 (카드사별 상이) ### 카카오페이 - **취소 기한**: 카드 1년 이내 / 머니 5년 이내 ### 네이버페이 - **취소 기한**: 결제일로부터 1095일 이내 ### 페이팔 - **취소 기한**: 180일 이내 (판매자 동의 필요)
결제 수단별 자세한 취소 정책은 [포트원 헬프센터](https://help.portone.io/content/cancel-deadline-by-paymethod)를 참고하세요.
## 결제 취소 API 호출 자세한 설명은 [결제 취소 API](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fcancel) 문서를 참고하세요. ### 전액 취소
```bash curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \ -H 'Authorization: PortOne {API_SECRET}' \ -H 'Content-Type: application/json' \ -d '{"reason":"고객 요청"}' ```
```ts import { PaymentClient } from "@portone/server-sdk"; const paymentClient = PaymentClient({ secret: "your-api-secret", }); // ... 생략 ... try { const response = await paymentClient.cancelPayment({ paymentId: "payment-id", reason: "고객 요청", }); console.log(response); } catch (error) { console.error(error); } ```
#### 주요 파라미터 - paymentId: string **결제 건 아이디** - reason: string **취소 사유** ### 부분 취소
```bash curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \ -H 'Authorization: PortOne {API_SECRET}' \ -H 'Content-Type: application/json' \ -d '{"reason":"고객 요청","currentCancellableAmount":10000,"amount":3000}' ```
```ts import { PaymentClient } from "@portone/server-sdk"; const paymentClient = new PaymentClient({ secret: "your-api-secret", }); // ... 생략 ... try { const response = await paymentClient.cancelPayment({ paymentId: "payment-id", reason: "고객 요청", currentCancellableAmount: 10000, // 검증용 잔액 값 amount: 3000, // 취소할 금액 }); console.log(response); } catch (error) { console.error(error); } ```
#### 주요 파라미터 - paymentId: string **결제 건 아이디** - reason: string **취소 사유** - amount?: integer (64 bit) **취소할 금액** 취소할 금액을 지정합니다. 지정하지 않으면 전액 취소가 진행됩니다. - currentCancellableAmount?: integer (64 bit) **결제 건의 취소 가능 잔액** 본 취소 요청 이전의 취소 가능 잔액으로써, 값을 입력하면 잔액이 일치하는 경우에만 취소가 진행됩니다. 값을 입력하지 않으면 별도의 검증 처리를 수행하지 않습니다. ### 가상계좌 환불
```bash curl -X POST 'https://api.portone.io/payments/{paymentId}/cancel' \ -H 'Authorization: PortOne {API_SECRET}' \ -H 'Content-Type: application/json' \ -d '{ "reason": "고객 요청", "refundAccount": { "bank": "BANK_OF_KOREA", "number": "1234567890", "holderName": "홍길동", "holderPhoneNumber": "01012345678" } }' ```
```ts import { PaymentClient } from "@portone/server-sdk"; const paymentClient = PaymentClient({ secret: "your-api-secret", }); // ... 생략 ... try { const response = await paymentClient.cancelPayment({ paymentId: "payment-id", reason: "고객 요청", refundAccount: { bank: "BANK_OF_KOREA", number: "1234567890", holderName: "홍길동", holderPhoneNumber: "01012345678", // 스마트로 가상계좌 취소 시 필수 }, }); console.log(response); } catch (error) { console.error(error); } ```
#### 주요 파라미터 - paymentId: string **결제 건 아이디** - reason: string **취소 사유** - refundAccount?: object **환불 계좌 정보** - bank: string **계좌 은행** [Bank](https://developers.portone.io/api/rest-v2/payment#Bank) 타입 참고 - number: string **계좌 번호** - holderName: string **예금주** - holderPhoneNumber?: string **예금주 연락처** 스마트로 가상계좌 결제인 경우에 필요합니다. ### 프로모션 적용 주문건 취소 프로모션이 적용된 결제 건의 취소는 [프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund) 문서를 참고하세요. ## 결제 취소 API 결과 처리 자세한 설명은 [결제 취소 API](https://developers.portone.io/api/rest-v2/payment?v=v2#post%20%2Fpayments%2F%7BpaymentId%7D%2Fcancel) 문서를 참고하세요. ```ts try { const response = await paymentClient.cancelPayment({ paymentId: "payment-id", reason: "고객 요청", // ... 생략 ... }); if (isUnrecognizedPaymentCancellation(response.cancellation)) { console.error(`취소 실패: ${response.cancellation.status}`); } else if (response.cancellation.status === "SUCCEEDED") { console.log("취소 완료"); } else if (response.cancellation.status === "FAILED") { console.error("취소 실패"); } else if (response.cancellation.status === "REQUESTED") { console.log("취소 요청 완료"); } } catch (error) { console.error("취소 실패:", error); } ``` ## 웹훅을 통한 결제 취소 결과 수신 관리자콘솔을 통한 취소를 포함하여 비동기로 처리되는 취소 요청이나 취소 상태 변경을 실시간으로 알림받으려면 웹훅을 설정해야 합니다. 웹훅 연동 방법은 [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2) 문서를 참고하세요. ### 결제 취소 관련 웹훅 이벤트 - `Transaction.CancelPending`: (결제 취소가 비동기로 수행되는 경우) **결제 취소를 요청**했을 때 - `Transaction.PartialCancelled`: **결제가 부분 취소**되었을 때 - `Transaction.Cancelled`: **결제가 완전 취소**되었을 때 ### 웹훅 처리 예제 ```ts import * as PortOne from "@portone/server-sdk"; import bodyParser from "body-parser"; import express from "express"; const app = express(); // 웹훅 검증 시 텍스트로 된 body가 필요합니다. app.use( "/webhook", bodyParser.text({ type: "application/json", }), ); app.post("/webhook", async (req, res) => { try { // 웹훅 검증 const webhook = await PortOne.Webhook.verify( process.env.PORTONE_WEBHOOK_SECRET, req.body, req.headers, ); // 취소 이벤트 처리 if ( webhook.type === "Transaction.Cancelled" || webhook.type === "Transaction.PartialCancelled" ) { const { paymentId, cancellationId } = webhook.data; console.log( `${paymentId} 결제가 취소되었습니다. 취소 ID: ${cancellationId}`, ); } res.status(200).send("OK"); } catch (error) { if (error instanceof PortOne.Webhook.WebhookVerificationError) { console.error("웹훅 검증 실패:", error.message); } else { console.error("웹훅 처리 중 오류 발생:", error); } res.status(400).send("Bad Request"); } }); ``` ## 관련 문서 - [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2): 결제 취소 알림을 받기 위한 웹훅 설정 - [결제 연동 시작하기](https://developers.portone.io/opi/ko/integration/start/v2/readme): 기본적인 결제 연동 방법 - [프로모션 결제 취소하기](https://developers.portone.io/opi/ko/extra/promotion/refund): 프로모션이 적용된 결제의 취소 방법 - [관리자 콘솔 가이드](https://help.portone.io/content/cancel-guide-using-admin-console): 관리자콘솔을 통해 결제 취소하는 방법 # https://developers.portone.io/opi/ko/integration/pg/v2/danal-identity-verification --- title: 다날 본인인증 description: 다날 본인인증 연동 방법을 안내합니다. targetVersions: - v2 --- ## 다날 본인인증 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## SDK 방식으로 본인인증하기 - [본인인증 연동하기](https://developers.portone.io/opi/ko/extra/identity-verification/readme-v2) 페이지의 내용을 참고하여 연동을 진행합니다. ### 전화번호 고정하기 `customer.phoneNumber` 값을 채워 요청을 보내면 본인인증 창에서 해당 값으로 전화번호가 고정됩니다. > 전화번호를 입력하실 때에는 `-` 없이 숫자만 입력해주세요. ### 이름 고정하기 `customer.fullName` 혹은 (`customer.firstName` + `customer.lastName`) 값을 채워 보내면 본인인증 창에서 해당 값으로 이름이 고정됩니다. > `customer.firstName` 과 `customer.lastName` 을 이용하실 경우엔 성을 `lastName`에, 이름을 `firstName`에 입력해주세요. > > ex) 이름이 "**홍길동**"인 경우: `customer.lastName == '홍'` & `customer.firstName == '길동'` ## API 방식으로 본인인증하기 - [본인인증 관련 API](https://developers.portone.io/api/rest-v2/identityVerification) 페이지의 내용을 참고하여 연동을 진행합니다. ## 다날 특수 파라미터 안내 포트원에서는 `bypass` 파라미터를 통해 다날에서 특수하게 지원하는 파라미터들을 입력할 수 있도록 지원하고 있습니다. - `IsCarrier`: (SDK) 본인인증 창이 열렸을 때, 해당 통신사만 활성화시킬 수 있습니다. - `AGELIMIT`: (SDK, API) 본인인증을 진행할 수 있는 최소 만 나이를 설정할 수 있습니다. - `CPTITLE`: (SDK, API) 고객사 서비스 URL 혹은 본인확인 기능 사용 경로를 입력할 수 있습니다. SDK, API 에서 각각 아래와 같은 방식으로 특수 파라미터들을 입력하실 수 있습니다.
```ts // 필요한 파라미터를 선택하여 입력해주세요. const danalBypass = { danal: { IsCarrier: "KTF", AGELIMIT: 20, CPTITLE: "www.MarketA.co.kr", }, }; ```
SDK의 `requestIdentityVerification` 함수의 파라미터 중 `bypass` 필드에 아래와 같이 값을 채울 수 있습니다. ```ts PortOne.requestIdentityVerification({ /* 기타 파라미터 생략 */ bypass: danalBypass, }); ```
[본인인증 요청 API](https://developers.portone.io/api/rest-v2/identityVerification#post%20%2Fidentity-verifications%2F%7BidentityVerificationId%7D%2Fsend)를 사용할 경우, bypass 필드에 아래 Json을 Stringify 해서 입력하셔야 합니다. ```ts await axios({ url: `https://api.portone.io/identity-verifications/${encodeURIComponent(identityVerificationId)}/send`, method: "post", headers: { "Content-Type": "application/json" }, data: { /* 기타 파라미터 생략 */ bypass: danalBypass, }, }); ```
### `IsCarrier` 파라미터 사용 시 유의사항 가능한 값: `SKT`, `KTF`, `LGT`, `MVNO` 여러 개의 통신사를 활성화시키려면 위 값들을 semicolon(`;`) 으로 이어야 합니다. ex) `SKT;KTF` ### `CPTITLE` 파라미터 사용 시 유의사항 본인인증 동작에 영향을 주지는 않지만, KISA의 ePrivacy Clean 서비스 연동을 위해 설정을 권장합니다. 해당 값 설정에 대한 가이드는 아래와 같습니다. - 본인확인 기능을 앱에서만 사용하는 경우 서비스 홈 URL 입력. Ex) `m.login.MarketC.co.kr` - 본인확인 기능을 사용하는 웹 페이지가 존재할 경우 해당 URL 입력. Ex) `www.MarketA.co.kr` - 웹 서비스 URL 자체가 존재하지 않는 경우 서비스 이름 (app 이름) 입력. Ex) `마켓A` 해당 값을 넘기지 않을 경우 `포트원`으로 default 값을 채웁니다. ## 일반 파라미터 유의사항 안내 ### `customer.id` 파라미터 사용 시 유의사항 고객의 식별 아이디를 입력할 때에는 글자수 200자 이내로 제한됩니다. # https://developers.portone.io/opi/ko/integration/pg/v2/eximbay-v2 --- title: 엑심베이 description: 엑심베이 결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. - V2 결제 모듈을 사용하시려면 엑심베이 신모듈로 연동하셔야 합니다. ## 해외결제 차지백 웹훅 등록 - 해외결제 차지백 웹훅을 수신하기 위해서는 엑심베이에 웹훅 URL로 `https://tx-gateway-service.prod.iamport.co/eximbay-v2`를 등록해 주셔야 합니다. - 웹훅 URL을 등록하신 후 받으신 웹훅 시크릿 키를 채널 정보에 입력해 주세요. ## 가능한 결제수단 엑심베이의 경우 포트원의 결제수단 구분과 상관없이 MID에 설정된 여러 결제수단을 표시할 수 있습니다. `payMethod`를 생략하고, 특정 결제수단만을 노출할 경우 `bypass.eximbay_v2`를 사용해야 합니다. - MID에 설정된 기본 결제수단을 전부 표시하려면 `bypass.eximbay_v2.payment`를 생략해야 합니다. - 특정 결제수단을 단독으로 표시하려면 `bypass.eximbay_v2.payment.payment_method`를 설정합니다. - 일부 결제수단만을 표시하려면 `bypass.eximbay_v2.payment.multi_payment_method`에 결제수단 목록을 전달합니다. - 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 엑심베이 채널 사용을 명시해주세요. 엑심베이 기준으로 작성한 예제 코드는 아래와 같습니다.
```javascript 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: "PortOne Purchase", totalAmount: 100, // 1 USD currency: "USD", customer: { fullName: "PortOne", email: "test@example.com", }, }); } ```
### 주요 파라미터 - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - locale?: Locale **결제창 언어** - `KO_KR`: 한국어 - `EN_US`: 영어 - `JA_JP`: 일본어 - `ZH_CN`: 중국어 (중국 본토) - `ZH_TW`: 중국어 (대만) - `TH_TH`: 타이어 - `VI_VN`: 베트남어 - 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 **구매자 이메일 주소** 결제 완료 메일이 발송됩니다. - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbay\_v2?: object **엑심베이 특수 파라미터** - payment?: object - payment\_method?: string **결제수단 단독 노출** 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. - multi\_payment\_method?: string\[] **결제수단 노출 목록** 여러 결제수단을 노출합니다. - merchant?: object - shop?: string **상점명** - partner\_code?: string **파트너 코드** - tax?: object - receipt\_status?: string **현금영수증 발급 여부** - `Y`: 발급 - `N`: 미발급 네이버페이 결제 시 필수 입력이며, 계좌이체 사용 시에는 반드시 `Y`로 입력해야 합니다. - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unit\_price?: string **단가 (음수 가능)** - ship\_to?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **수신인의 성을 제외한 이름** - last\_name?: string **수신인의 성** - phone\_number?: string **수신인 전화번호** - postal\_code?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - bill\_to?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **청구 카드 명의자의 성을 제외한 이름** - last\_name?: string **청구 카드 명의자의 성** - phone\_number?: string **청구 카드 명의자의 전화번호** - postal\_code?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** - settings?: object - call\_from\_app?: string **모바일 앱 내에서 결제를 연동할 경우 설정** - `Y`: 모바일 앱 환경인 경우 - `N`: 모바일 앱 환경이 아닌 경우 - issuer\_country?: string **해외 결제 가맹점에서 국내 결제를 사용할 경우 `KR`** - virtualaccount\_expiry\_date?: string **입금 만료 일자 (yyyyMMddHH)** ## SDK 빌링키 발급 및 결제 요청하기 엑심베이의 경우 빌링키 발급과 동시에 최초 결제가 일어나며, `requestIssueBillingKeyAndPay` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 엑심베이 채널 사용을 명시해주세요. 엑심베이 기준으로 작성한 예제 코드는 아래와 같습니다.
```javascript import * as PortOne from "@portone/browser-sdk/v2"; function issueBillingKeyAndPay() { PortOne.requestIssueBillingKeyAndPay({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "PortOne Recurring Payment", totalAmount: 100, // 1 USD currency: "USD", customer: { fullName: "PortOne", email: "test@example.com", }, }); } ```
### 주요 파라미터 - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - locale?: Locale **결제창 언어** - `KO_KR`: 한국어 - `EN_US`: 영어 - `JA_JP`: 일본어 - `ZH_CN`: 중국어 (중국 본토) - `ZH_TW`: 중국어 (대만) - `TH_TH`: 타이어 - `VI_VN`: 베트남어 - 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 **구매자 이메일 주소** 결제 완료 메일이 발송됩니다. - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbay\_v2?: object **엑심베이 특수 파라미터** - payment?: object - payment\_method?: string **결제수단 단독 노출** 엑심베이의 결제수단 코드는 포트원 코드와 상이하므로, [EXIMBAY Docs](https://developer.eximbay.com/eximbay/api_sdk/code-organization.html#paymentCode)에서 확인 후 입력해야 합니다. - multi\_payment\_method?: string\[] **결제수단 노출 목록** 여러 결제수단을 노출합니다. - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unit\_price?: string **단가 (음수 가능)** - ship\_to?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **수신인의 성을 제외한 이름** - last\_name?: string **수신인의 성** - phone\_number?: string **수신인 전화번호** - postal\_code?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - bill\_to?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - first\_name?: string **청구 카드 명의자의 성을 제외한 이름** - last\_name?: string **청구 카드 명의자의 성** - phone\_number?: string **청구 카드 명의자의 전화번호** - postal\_code?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** ## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제 요청 시 `POST /payments/{paymentId}/billing-key` API를 호출해야 합니다. 엑심베이 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts const response = await axios({ url: `https://api.portone.io/payments/${paymentId}/billing-key`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { billingKey: "billing-key-1", // SDK 빌링키 발급 및 결제 시 발급받은 빌링키 orderName: "PortOne Recurring Payment", customer: { name: { full: "PortOne", }, email: "test@example.com", }, amount: { total: 100, // 1 USD }, currency: "USD", locale: "KO_KR", }, }); ```
### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - URL path에 포함하여 요청해야 합니다. - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** `vat`와 `taxFree` 파라미터는 지원하지 않습니다. - total: number **총 결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화** - [ISO 4217 통화 코드](https://en.wikipedia.org/wiki/ISO_4217) - customer: object **고객 정보** 엑심베이의 경우 고객 이름과 이메일은 필수 입력 항목입니다. - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** - email: string **구매자 이메일** - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbayV2?: object **엑심베이 특수 파라미터** - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unitPrice?: string **단가 (음수 가능)** - shipTo?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **수신인의 성을 제외한 이름** - lastName?: string **수신인의 성** - phoneNumber?: string **수신인 전화번호** - postalCode?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - billTo?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **청구 카드 명의자의 성을 제외한 이름** - lastName?: string **청구 카드 명의자의 성** - phoneNumber?: string **청구 카드 명의자의 전화번호** - postalCode?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 하기 위해서는 `POST /payments/{paymentId}/schedule` 를 이용하여 결제를 예약합니다. 엑심베이 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts const response = await axios({ url: `https://api.portone.io/payments/${paymentId}/schedule`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { payment: { billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키 orderName: "PortOne Recurring Payment", customer: { name: { full: "PortOne", }, email: "test@example.com", }, amount: { total: 100, // 1 USD }, currency: "USD", locale: "KO_KR", }, timeToPay: "2023-01-01T00:00:00+09:00", // 결제 예정 시점. RFC 3339 형식으로 입력해야 합니다. }, }); ```
### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제나 가상계좌 발급을 시도하는 경우 에러가 발생합니다. - URL path에 포함하여 요청해야 합니다. - payment: object **빌링키 결제 요청 입력정보** - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** `vat`와 `taxFree` 파라미터는 지원하지 않습니다. - total: number **총 결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화** - [ISO 4217 통화 코드](https://en.wikipedia.org/wiki/ISO_4217) - customer: object **고객 정보** 엑심베이의 경우 고객 이름과 이메일은 필수 입력 항목입니다. - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** - email: string **구매자 이메일** - products?: object\[] **구매 상품 정보** - 해외카드 결제를 제외하고 필수 입력입니다. - 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. * id: string **상품 ID** * name: string **상품명** * amount: number **상품 단위 가격** 결제 금액과 동일하게 scale factor가 적용된 값을 입력합니다. * quantity: number **상품 수량** * link: string **상품 판매 URL** - bypass?: oneof object - eximbayV2?: object **엑심베이 특수 파라미터** - merchant?: object - shop?: string **상점명** - surcharge?: object\[] **최대 3개의 추가 비용 목록** - name?: string **항목명** - quantity?: string **수량** - unitPrice?: string **단가 (음수 가능)** - shipTo?: object - city?: string **배송지 도시** - country?: string **배송지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **수신인의 성을 제외한 이름** - lastName?: string **수신인의 성** - phoneNumber?: string **수신인 전화번호** - postalCode?: string **배송지 우편번호** - state?: string **배송지가 미국 혹은 캐나다인 경우, 배송지 주 정보** - street1?: string **배송지 상세 주소** - billTo?: object - city?: string **청구지 도시** - country?: string **청구지 국가 (ISO 3166 두 자리 국가 코드)** - firstName?: string **청구 카드 명의자의 성을 제외한 이름** - lastName?: string **청구 카드 명의자의 성** - phoneNumber?: string **청구 카드 명의자의 전화번호** - postalCode?: string **청구지 우편번호** - state?: string **청구지가 미국 혹은 캐나다인 경우, 청구지 주 정보** - street1?: string **청구지 상세 주소** - timeToPay: string **결제 예정 시점** ## 유의사항 ### 공통 - `customer.name` 및 `customer.email`은 필수 입력 항목입니다. - 해외카드 결제를 제외하고 `products`를 필수로 입력해야 합니다. 해외카드의 경우에도 위험 거래 관리가 필요한 경우 요구될 수 있습니다. - `products` 입력 시 `link`를 필수로 입력해야 합니다. ### SDK 결제 / 빌링키 발급 및 결제 요청 - 네이버페이 포인트로 결제할 경우에는 `bypass.eximbay_v2.tax` 내용을 모두 입력해야 합니다. - 계좌이체 사용 시에는 현금영수증 발급을 위해 반드시 `bypass.eximbay_v2.tax.receipt_status`를 `Y`로 입력해야 합니다. - `bypass.eximbay_v2.payment_method`에 일본 편의점 결제를 지정할 경우 `customer.phoneNumber`을 필수로 입력해야 합니다. - 아래 결제수단의 경우 사용이 제한되므로 결제 연동 시 유의해 주시기 바랍니다. - 가상계좌(`P305`) : 호환성 이슈로 추후 지원 예정 - Klarna(`P197`) : 엑심베이 정책에 따라 신규 결제 사용 불가 - 모바일 앱 내에서 결제를 연동할 경우 `appScheme` 파라미터를 설정하고 `bypass.eximbay_v2.settings.call_from_app` 파라미터를 "Y"로 설정해야 합니다. - 엑심베이의 경우 결제창을 닫은 이후에 결제가 성공 처리될 수 있습니다. 웹훅을 연동하여 결제 실패 상태에서 결제 성공 상태로 바뀌는 경우를 처리해야 합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/galaxia --- title: 갤럭시아머니트리 description: 갤럭시아머니트리 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/galaxia --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액 결제 : `MOBILE` - 상품권 : `GIFT_CERTIFICATE` - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `CARD` - **결제창 빌링키 발급과 동시에 결제** `billingKeyAndPayMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 휴대폰: `MOBILE` ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 갤럭시아머니트리 채널 사용을 명시해주세요. 갤럭시아머니트리 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: "KRW", payMethod: "CARD", customer: { customerId: "customer-1234", // 고객사가 구매자에게 부여한 고유 ID (필수) fullName: "포트원", phoneNumber: "010-0000-1234", email: "test@portone.io", }, bypass: { galaxia: { ITEM_CODE: "상품코드", // 필수, 최대 10바이트 }, }, }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. (최대 64자) - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. 갤럭시아머니트리의 경우 필수로 입력해야 합니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - totalAmount: number **결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. 갤럭시아머니트리의 경우 `KRW`만 지원됩니다. - payMethod: string **결제수단 구분코드** 결제 호출 시 결제수단을 지정할 때 사용됩니다. - 신용카드 : `CARD` - 실시간 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 상품권 : `GIFT_CERTIFICATE` - 간편 결제 : `EASY_PAY` - taxFreeAmount?: number **면세 금액** (기본값: 0) - vatAmount?: number **부가세 금액** 미 입력시 과세 금액의 1/11로 자동 계산됩니다. - customer: object **고객 정보** - customerId: string **구매자 고유 ID** 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. 갤럭시아머니트리의 경우 필수 입력이며 최대 20자까지 허용됩니다. - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** 계좌이체 결제 시 필수 입력입니다. - email?: string **구매자 이메일** - redirectUrl?: string **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** 갤럭시아머니트리의 경우 **모바일 환경에서 필수 입력**입니다. - noticeUrls?: string\[] **트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** 설정시 콘솔에 설정된 웹훅 URL은 override 되며 해당 주소로만 웹훅이 발송됩니다. - appScheme?: string **IOS 앱에서 결제시 카드/은행 앱에서 인증 후 복귀 될 고객사 커스텀 앱 URL Scheme** - 예: `portone://` - 주의: **IOS 앱 결제시 필수** 입력이며 **앱이 아닌 모바일 웹 결제시에는 입력하지 마세요.** - isEscrow?: boolean **에스크로 결제 여부** (기본값: false) 갤럭시아머니트리의 경우, 계좌이체/가상계좌 결제시 에스크로 결제가 허용됩니다. - virtualAccount?: object **가상계좌 결제 관련 설정** - accountExpiry?: object **입금 만료 기한** 갤럭시아머니트리의 경우 가상계좌 결제시 **필수 입력**입니다. - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 RFC 3339 date-time 형식으로 입력해야 합니다. - card?: object **카드 결제 관련 설정** - cardCompany?: string **카드사 다이렉트 호출 시 카드사 코드** [카드사 코드](https://developers.portone.io/opi/ko/support/code-info/card-code) 참조 - installment?: object **할부 설정** - monthOption?: object **할부 개월 수 옵션** - fixedMonth?: number **고정 할부 개월 수** 일시불일 시 0으로 설정합니다. - availableMonthList?: number\[] **선택 가능한 할부 개월 수 목록** 예시: `[0, 2, 3, 4, 5, 6]` - 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능 - mobile?: object **휴대폰 결제 관련 설정** - carrier?: string **휴대폰 통신사 코드** `SKT`, `KT`, `LGU`, `HELLO`, `KCT`, `SK7` - giftCertificate?: object **상품권 결제 관련 설정** - giftCertificateType?: string **상품권 종류** - 컬쳐랜드: `CULTURELAND` - 스마트문상: `SMART_MUNSANG` - 도서문화상품권: `BOOKNLIFE` - 해피머니: `HAPPYMONEY` - easyPay?: object **간편결제 관련 설정** - easyPayProvider?: string **간편결제사 코드** - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` - 토스페이: `TOSSPAY` - 삼성페이: `SAMSUNGPAY` - 애플페이: `APPLEPAY` - 페이코: `PAYCO` - 머니트리: `MONEYTREE` - bypass: object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - galaxia: object **갤럭시아머니트리 전용 파라미터** - ITEM\_CODE: string **구매 상품코드** 갤럭시아머니트리에서 발급받은 상품 코드를 입력합니다. (최대 10자, **필수**) ### 유의사항
갤럭시아머니트리 지원 결제 수단 - CARD (신용카드) - TRANSFER (실시간 계좌이체) + 에스크로 - VIRTUAL\_ACCOUNT (가상계좌) + 에스크로 - MOBILE (휴대폰소액결제) - GIFT\_CERTIFICATE (상품권) - CULTURELAND (컬쳐랜드) - SMART\_MUNSANG (스마트문상) - BOOKNLIFE (도서문화상품권) - HAPPYMONEY (해피머니) - EASY\_PAY (간편결제) - KAKAOPAY (카카오페이) - NAVERPAY (네이버페이) - TOSSPAY (토스페이) - SAMSUNGPAY (삼성페이) - APPLEPAY (애플페이) - PAYCO (페이코) - MONEYTREE (머니트리)
가능한 트랜잭션 환경 - PC (iframe) - 모바일 (리디렉션)
## SDK 빌링키 발급 요청하기 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 갤럭시아머니트리 채널 사용을 명시해주세요. 갤럭시아머니트리 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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", // 갤럭시아머니트리의 경우 'CARD'만 지원됩니다. issueId: "test-issueId", issueName: "빌링키 발급", displayAmount: 1000, currency: "KRW", customer: { customerId: "customer-1234", // 고객사가 구매자에게 부여한 고유 ID (필수) fullName: "포트원", phoneNumber: "010-0000-1234", email: "test@portone.io", }, bypass: { galaxia: { ITEM_CODE: "상품코드", // 필수, 최대 10바이트 }, }, }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyMethod: string **빌링키 발급수단** 갤럭시아머니트리는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는 `CARD`로 고정해야 합니다. - issueId: string **빌링키 발급 건 고유 ID** 고객사에서 채번하여 사용해야 합니다. - issueName: string **빌링키 발급 시 결제창에 표시되는 제목** 갤럭시아머니트리의 경우 필수로 입력해야 합니다. - displayAmount?: number **결제창에 표시될 금액** 빌링키 발급 시 amount가 0이거나 미입력시 1000원으로 노출됩니다. (결제 발생하지 않음) - currency?: string **결제 통화** 갤럭시아머니트리의 경우 `KRW`만 지원됩니다. - customer: object **고객 정보** - customerId: string **구매자 고유 ID** 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. 갤럭시아머니트리의 경우 필수 입력입니다. - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - redirectUrl?: string **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** 갤럭시아머니트리의 경우 **모바일 환경에서 필수 입력**입니다. - bypass: object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - galaxia: object **갤럭시아머니트리 전용 파라미터** - ITEM\_CODE: string **구매 상품코드** 고객사에서 내부적으로 관리하는 상품 코드를 입력합니다. (최대 10자, **필수**)
갤럭시아머니트리 지원 빌링키 발급 수단 - CARD (카드)
## SDK 빌링키 발급 및 결제 요청하기 빌링키 발급과 동시에 결제 요청 시에는 `requestIssueBillingKeyAndPay` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 갤럭시아머니트리 채널 사용을 명시해주세요. 갤럭시아머니트리 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: "MOBILE", // 갤럭시아머니트리의 경우 'MOBILE'만 지원됩니다. paymentId: `payment${crypto.randomUUID()}`, orderName: "월간 이용권 정기결제", totalAmount: 1000, // 전달한 금액 만큼 실제로 승인이 됩니다. currency: "KRW", customer: { customerId: "customer-1234", // 고객사가 구매자에게 부여한 고유 ID (필수) fullName: "포트원", phoneNumber: "010-0000-1234", email: "test@portone.io", }, bypass: { galaxia: { ITEM_CODE: "상품코드", // 필수, 최대 10바이트 }, }, }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyAndPayMethod: string **빌링키 발급 및 결제수단** 갤럭시아머니트리의 경우, 빌링키 발급과 동시에 결제 수단은 `MOBILE`만 허용되며 **반드시 `MOBILE`을 필수로 입력해주셔야** 합니다. - paymentId: string **주문 번호** 매번 고유하게 채번되어야 합니다. - orderName: string **주문명** 갤럭시아머니트리의 경우 필수로 입력해야 합니다. - totalAmount: number **결제 금액** **string** 이 아닌 점에 유의하세요. 전달한 금액 만큼 실제로 승인이 됩니다. - currency?: string **결제 통화** 갤럭시아머니트리의 경우 `KRW`만 지원됩니다. - customer: object **고객 정보** - customerId: string **구매자 고유 ID** 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. 갤럭시아머니트리의 경우 필수 입력이며 최대 20자까지 허용됩니다. - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - redirectUrl?: string **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** 갤럭시아머니트리의 경우 **모바일 환경에서 필수 입력**입니다. - mobile?: object **휴대폰 결제 관련 설정** - carrier?: string **휴대폰 통신사 코드** `SKT`, `KT`, `LGU`, `HELLO`, `KCT`, `SK7` - bypass: object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - galaxia: object **갤럭시아머니트리 전용 파라미터** - ITEM\_CODE: string **구매 상품코드** 갤럭시아머니트리에서 발급받은 상품 코드를 입력합니다. (최대 10자, **필수**)
갤럭시아머니트리 지원 빌링키 발급과 동시에 결제 수단 - MOBILE (휴대폰소액결제)
## 연동 유의사항 ### 갤럭시아머니트리 필수 파라미터 갤럭시아머니트리 연동 시 아래 파라미터는 필수로 입력해야 합니다. - `bypass.galaxia.ITEM_CODE`: 고객사에서 내부적으로 관리하는 상품 코드 (최대 10자) - `customer.customerId`: 고객사가 구매자에게 부여한 고유 ID (최대 20자) - `orderName`: 주문명 ### 모바일 결제 시 필수 파라미터 모바일 환경에서 결제 시 `redirectUrl` 파라미터를 필수로 입력해야 합니다. ### 가상계좌 결제 시 필수 파라미터 가상계좌 결제 시 `virtualAccount.accountExpiry` 파라미터를 필수로 입력해야 합니다. ### 빌링키 발급 제약사항 - **결제창 빌링키 발급**: 카드(`CARD`)만 지원 - **결제창 빌링키 발급과 동시에 결제**: 휴대폰(`MOBILE`)만 지원 ### 지원 통화 갤럭시아머니트리는 `KRW`만 지원합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/inicis-jp --- title: KG이니시스 일본결제 description: KG이니시스 일본결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 편의점결제 : `CONVENIENCE_STORE` - 간편결제 : `EASY_PAY` ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KG이니시스 채널 사용을 명시해주세요. KG이니시스 일본결제 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: 10, currency: "CURRENCY_JPY", payMethod: "CARD", customer: { fullName: "matt", firstNameKana: "マット", lastNameKana: "デイモン", phoneNumber: "01012341234", email: "test@portone.io", }, storeDetails: { storeName: "韓国ストア", storeNameShort: "ストア", storeNameEn: "Kankoku Store", storeNameKana: "カンコクストア", contactName: "contact", email: "store@portone.io", phoneNumber: "3712345678", openingHours: { open: "00:00", close: "23:00", }, }, }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - totalAmount: number **결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 엔화 결제만 허용하며 `CURRENCY_JPY`로 입력해야 합니다. - payMethod: string **결제수단 구분코드** 결제 호출 시 결제수단을 지정할 때 사용됩니다. - 신용카드 : `CARD` - 편의점 결제 : `CONVENIENCE_STORE` - 간편 결제 : `EASY_PAY` - card?: object **카드 결제 시 파라미터** - installment?: object **할부 개월 수 설정** - monthOption?: object **할부 개월 수 설정** - fixedMonth?: integer **고정 할부 개월 수** 0을 입력한 경우 일시불만 표시됩니다. - availableMonthList?: integer\[] **렌더링을 허용 할 할부 개월 수 리스트** 목록에 0이 포함되어 있는 경우 일시불도 표시됩니다. 목록에 0만 있는 경우 일시불만 표시됩니다. - convenienceStore?: object **편의점 결제 시 파라미터** - paymentDeadline: object **지불 기한** - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 ISO8601 형식으로 입력해야 합니다. - easyPay?: object **간편 결제 시 파라미터** - easyPayProvider: string **간편 결제 수단** - customer?: object **고객 정보** - customerId?: string **구매자 ID** CBT 유형이 SBPS인 경우 필수 입력이며 최대 30자로 설정해야합니다. - fullName?: string **구매자 전체 이름** - 이니시스 일본결제의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - firstName?: string **구매자 이름** - 이니시스 일본결제의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - lastName?: string **구매자 성** - 이니시스 일본결제의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - firstNameKana?: string **구매자 이름 (후리가나)** - 편의점 결제의 경우 firstNameKana + lastNameKana를 필수로 입력해야 합니다. - lastNameKana?: string **구매자 성 (후리가나)** - 편의점 결제의 경우 firstNameKana + lastNameKana를 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - storeDetails?: object **상점 정보(가맹점 정보)** - storeName?: string **상점명** CBT 유형이 JPPG인 경우 필수 입력입니다. - storeNameKana?: string **상점명 (후리가나)** CBT 유형이 JPPG인 경우 필수 입력입니다. 가타카나만 허용합니다. - storeNameEn?: string **상점명 (영문)** CBT 유형이 JPPG인 경우 필수 입력입니다. 알파벳만 허용합니다. - storeNameShort?: string **상점명 (약어)** CBT 유형이 JPPG인 경우 필수 입력입니다. - contactName?: string **상점 연락처 정보 이름** CBT 유형이 JPPG인 경우 필수 입력입니다. - email?: string **상점 이메일** CBT 유형이 JPPG인 경우 필수 입력입니다. - phoneNumber?: string **상점 연락처** CBT 유형이 JPPG인 경우 필수 입력입니다. - openingHours?: object **상점 영업시간** CBT 유형이 JPPG인 경우 필수 입력입니다. - open?: string **영업 시작 시간** HH:mm 포맷으로 입력해야하며 00:00\~23:59 범위의 값만 허용합니다. - close?: string **영업 종료 시간** HH:mm 포맷으로 입력해야하며 00:00\~23:59 범위의 값만 허용합니다. - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - inicis\_jp?: InicisJp [definition link](https://developers.portone.io/schema/browser-sdk.yml#/resources/entity/bypass/payment/InicisJp) ### 유의사항 #### 공통
`paymentId` 에는 알파벳 대소문자, 숫자 및 일부 특수문자만 허용됩니다. 지원되지 않는 언어(ex. 한글) 및 특수문자(ex. `()`) 사용 시 결제가 실패할 수 있습니다.
지원되는 결제창 언어 이니시스 일본결제 결제창의 언어는 일본어로 고정입니다.
지원되는 결제 통화 KG이니시스 일본결제의 경우 `JPY`만 지원합니다.
#### 카드 결제
할부 개월 수 옵션은 일부 할부 개월 수만 지원합니다. KG이니시스 일본결제 카드 결제 경우 할부개월 수는 3, 5, 6, 10, 12개월만 지원합니다.
이니시스 일본결제에서 지원하지 않는 카드 관련 파라미터 KG이니시스 일본결제의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `cardCompany`: 카드 결제시 사용되는 카드사 코드 - `availableCards`: 노출할 카드사 제어 - `useAppCardOnly`: 앱카드만 허용할지 여부 - `useInstallment`: 할부 사용 여부. (이니시스 일본결제의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (이니시스 일본결제의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 간편 결제
이니시스 일본결제에서 지원하는 간편결제사 종류 KG이니시스 일본결제의 경우 아래 간편결제사를 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. - 아마존페이: `AMAZONPAY` - 라쿠텐페이: `RAKUTENPAY` - Paypay: `PAYPAY` - dBarai: `DBARAI` - AuPay: `AUPAY` - Merpay: `MERPAY`
이니시스 일본결제에서 지원하지 않는 간편결제 관련 파라미터 이니시스 일본결제의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `installment`: 할부 설정 - `useCardPoint`: 카드사 포인트 사용 여부 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션 - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - `useInstallment`: 할부 사용 여부. (이니시스 일본결제의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (이니시스 일본결제의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 편의점결제
`convenienceStore.paymentDeadline` 파라미터는 필수로 입력해야 합니다. - KG이니시스 일본결제 편의점 결제의 경우 **지불기한인 `convenienceStore.paymentDeadline` 파라미터가 필수**로 입력해야 합니다. - 지불기한은 최소 1일, 최대 30일까지만 설정 가능합니다.
편의점 결제는 입금 이전에만 취소할 수 있습니다.
# https://developers.portone.io/opi/ko/integration/pg/v2/inicis-unified-identity-verification --- title: KG이니시스 통합인증 description: KG이니시스 통합인증 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/inicis --- ## KG이니시스 통합인증 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## SDK를 통해 본인인증하기 - [본인인증 연동하기](https://developers.portone.io/opi/ko/extra/identity-verification/readme-v2) 페이지의 내용을 참고하여 연동을 진행합니다. ## KG이니시스 특수 파라미터 안내 포트원에서는 `bypass` 파라미터를 통해 KG이니시스에서 특수하게 지원하는 파라미터들을 입력할 수 있도록 지원하고 있습니다. `flgFixedUser` 파라미터의 경우 필수로 입력해야 합니다. - `flgFixedUser`: 인증 창에 고객 정보가 자동으로 입력하도록 설정할 수 있습니다. - `directAgency`: 인증 업체를 사용자가 선택하지 않고 특정 인증 업체를 통해 인증하도록 설정할 수 있습니다. - `logoUrl`: 인증 창 좌측 상단 KG이니시스 로고 대신 들어갈 로고의 URL입니다. - `FRGNDInfo`: 성별 및 외국인 정보 별도 입력 여부 - `Y`(기본값): 성별 및 외국인 정보를 제공하지 않는 네이버, 카카오에서 사용자가 성별 및 외국인 정보를 입력하는 칸을 표시합니다. **해당 정보는 인증 기관을 통해 검증되지 않습니다.** - `N`: 네이버, 카카오에서 사용자가 성별 및 외국인 정보를 입력하는 칸을 표시하지 않습니다. SDK를 통해 아래와 같이 특수 파라미터들을 입력하실 수 있습니다. ```ts PortOne.requestIdentityVerification({ /* 기타 파라미터 생략 */ bypass: { inicisUnified: { flgFixedUser: "N", directAgency: "PASS", logoUrl: "https://www.MarketA.co.kr/logo.png", }, }, }); ``` ### `flgFixedUser` 사용 시 유의사항 `Y` 또는 `N`만 입력 가능합니다. `Y`인 경우 이름, 연락처, 출생년도, 출생월, 출생일을 필수로 입력해야 합니다. ### `directAgency` 사용 시 유의사항 인증 업체 코드를 입력해야 합니다. `SMS`의 경우, KG이니시스와 계약하지 않으면 `알 수 없는 오류가 발생했습니다.` 메시지와 함께 인증 진행이 불가능합니다.
인증 업체 코드 확인하기 - PASS(패스 (통신사)) - TOSS(토스) - KFTC(금융결제원) - KAKAO(카카오) - NAVER(네이버) - SAMSUNG(삼성패스) - SHINHAN(신한은행) - KB(국민은행) - HANA(하나은행) - WOORI(우리은행) - NH(농협은행) - KAKAOBANK(카카오뱅크) - SMS(휴대폰 인증, 별도 계약 필요)
### `logoUrl` 사용 시 주의사항 최적 크기는 가로 164px, 세로 28px입니다. 인증 창은 HTTPS를 사용하므로, HTTP URL 사용 시 이미지가 제대로 표시되지 않을 수 있습니다. # https://developers.portone.io/opi/ko/integration/pg/v2/inicis-v2 --- title: KG이니시스 description: KG이니시스 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/inicis --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 사전 계약 안내 아래 기능을 사용하시려면 KG이니시스에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다. - API를 통한 수기 결제 (가상계좌, 카드) - API를 통한 빌링키 발급 - 에스크로 결제 - 상점분담무이자 설정 - 부가세 및 비과세 금액 직접 설정 - 카드사 포인트 사용 여부 설정 - OK캐시백 적립 옵션 설정 - 부분무이자 설정 - 몰포인트 설정 - 카드사/간편결제 다이렉트 호출 - 휴대폰 결제 익월 환불 ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 상품권 : `GIFT_CERTIFICATE` - 휴대폰 소액 결제 : `MOBILE` - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** 카드 결제는 `requestIssueBillingKey` 함수, 휴대폰 결제는 `requestIssueBillingKeyAndPay` 함수를 이용합니다. `requestIssueBillingKeyAndPay` 함수를 이용할 때에는 빌링키 발급과 동시에 결제가 일어납니다. `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `CARD` - 휴대폰: `MOBILE` - **API 수기(키인) 결제** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 - 가상계좌: `virtualAccount` 로 설정하여 가상계좌 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/payment#post%20%2Fpayments%2F%7BpaymentId%7D%2Finstant) 를 참고해주시기 바랍니다. - **API 빌링키 발급** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/billingKey#post%20%2Fbilling-keys)를 참고해주시기 바랍니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KG이니시스 채널 사용을 명시해주세요. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 **구매자 전체 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - firstName?: string **구매자 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - lastName?: string **구매자 성** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - KG이니시스의 PC 결제의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional) - email?: string **구매자 이메일** - KG이니시스의 PC 결제의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional) - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - inicis\_v2?: InicisV2BypassOnPc & InicisV2BypassOnMobile **이니시스 bypass 파라미터** KG이니시스는 PC 결제 모듈과 모바일 결제 모듈이 분리되어 있기 때문에 bypass 파라미터 또한 PC용과 모바일용이 분리되어 있습니다. - **bypass 예시 코드** ```json { "bypass": { "inicis_v2": { "logo_url": "https://portone.io/assets/portone.87061e94.avif", "logo_2nd": "https://admin.portone.io/assets/img/auth/lock.png", "parentemail": "parentemail", "Ini_SSGPAY_MDN": "01012341234", "acceptmethod": ["SKIN(#C1272C)", "below1000", "ocb"], "P_CARD_OPTION": "selcode=14", "P_MNAME": "포트원", "P_RESERVED": ["below1000=Y", "noeasypay=Y"] } } } ``` - InicisV2BypassOnPc **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)`) 카드사 코드는 [KG이니시스 통합 코드](https://manual.inicis.com/pay/code.html) 페이지에서 "결제요청 시 카드코드" 섹션을 참고하시기 바랍니다. - mallpoint(${string})?: string 몰포인트 (별도 계약시 이용 가능) `string` 부분에는 `카드코드:카드코드` 와 같은 형식으로 입력합니다. (ex. `mallpoint(11:34)`) 카드사 코드는 [KG이니시스 통합 코드](https://manual.inicis.com/pay/code.html) 페이지에서 "결제요청 시 카드코드" 섹션을 참고하시기 바랍니다. - InicisV2BypassOnMobile **모바일용 파라미터** - 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://) 호출 ### 유의사항 #### 공통
계약 사항에 따라 결제 정보에서 카드 정보가 누락될 수 있습니다. KG이니시스와의 계약에서 결제 결과에 카드번호를 전송하지 않도록 설정된 경우, 결제 조회 시 다음 카드 관련 필드들이 누락될 수 있습니다. - `card.issuer`: 카드 발급사 - `card.publisher`: 카드 발행사 - `card.name`: 카드명
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 결제와 모바일 결제에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 PC 결제에서는 필수이지만, 모바일 결제에서는 선택입니다. - `customer.fullName` 혹은 `customer.firstName + customer.lastName` - `customer.phoneNumber` - `customer.email`
`paymentId` 에는 ASCII 문자만 허용됩니다. `paymentId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
지원되는 결제창 언어 SDK를 통한 결제 요청 파라미터에는 결제창 언어를 지정할 수 있는 `locale` 파라미터가 존재합니다. PC 결제의 경우 `KO_KR`, `EN_US`, `ZH_CN`을 지원하며, 모바일 결제의 경우 `KO_KR`, `EN_US`만을 지원합니다.
지원되는 결제 통화 SDK를 통한 결제 요청 파라미터에는 결제 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. KG이니시스의 경우 `KRW`와 `USD`를 지원하며, 이 중 `USD`는 카드 결제일 경우에만 지정 가능합니다.
부가세, 면세금액 직접 지정을 위해서는 별도 계약이 필요합니다. SDK를 통한 결제 요청 파라미터에는 부가세를 지정할 수 있는 `vat` 파라미터와 면세 금액을 지정할 수 있는 `taxFreeAmount` 파라미터가 존재합니다. KG이니시스의 경우 부가세 및 면세금액을 직접 지정하기 위해서는 별도 계약이 필요합니다. 별도 계약이 되지 않은 상태에서 `vat`와 `taxFreeAmount`에 값을 지정해 결제를 요청하면 요청한 내용과 다른 금액으로 실결제가 발생할 수 있습니다.
이니시스에서 지원하는 현금영수증 발급 유형 현금영수증은 현금성 거래인 실시간 계좌이체 및 가상계좌 발급 시 사용이 가능합니다. KG이니시스의 경우 현금영수증 발급 유형을 `CORPORATE` 혹은 `PERSONAL` 등 파라미터로 제어할 수 없습니다. 어떤 유형의 현금영수증을 발행할지는 항상 결제창 내에서 선택 가능하며, 결제창 호출 파라미터로는 현금영수증을 발행 여부만을 제어할 수 있습니다. `cashReceiptType` 파라미터를 `ANONYMOUS`로 설정 시 결제창에서 현금영수증 발급 UI가 미노출됩니다.
#### 카드 결제
카드사 다이렉트 호출 시 할부 개월 수 옵션은 고정 할부 개월 수만 지원합니다. KG이니시스 경우 **카드사 다이렉트 호출 시 할부 개월 수 옵션은** 고정 할부 개월 수만 지원합니다. 카드사 다이렉트 호출을 설정했으나 할부 개월 수 옵션을 `card.installment.monthOption.fixedMonth` 가 아닌 `card.installment.monthOption.availableMonthList`로 설정할 경우 에러가 발생합니다.
카드사 다이렉트 호출 시 지원하는 카드사 종류 KG이니시스의 경우 **포트원에서 관리하는 카드사 중 토스뱅크를 제외한 모든 카드사를 지원**합니다. 포트원에서 관리하는 카드사 목록을 확인하시려면 [JS SDK 결제요청 파라미터](https://developers.portone.io/sdk/ko/v2-sdk/payment-request) 페이지에서 `card` -> `cardCompany` 필드 설명을 참고해주세요.
이니시스에서 지원하지 않는 카드 관련 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useAppCardOnly`: 앱카드만 허용할지 여부 - `useInstallment`: 할부 사용 여부. (KG이니시스의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (KG이니시스의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 간편 결제
이니시스에서 지원하는 간편결제사 종류 KG이니시스의 경우 아래 간편결제사를 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` - 삼성페이: `SAMSUNGPAY` - ssg페이: `SSGPAY` - 애플페이: `APPLEPAY` - lpay: `LPAY` - 토스페이: `TOSSPAY` - 페이코: `PAYCO`
이니시스에서 지원하지 않는 간편결제 관련 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useCardPoint`: 카드사 포인트 사용 여부 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션 - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - `useInstallment`: 할부 사용 여부. (KG이니시스의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (KG이니시스의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 계좌이체
이니시스에서 지원하지 않는 계좌이체 관련 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 계좌이체 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
#### 가상계좌 결제
이니시스에서 지원하지 않는 가상계좌 관련 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 가상계좌 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
#### 상품권 결제
이니시스에서 지원하는 상품권 종류 및 필수 여부 KG이니시스 모바일 결제의 경우 `giftCertificateType`을 필수로 입력해야 하며, PC 결제의 경우는 선택 사항입니다. PC 결제에서 해당 파라미터를 입력하지 않을 경우 결제창 내에서 상품권 종류를 선택할 수 있습니다. KG이니시스에서 지원하는 상품권 종류는 아래와 같습니다. - 도서문화상품권: `BOOKNLIFE` - 스마트문상: `SMART_MUNSANG` - 컬쳐랜드 문화상품권: `CULTURELAND`
#### 휴대폰 소액 결제
`productType` 파라미터는 필수 입력해야 합니다. - KG이니시스의 경우 **휴대폰 소액결제시 상품 유형을 구분 짓는 `productType` 파라미터가 필수**로 입력해야 합니다. - `productType`의 값은 `PRODUCT_TYPE_REAL` 또는 `PRODUCT_TYPE_DIGITAL`를 입력해야 합니다.
결제창에 노출될 통신사 리스트 지정 옵션 지원 여부 KG이니시스 모바일 결제의 경우 `availableCarriers` 필드를 통해 결제창에 노출될 통신사 리스트를 지정할 수 있습니다. PC에서는 해당 파라미터를 지원하지 않습니다.
이니시스에서 지원하지 않는 휴대폰 소액결제 관련 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `carrier`: 휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값
## SDK 카드 빌링키 발급 요청하기 카드 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KG이니시스 채널 사용을 명시해주세요. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 **빌링키 발급수단** KG이니시스는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는 `CARD`로 고정해야 합니다. - issueId: string **빌링키 발급 건 고유 ID** - 고객사에서 채번하여 사용해야 합니다. - KG이니시스의 경우 필수 입력해야 합니다. - issueName: string **빌링키 발급 시 결제창에 표시되는 제목** - KG이니시스의 경우 필수 입력해야 합니다. - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - firstName?: string **구매자 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - lastName?: string **구매자 성** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - KG이니시스의 PC 빌링키 발급의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional) - email?: string **구매자 이메일** - KG이니시스의 PC 빌링키 발급의 경우 필수로 입력해야 합니다. (모바일인 경우에는 optional) - offerPeriod?: object **제공 기간** - KG이니시스 모바일 빌링키 발급의 경우 필수로 입력해야 합니다. (PC인 경우에는 optional) - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - inicis\_v2?: object **이니시스에서 제공하는 파라미터 모음** - carduse?: 'percard' | 'cocard' **개인/법인카드 사용 선택 옵션** - 모바일에서만 동작하는 파라미터입니다. - 'percard' 혹은 'cocard'를 입력할 수 있습니다. - 'percard' 입력 시 개인 카드로만 결제를 진행할 수 있으며, 'cocard' 입력 시 법인 카드로만 결제를 진행 할 수 있습니다. ### 유의사항
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 빌링키 발급과 모바일 빌링키 발급에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 PC에서는 필수이지만, 모바일에서는 선택입니다. - `customer.fullName` 혹은 `customer.firstName + customer.lastName` - `customer.phoneNumber` - `customer.email` 아래 필드들은 모바일에서는 필수이지만, PC에서는 선택입니다. - `offerPeriod`
`issueId` 에는 ASCII 문자만 허용됩니다. `issueId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
`offerPeriod` 파라미터 제약 사항 SDK를 통한 빌링키 발급 요청 파라미터에는 제공 기간을 나타내는 `offerPeriod` 파라미터가 존재합니다. 날짜 범위를 입력하는 방식(`range`)과 간격을 입력하는 방식(`interval`) 중 하나를 선택하여 입력할 수 있습니다. - `range` 방식으로 입력할 경우 `from`과 `to` 모두를 입력하셔야 하, `from`은 `to`보다 과거 시간이어야 합니다. - `interval` 방식으로 입력할 경우는 `1m` 또는 `1y`만 허용됩니다. `1m`를 입력할 경우 `월 정기결제`, `1y`를 입력할 경우 `연 정기결제` 로 빌링키 발급 창에 노출됩니다.
지원되는 결제창 언어 SDK를 통한 빌링키 발급 요청 파라미터에는 결제창 언어를 지정할 수 있는 `locale` 파라미터가 존재합니다. PC 빌링키 발급의 경우 `KO_KR`, `EN_US`, `ZH_CN`을 지원하며, 모바일 빌링키 발급의 경우 해당 파라미터를 지원하지 않고 항상 한국어로 노출됩니다.
지원되는 결제 통화 SDK를 통한 빌링키 발급 요청 파라미터에는 displayAmount에 대한 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. PC 빌링키 발급의 경우 `KRW`와 `USD`를 지원하며, 모바일 빌링키 발급의 경우 `KRW`만 지원합니다.
카드사 다이렉트 호출을 지원하지 않습니다. KG이니시스 경우 카드사 다이렉트 호출을 통한 빌링키 발급을 지원하지 않습니다. `card.cardCompany` 필드에 값을 채워도 빌링키 발급 동작에 아무런 영향을 미치지 않습니다.
## SDK 휴대폰 빌링키 발급 및 결제 요청하기 휴대폰 빌링키 발급 및 결제 요청 시에는 `requestIssueBillingKeyAndPay` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KG이니시스 채널 사용을 명시해주세요. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 **빌링키 발급 및 결제수단** KG이니시스는 빌링키 발급 및 결제 수단으로 휴대폰 소액 결제만을 지원하므로 해당 파라미터는 `PHONE`로 고정해야 합니다. - paymentId: string **빌링키 발급 및 결제 건 고유 ID** - 고객사에서 채번하여 사용해야 합니다. - KG이니시스의 경우 필수 입력해야 합니다. - orderName: string **빌링키 발급 및 결제 시 결제창에 표시되는 제목** - KG이니시스의 경우 필수 입력해야 합니다. - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - firstName?: string **구매자 이름** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - lastName?: string **구매자 성** - KG이니시스의 경우 fullName 혹은 (firstName + lastName)을 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - KG이니시스의 경우 필수 입력해야 합니다. - email?: string **구매자 이메일** - KG이니시스의 경우 필수 입력해야 합니다. - offerPeriod?: object **제공 기간** - KG이니시스 모바일 빌링키 발급 및 결제의 경우 필수로 입력해야 합니다. (PC인 경우에는 optional) ### 유의사항
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 빌링키 발급 및 결제와 모바일 빌링키 발급 및 결제에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 모바일에서는 필수이지만, PC에서는 선택입니다. - `offerPeriod`
`paymentId` 에는 ASCII 문자만 허용됩니다. `paymentId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
`productType` 파라미터는 필수 입력해야 합니다. - KG이니시스의 경우 **빌링키 발급 및 결제 시 상품 유형을 구분 짓는 `productType` 파라미터가 필수**로 입력해야 합니다. - `productType`의 값은 `PRODUCT_TYPE_REAL` 또는 `PRODUCT_TYPE_DIGITAL`를 입력해야 합니다.
`offerPeriod` 파라미터 제약 사항 SDK를 통한 빌링키 발급 및 결제 요청 파라미터에는 제공 기간을 나타내는 `offerPeriod` 파라미터가 존재합니다. 날짜 범위를 입력하는 방식(`range`)과 간격을 입력하는 방식(`interval`) 중 하나를 선택하여 입력할 수 있습니다. - `range` 방식으로 입력할 경우 `from`과 `to` 모두를 입력하셔야 하, `from`은 `to`보다 과거 시간이어야 합니다. - `interval` 방식으로 입력할 경우는 `1m` 또는 `1y`만 허용됩니다. `1m`를 입력할 경우 `월 정기결제`, `1y`를 입력할 경우 `연 정기결제` 로 빌링키 발급 및 결제 창에 노출됩니다.
이니시스에서 지원하지 않는 빌링키 발급 및 결제 파라미터 KG이니시스의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `locale`: 결제창 언어를 지정하기 위한 값 - `mobile.carrier`: 휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값 - `mobile.availableCarriers`: 빌링키 발급 및 결제창에 노출될 통신사 리스트
지원되는 결제 통화 SDK를 통한 빌링키 발급 및 결제 요청 파라미터에는 totalAmount에 대한 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. 이니시스 빌링키 발급 및 결제의 경우, `KRW`만 지원합니다.
## API 수기(키인)결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant`를 이용하여 결제 요청을 해야합니다.
```javascript // ... 수기(키인) 결제 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 **발급 은행** - 은행코드는 ENUM으로 정의되어 있습니다. - [BANK ENUM 바로가기](https://developers.portone.io/api/rest-v2/payment#Bank) - expiry: object **입금 만료 기한** - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 ISO8601 형식으로 입력해야 합니다. - option: object **가상계좌 발급 방식** - type: string **가상계좌 발급 유형** 발급 유형은 ENUM으로 정의되어 있습니다. - 회전식 가상계좌 : `NORMAL` - 고정식 가상계좌 : `FIXED` - 회전식 가상계좌는 일반적으로 사용되는 방식이며 PG사에서 직접 채번한 가상계좌번호를 사용합니다. - fixed?: object **고정식 가상계좌 발급 유형** - accountNumber?: string **고정식 가상계좌번호** - PG사가 일정 개수만큼의 가상계좌번호를 발급하여 가맹점에게 미리 전달하고 가맹점이 그 중 하나를 선택하여 사용하는 방식입니다. KG이니시스에서는 해당 방식만 지원하고 있습니다. - 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 **고객 이름** KG이니시스의 경우 full 혹은 separated를 필수로 입력해야 합니다. - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - KG이니시스의 경우 필수로 입력해야 합니다. - email: string **구매자 이메일** - KG이니시스의 경우 필수로 입력해야 합니다. - productCount?: integer **상품 개수** ## API 빌링키 발급 요청하기 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 **고객 이름** KG이니시스의 경우 full 혹은 separated를 필수로 입력해야 합니다. - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - KG이니시스의 경우 필수로 입력해야 합니다. - email: string **구매자 이메일** - KG이니시스의 경우 필수로 입력해야 합니다. ## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제를 하기 위해 `POST /payments/${PAYMENT_ID_HERE}/billing-key`를 이용하여 결제를 요청합니다. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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 **고객 이름** KG이니시스의 경우 full 혹은 separated를 필수로 입력해야 합니다. - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - KG이니시스의 경우 필수로 입력해야 합니다. - email: string **구매자 이메일** - KG이니시스의 경우 필수로 입력해야 합니다. - productCount?: integer **상품 개수** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/schedule` 를 이용하여 결제를 예약합니다. KG이니시스 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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 **고객 이름** KG이니시스의 경우 full 혹은 separated를 필수로 입력해야 합니다. - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - KG이니시스의 경우 필수로 입력해야 합니다. - email: string **구매자 이메일** - KG이니시스의 경우 필수로 입력해야 합니다. ### 유의사항 #### 공통
이니시스 필수 파라미터 KG이니시스의 경우에는 키인(수기)결제, 빌링키 발급, 빌링키 단건 결제 시 아래의 파라미터를 필수로 입력해야 합니다. - `customer.name.full` 혹은 `customer.name.separated` - `customer.phoneNumber` - `customer.email`
#### 에스크로
이니시스에서 에스크로 배송 등록시 필수 파라미터 KG이니시스의 경우 에스크로 배송 등록 시 아래의 파라미터를 필수로 입력해야 합니다. - `sender.name` - `sender.phoneNumber` - `sender.zipcode` - `sender.address` - `receiver.name` - `receiver.phoneNumber` - `receiver.zipcode` - `receiver.address` - `products`
## API 영수증 내 하위 상점 거래 등록 오픈마켓 고객사의 경우 해당 API를 호출하여 결제 내역 매출 전표에 하위 상점 거래를 등록할 수 있습니다. 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/payment#post%20%2Fpayments%2F%7BpaymentId%7D%2Fregister-store-receipt) 를 참고해주시기 바랍니다. ### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다. - URL path에 포함하여 요청해야 합니다. - items: RegisterStoreReceiptBodyItem\[] **등록할 거래 건 리스트** \= 매출전표에 등록할 하위 상점 거래 건 리스트를 등록 하셔야합니다. - storeBusinessRegistrationNumber: string **하위 상점 사업자등록번호** - storeName: string **하위 상점 명** - totalAmount: number **총 결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - taxFreeAmount: number **면세액** - KG이니시스의 경우 필수로 입력해야 합니다. - vatAmount: number **부가세** - KG이니시스의 경우 필수로 입력해야 합니다. - supplyAmount: number **공급가액** - KG이니시스의 경우 필수로 입력해야 합니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/kakaopay --- title: 카카오페이 description: 카카오페이 간편결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/kakaopay --- ## 카카오페이 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## 가능한 결제수단 - 간편 결제 - `payMethod`(결제) 혹은 `billingKeyMethod`(빌링키 발급) 파라미터를 `EASY_PAY` 로 설정해야 합니다. - 결제창 내에서 카드 및 카카오페이머니 선택이 가능합니다. ## SDK - 유의할 파라미터 ### 결제/빌링키 발급 공통 - `windowType` - 카카오페이의 경우 PC는 `IFRAME`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다. - `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다. ```json { "pc": "IFRAME", "mobile": "REDIRECTION" } ``` - `locale` - 카카오페이의 경우 `KO_KR`만 지원합니다. 이외의 값을 넣어도 무시됩니다. - `bypass` - 카카오페이의 경우 아래와 같이 `custom_message` 필드를 채워줄 수 있습니다. ```json { "bypass": { "kakaopay": { "custom_message": "여기가 안내 문구영역입니다." } } } ``` - `custom_message`: 결제 화면에 보여줄 사용자 정의 문구입니다.(카카오페이와 사전 협의 필요) - 해당 필드를 채워서 요청할 시 아래와 같이 카카오페이 결제창 내에서 문구가 띄워집니다. [이미지 링크](https://developers.portone.io/gitbook-assets/ko/KakaoTalk_Photo_2023-04-10-17-39-36.jpeg) - `easyPay` - `easyPayProvider` - 카카오페이의 경우 PG사 자체가 간편결제사이므로 `easyPayProvider` 는 비워두어도 무방하며 다른 값을 채울 경우 무시됩니다. - `availableCards` - 해당 파라미터로 사용 가능한 카드사를 제한할 수 있습니다. - 지원하는 카드사 목록: - `CARD_COMPANY_SHINHAN_CARD` - `CARD_COMPANY_KOOKMIN_CARD` - `CARD_COMPANY_HYUNDAI_CARD` - `CARD_COMPANY_LOTTE_CARD` - `CARD_COMPANY_SAMSUNG_CARD` - `CARD_COMPANY_NH_CARD` - `CARD_COMPANY_BC_CARD` - `CARD_COMPANY_HANA_CARD` - `CARD_COMPANY_CITI_CARD` - `CARD_COMPANY_KAKAO_BANK` - `appScheme` - 카카오페이 정책에 따라 iOS에서만 사용 가능합니다. ### 결제 (`requestPayment`) - `currency` - 카카오페이의 경우 원화 결제만 지원하므로 `KRW` 이외의 값을 넣으면 에러를 리턴합니다. - `isEscrow` - 카카오페이에서는 에스크로 결제를 지원하지 않으며, 해당 파라미터를 채워서 요청할 경우 포트원 내부적으로만 저장됩니다. - `isCulturalExpense` - 카카오페이에서는 지원하지 않는 파라미터입니다. 해당 파라미터를 채워서 요청할 경우 포트원 내부적으로만 저장됩니다. - `productType` - 카카오페이에서는 지원하지 않는 파라미터입니다. 해당 파라미터를 채워서 요청할 경우 포트원 내부적으로만 저장됩니다. - `easyPay.installment` - `freeInstallmentPlans` - 카카오페이는 지원하지 않는 파라미터입니다. - `monthOption` - 카카오페이는 고정개월 수 할부 옵션(`fixedMonth`)만 지원합니다. - 카카오페이의 경우, 결제 금액이 5만원 미만이어도 해당 파라미터가 채워져 있으면 체크카드로 결제가 불가능합니다. ### 빌링키 발급 (`requestIssueBillingKey`) - `issueName` - 빌링키 발급 시 결제창에 표시되는 제목입니다. (카카오페이는 필수 입력) # https://developers.portone.io/opi/ko/integration/pg/v2/kcp-v2-identity-verification --- title: KCP 본인인증 description: KCP 본인인증 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/kcp-v2-identity-verification --- ## KCP 본인인증 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. - KCP 관리자 페이지에서 부가서비스 > 휴대폰본인확인 > 인증결과URL설정 메뉴에서 인증 결과 URL로 `checkout-service.prod.iamport.co`를 설정합니다. ## SDK 방식으로 본인인증하기 - [본인인증 연동하기](https://developers.portone.io/opi/ko/extra/identity-verification/readme-v2) 페이지의 내용을 참고하여 연동을 진행합니다. ## API 방식으로 본인인증하기 - [본인인증 관련 API](https://developers.portone.io/api/rest-v2/identityVerification) 페이지의 내용을 참고하여 연동을 진행합니다. ### 본인인증 요청 전송 API ```ts await axios({ url: `https://api.portone.io/identity-verifications/${encodeURIComponent(identityVerificationId)}/send`, method: "post", headers: { "Content-Type": "application/json" }, data: { /* 기타 파라미터 생략 */ bypass: { kcpV2: { media_type: "MC01", }, }, }, }); ```
- channelKey: string **본인인증 요청하고자 하는 PG사의 채널키** 본인인증을 요청할 채널을 지정합니다. - customer: SendIdentityVerificationBodyCustomer **본인인증 요청을 위한 고객 정보**
customer 필수 파라미터 - name: string **이름** - phoneNumber: string **전화번호** 특수문자(-)없이 숫자만 입력합니다. - identityNumber: string **주민등록번호 앞 7자리**
- operator: IdentityVerificationOperator **본인인증 통신사** - SKT : SKT - KT : KT - LGU : LGU - SKT\_MVNO : SKT 알뜰폰 - KT\_MVNO : KT 알뜰폰 - LGU\_MVNO : LGU 알뜰폰 - method: IdentityVerificationMethod **본인인증 방식** - SMS - APP - bypass: kcpV2Bypass **NHN KCP 특수파라미터** 포트원에서는 `bypass` 파라미터를 통해 NHN KCP에서 특수하게 지원하는 파라미터들을 입력 할 수 있도록 지원하고 있습니다.
bypass 필수 파라미터 - media\_type: string **미디어 타입** - PC : MC01 - MOBILE : MC02
- storeId?: string **상점 아이디** 접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다. - customer: SendIdentityVerificationBodyCustomer **본인인증 요청을 위한 고객 정보**
customer 선택 파라미터 - id?: string **식별 아이디**
- customData?: string **사용자 지정 데이터** - bypass: kcpV2Bypass **NHN KCP 특수파라미터** 포트원에서는 `bypass` 파라미터를 통해 NHN KCP에서 특수하게 지원하는 파라미터들을 입력 할 수 있도록 지원하고 있습니다.
bypass 선택 파라미터 - web\_siteid: string **KCP 사이트 식별코드** DI 생성 시 사용할 사이트 ID입니다. 미입력 시 KCP에서 발급한 사이트 ID로 설정됩니다. - cp\_sms\_msg: string **CP 지정 SMS 메세지** 인증번호 난수가 채워질 \[000000] 부분만 제외 (6자리)하고 표시할 문자 발송 내용으로 요청 바랍니다. “\[000000]” 문자열은 반드시 포함되어야 합니다. ex) “cp\_sms\_msg” : “\[TEST SHOP]이용자번호는\[000000]입니다.” - cp\_callback: string **CP 지정 callback 번호** 인증번호 SMS의 발신자
### 본인인증 확인 API ```ts await axios({ url: `https://api.portone.io/identity-verifications/${encodeURIComponent(identityVerificationId)}/confirm`, method: "post", headers: { "Content-Type": "application/json" }, data: { otp: "000000", }, }); ```
- storeId?: string **상점 아이디** 접근 권한이 있는 상점 아이디만 입력 가능하며, 미입력시 토큰에 담긴 상점 아이디를 사용합니다. - otp?: string **OTP (One-Time Password)** SMS 방식으로 요청한 경우에만 사용됩니다.
## KCP 특수 파라미터 안내 포트원에서는 `bypass` 파라미터를 통해 KCP에서 특수하게 지원하는 파라미터들을 입력할 수 있도록 지원하고 있습니다. - `web_siteid`: (SDK, API) DI 생성 시 사용할 사이트 ID입니다. 미입력 시 KCP에서 발급한 사이트 ID로 설정됩니다. - `media_type`: (API) 미디어 타입으로 PC 환경은 `MC01`, MOBILE 환경은 `MC02` 를 입력합니다. - `cp_sms_msg`: (API) CP 지정 SMS 메세지입니다. 인증번호 난수가 채워질 \[000000] 부분만 제외 (6자리)하고 표시할 문자 발송 내용으로 요청 바랍니다. - `cp_callback`: (API) CP 지정 callback 으로 인증번호 SMS의 발신자를 설정합니다. SDK, API에서 아래와 같은 방식으로 특수 파라미터들을 입력하실 수 있습니다.
```ts // 필요한 파라미터를 선택하여 입력해주세요. const kcpBypass = { kcp_v2: { web_siteid: "J01234567890", }, }; ```
```ts // 필요한 파라미터를 선택하여 입력해주세요. const kcpBypass = { kcpV2: { media_type: "MC01", web_siteid: "J01234567890", cp_sms_msg: "[TEST SHOP]이용자번호는[000000]입니다.", cp_callback: "02-1670-5176", }, }; ```
SDK의 `requestIdentityVerification` 함수의 파라미터 중 `bypass` 필드에 아래와 같이 값을 채울 수 있습니다. ```ts PortOne.requestIdentityVerification({ /* 기타 파라미터 생략 */ bypass: kcpBypass, }); ```
[본인인증 요청 API](https://developers.portone.io/api/rest-v2/identityVerification#post%20%2Fidentity-verifications%2F%7BidentityVerificationId%7D%2Fsend)를 사용할 경우, bypass 필드에 아래 Json을 Stringify 해서 입력하셔야 합니다. ```ts await axios({ url: `https://api.portone.io/identity-verifications/${encodeURIComponent(identityVerificationId)}/send`, method: "post", headers: { "Content-Type": "application/json" }, data: { /* 기타 파라미터 생략 */ bypass: kcpBypass, }, }); ```
## 일반 파라미터 유의사항 안내 ### `identityVerificationId` 파라미터 유의사항 영어 대소문자와 숫자만 사용 가능하며 40자 이하로 입력해야 합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/kcp-v2 --- title: NHN KCP description: NHN KCP 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/nhn-kcp/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 사전 계약 안내 아래 기능을 사용하시려면 KCP에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다. - API를 통한 수기 결제 (가상계좌, 카드) - API를 통한 빌링키 발급 - 에스크로 결제 - 상점분담무이자 설정 - 부가세 및 비과세 금액 직접 설정 - 부분무이자 설정 - 휴대폰 결제 익월 환불 ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 상품권 : `GIFT_CERTIFICATE` - 휴대폰 소액 결제 : `MOBILE` - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `CARD` - **API 수기(키인) 결제** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 - 가상계좌: `virtualAccount` 로 설정하여 가상계좌 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/payment#post%20%2Fpayments%2F%7BpaymentId%7D%2Finstant) 를 참고해주시기 바랍니다. - **API 빌링키 발급** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/billingKey#post%20%2Fbilling-keys)를 참고해주시기 바랍니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KCP 채널 사용을 명시해주세요. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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`로 결제를 시도하는 경우 에러가 발생합니다. KCP의 경우 최대 40자 까지 허용합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. KCP의 경우 최대 100Byte까지 허용합니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - totalAmount: number **결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - payMethod: string **결제수단 구분코드** 결제 호출 시 결제수단을 지정할 때 사용됩니다. - 신용카드 : `CARD` - 실시간 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 간편 결제 : `EASY_PAY` - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - kcp\_v2?: object **KCP에서 제공하는 파라미터 모음** - site\_logo?: string **결제창에 삽입할 메인 로고 url** - 결제창 왼쪽 상단에 표시됩니다. - 이미지 사이즈는 150\*50 미만으로 설정해야 하며, GIF, JPG 파일만 지원됩니다. - skin\_indx?: integer **결제창 색상** - PC로 결제창 호출 시 결제창 색상을 변경합니다. - 1\~12까지 설정 가능합니다. - kcp\_pay\_title?: string **결제창 상단 문구** - 결제창의 상단 문구를 변경합니다. - shop\_user\_id?: string **리스크 관리 조치를 위한 고객사 회원 ID** - KCP에서 부정거래를 신속하게 탐지하기 위한 파라미터입니다. - 고객사에서 관리하는 구매자의 회원 ID를 입력합니다. - 상품권, 휴대폰 결제 시 필수로 입력해야 합니다. - site\_name?: string **카드사 다이렉트 호출 시 결제창에 표기될 상호명** - PC의 경우 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리카드사에 대해 다이렉트 호출 시 필수로 입력해야 합니다. - 모바일의 경우 필수로 입력해야 합니다. - disp\_tax\_yn?: string **결제창 현금영수증 노출 여부** - 결제창에서 현금영수증 노출 여부를 설정할 수 있습니다. 실시간 계좌이체 또는 가상계좌 결제 시 사용할 수 있습니다. - `Y`: 노출 - `N`: 노출하지 않음 - `R`: 소득공제로 노출 - `E`: 지출증빙으로 노출 - deli\_term?: string **에스크로 결제 예상 배송 소요일** - 에스크로 결제 시, 결제 상품의 예상 배송 소요일입니다. KCP측에서 에스크로 결제 사용 시 입력을 권장하고 있습니다. - 미입력 시 '00'으로 입력됩니다. - 입력 형식은 두 자리 수로 입력되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,`03`으로 입력 #### 예제 ```json title="bypass 파라미터 예시" { "bypass": { "kcp_v2": { "site_logo": "https://developers.portone.io/assets/portone.jpg", "skin_indx": 6, "shop_user_id": "user_id1", "site_name": "포트원 고객사" } } } ``` ### SDK 결제 - 유의사항 #### 공통
`paymentId` 파라미터 내 한글, 특수문자 미지원 `paymentId` 에는 영문/숫자만 사용할 수 있습니다. 한글이나 특수 문자가 포함된 채 결제를 요청하는 경우 결제 실패가 발생하오니 유의하시기 바랍니다.
결제창 표시 언어 지원 안내 SDK를 통한 결제 요청 시 `locale` 파라미터를 이용하여 결제창 언어를 변경할 수 있으며, PC 및 모바일 환경 모두 한국어(`KO_KR`) 및 영어(`EN_US`)를 지원합니다. 미입력 시 자동으로 한국어로 표시됩니다.
결제 통화 지원 안내 SDK를 통한 결제 요청 시 `currency` 파라미터를 이용하여 결제 통화를 지정할 수 있으며, KCP에서는 `KRW`와 `USD`만 지원됩니다. 단, `USD`는 카드 결제일 경우에만 지정 가능합니다.
부가세, 면세금액 직접 지정을 위해서는 별도 계약이 필요합니다. SDK를 통한 결제 요청 시 면세 금액(`taxFreeAmount`) 와 부가세(`vatAmount`) 파라미터를 이용하여 면세금액과 부가세를 직접 지정할 수 있습니다. 다만 직접 지정하여 사용하기 위해서는 사전에 KCP와 별도로 계약을 진행해야 합니다. 별도로 계약을 진행하지 않은 상태에서 해당 파라미터에 값을 지정하여 결제를 요청하는 경우 요청한 내용과 다른 금액으로 실결제가 발생할 수 있습니다.
KCP에서 지원하는 현금영수증 발급 유형 현금영수증은 현금성 거래인 실시간 계좌이체 및 가상계좌 발급 시 사용이 가능합니다. KCP의 경우 현금영수증 발급 유형을 `CORPORATE` 혹은 `PERSONAL` 등 파라미터로 제어할 수 없습니다. 어떤 유형의 현금영수증을 발행할지는 항상 결제창 내에서 선택 가능합니다.
#### 카드 결제
카드사 다이렉트 호출 시 고정 할부 개월 수만 설정할 수 있습니다. KCP의 경우 카드사 다이렉트 호출 시 **고정 할부 개월 수**만 설정 가능합니다. 카드사 다이렉트 호출 시 할부 개월 수 옵션을 `card.installment.monthOption.fixedMonth` 가 아닌 `card.installment.monthOption.availableMonthList`로 설정할 경우 에러가 발생합니다.
카드사 다이렉트 호출 시 지원하는 카드사 종류 아래 카드사는 다이렉트 호출이 가능합니다. - 신한카드 - 현대카드 - 삼성카드 - 농협카드 - 하나카드 - 롯데카드 - 씨티카드 - 우리카드 - 비씨카드 - 국민카드 - 우체국은행 카드 - 광주은행 카드 - 새마을금고 카드 - 수협은행 카드 - 제주은행 카드 - 신협 카드 - 저축은행 카드 - KDB산업은행 카드
미지원 카드 관련 파라미터 안내 KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useCardPoint`: 카드 포인트 사용 여부. - KCP의 경우 지정하지 않아도 카드 포인트를 사용 가능합니다. - `useInstallment`: 할부 사용 여부. - KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다. - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. - KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.
일부 카드사에 한하여 다이렉트 호출 시 필수 파라미터 안내 PC 환경에서 카드사 다이렉트 결제 요청 시, 다음 카드사들의 경우 `bypass.kcp_v2.site_name`을 필수로 입력해야 합니다. - 신한카드 - 우리카드 - 현대카드 - 삼성카드 - 농협카드 - 하나카드 - 롯데카드 - 씨티카드 모바일 환경에서 카드사 다이렉트 결제 요청 시, 고객사 상호명 파라미터인 `bypass.kcp_v2.site_name`을 필수로 입력해야 합니다.
#### 간편 결제
간편결제 허브형 지원 안내 KCP의 경우 아래 간편결제 허브형을 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` - 삼성페이: `SAMSUNGPAY` - ssg페이: `SSGPAY` - 애플페이: `APPLEPAY` - lpay: `LPAY` - 토스페이: `TOSSPAY` - 페이코: `PAYCO`
미지원 간편결제 관련 파라미터 안내 KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useCardPoint`: 카드사 포인트 사용 여부 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션 - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - `useInstallment`: 할부 사용 여부. - KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다. - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. - KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.
#### 계좌이체
미지원 계좌이체 관련 파라미터 안내 KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 계좌이체 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
#### 가상계좌 결제
미지원 가상계좌 관련 파라미터 안내 KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 가상계좌 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
#### 상품권 결제
상품권 지원 안내 KCP PC, 모바일 결제에서 `giftCertificateType`는 선택 사항입니다. 결제에서 해당 파라미터를 입력하지 않을 경우 결제창 내에서 상품권 종류를 선택할 수 있습니다. KCP에서 지원하는 상품권 종류는 아래와 같습니다. - 도서문화상품권: `BOOKNLIFE` - 컬쳐랜드 문화상품권: `CULTURELAND`
상품권 또는 휴대폰 결제 시 필수 파라미터 안내 KCP에서 상품권, 휴대폰 결제 시 리스크 관리를 위해 고객사 회원의 ID를 필수로 받고 있어, `bypass.kcp_v2.shop_user_id`를 필수로 입력하셔야 합니다.
#### 휴대폰 소액 결제
결제창에 노출될 통신사 지정 옵션 지원 여부 KCP 모바일 결제의 경우 하나의 통신사만 지정할 수 있으며 `availableCarriers`를 사용할 수 없습니다. 통신사 구분 값을 위한 `carrier`만 사용이 가능합니다.
#### 에스크로 결제
에스크로 결제 시 필수 파라미터 안내 KCP 에스크로 결제 시 `products` 파라미터를 필수로 요구합니다. 구매 상품의 정보를 담아 `products` 리스트에 하나 이상의 상품 정보가 포함되어야 합니다.
에스크로 결제 시 입력 권장 파라미터 안내 KCP에서 에스크로 결제 시 예상 배송 소요일인 `bypass.kcp_v2.deli_term`을 입력을 권장하고 있습니다. 입력 형식은 두 자리 수로 입력 되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,'03'으로 입력 정확한 소요일을 알 수 없어 미입력 시 '00'으로 입력됩니다.
## SDK 빌링키 발급 요청하기 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KCP 채널 사용을 명시해주세요. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 **빌링키 발급수단** KCP는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는 `CARD`로 고정해야 합니다. - issueId: string **빌링키 발급 건 고유 ID** - 고객사에서 채번하여 사용해야 합니다. - KCP의 경우 필수 입력해야 합니다. // 추후 수정 필요, 포트원 내부 채번으로 수정할 예정 - issueName: string **빌링키 발급 시 결제창에 표시되는 제목** - 모바일 발급의 경우 필수 입력해야 합니다. - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - offerPeriod?: object **제공 기간** - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - kcp\_v2?: object **KCP에서 제공하는 파라미터 모음** - batch\_soc\_choice?: 'percard' | 'cocard' **결제창에서 주민번호/사업자 번호 고정여부 설정** - S: 주민번호만 표시 - C: 사업자번호만 표시 ### SDK 빌링키 발급 - 유의사항
파라미터 제약 사항 SDK를 통한 빌링키 발급 요청 `offerPeriod` 파라미터를 이용하여 제공 기간을 나타낼 수 있으며, 빌링키 발급 시 `interval`파라미터만 지원됩니다.
카드사 다이렉트 호출 미지원 안내 KCP 경우 카드사 다이렉트 호출을 통한 빌링키 발급을 지원하지 않습니다. `card.cardCompany` 필드에 값을 채워도 빌링키 발급 동작에 아무런 영향을 미치지 않습니다.
## API 수기(키인)결제 요청하기 수기(키인) 결제 요청 시 `POST /payments/${PAYMENT_ID_HERE}/instant` API를 호출해야 합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript // ... 수기(키인) 결제 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: { card: { credential: { nuber: "1234123400001234", // 카드 번호 입력 시 숫자만 입력해주세요. expiryYear: "26", // 유효기간 만료 연도 2자리 expiryMonth: "12", // 유효기간 만료 월 2자리 birthOrBusinessRegistrationNumber: "900101", // 카드 소유주 생년월일 또는 사업자 등록번호 passwordTwoDigits: "00", // 카드 비밀번호 앞 2자리 }, }, }, }, }); ```
```javascript // ... 수기(키인) 결제 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: `테스트`, }, }, }, }); ```
### 주요 파라미터 - paymentId: string **고객사 주문 고유 번호** 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. KCP의 경우 최대 40자까지 허용합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. KCP의 경우 최대 100 바이트까지 허용합니다. - 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 **발급 은행** - 은행코드는 ENUM으로 정의되어 있습니다. - [BANK ENUM 바로가기](https://developers.portone.io/api/rest-v2/payment#Bank) - expiry: object **입금 만료 기한** `validHours` 또는 `dueDate` 필드 중 하나를 지정합니다. - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 RFC 3339 date-time 형식으로 입력해야 합니다. - option: object **가상계좌 발급 방식** - type: string **가상계좌 발급 유형** 회전식 가상계좌만 지원하므로 `NORMAL`로 입력합니다. - cashReceipt: object **현금영수증 정보** - type: string **발급 유형** `PERSONAL` 또는 `CORPORATE`로 입력합니다. - 소득공제용 : `PERSONAL` - 지출증빙용 : `CORPORATE` - customerIdentityNumber: 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?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** ### 유의사항 #### 카드 결제
미지원 파라미터 안내 무이자 및 카드 포인트 파라미터는 지원하지 않습니다. 해당 파라미터를 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다.
#### 가상계좌 결제
고정식 가상계좌 미지원 안내 회전식(일반) 가상계좌만 지원되며, 고정식 가상계좌는 지원하지 않습니다.
가상계좌 발급 시 입금자명 관련 안내 발급된 가상계좌의 입금자명은 결제 요청 시 `customer.name` 파라미터에 입력된 이름으로 표시됩니다. `remitteeName`을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다.
가상계좌 발급 가능 은행 안내 - 아래 은행에 한하여 가상계좌 발급이 가능합니다. - 기업은행 - 국민은행 - 수협은행 - NH농협은행 - 우리은행 - SC제일은행 - iM뱅크 - 부산은행 - 광주은행 - 경남은행 - 우체국 - 하나은행 - 신한은행
## API 빌링키 발급 요청하기 빌링키를 발급 요청 시 `POST /billing-keys`를 호출해야 합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 - KCP의 경우 필수로 입력해야 합니다. - passwordTwoDigits?: string **비밀번호 앞 두자리** - KCP의 경우 필수로 입력해야 합니다. - customer: object **고객 정보** - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - email: string **구매자 이메일** ## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제 요청 시 `POST /payments/${PAYMENT_ID_HERE}/billing-key` API를 호출해야 합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts const response = await axios({ url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/billing-key`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { payment: { billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키 orderName: "후불 결제", customer: { id: "customer-1234", // 고객사에서 관리하는 고객 고유번호 phoneNumber: "010-1234-5678", email: "test@test.com", }, amount: { total: 10000, }, currency: "KRW", }, }, }); ```
### 주요 파라미터 - 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?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - email: string **구매자 이메일** - productCount?: integer **상품 개수** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/schedule` 를 이용하여 결제를 예약합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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-01T00:00:00+09:00", // 결제 예정 시점. RFC 3339 형식으로 입력해야 합니다. }, }); ```
### 주요 파라미터 - 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`로 입력해야 합니다. - customer: object **고객 정보** - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber: string **구매자 연락처** - email: string **구매자 이메일** - timeToPay: string **결제 예정 시점** # https://developers.portone.io/opi/ko/integration/pg/v2/kicc-v2 --- title: 이지페이(KICC) 해외결제 description: 이지페이(KICC) 해외결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 가능한 결제 수단 - **결제창 일반 결제** KICC 해외결제를 통해 위챗페이와 알리페이 플러스를 이용할 수 있습니다. 이용하고자 하는 결제사 별 파라미터는 아래를 참고해주세요. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KICC 채널 사용을 명시해주세요. KICC 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: "PortOne Purchase", totalAmount: 100, // 1 USD currency: "USD", payMethod: "EASY_PAY", easyPay: { easyPayProvider: "WECHAT", }, locale: "KO_KR", customer: { fullName: "PortOne", email: "test@example.com", }, }); } ``` **주요 파라미터 설명** - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. KICC와 위챗페이에서는 영문만 사용하는 것을 권장합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 통화 코드 - `KRW`: 한국 원 - `USD`: 미국 달러 - locale?: Locale **결제창 언어** - `ZH_CN`: 중국어 (중국 본토) (기본값) - `KO_KR`: 한국어 - `EN_US`: 영어 - `ZH_TW`: 중국어 (대만) - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** `fullName`과 `firstName` / `lastName`이 모두 입력된 경우 `fullName`으로 기록됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`이 존재하는 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일 주소**
```javascript 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: "PortOne Purchase", orderDescription: "Description for Order", totalAmount: 100, // 1 USD currency: "USD", payMethod: "ALIPAY_PLUS", alipayPlus: { easyPayProvider: "ALIPAY", }, customer: { fullName: "PortOne", email: "test@example.com", }, }); } ``` **주요 파라미터 설명** - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인 완료 된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. KICC와 알리페이 플러스에서는 영문만 사용하는 것을 권장합니다. - orderDescription: string **주문 상세 정보** 주문 상세 정보로 고객사에서 자유롭게 입력합니다. KICC와 알리페이 플러스에서는 영문만 사용하는 것을 권장합니다. - channelKey: string **채널 키** 콘솔에서 채널 연동 시 생성된 채널 키입니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 통화 코드 - `KRW`: 한국 원 - `USD`: 미국 달러 - alipayPlus: object **알리페이 플러스 정보** - easyPayProvider?: string **알리페이 플러스를 통해 이용할 간편결제** 미입력 시 이용 가능한 간편결제 수단이 모두 노출되는 알리페이 플러스 통합 월렛 화면이 표기됩니다. - `ALIPAY`: Alipay (알리페이) - `TRUE_MONEY`: TrueMoney (트루머니) - `ALIPAY_HK`: AlipayHK (알리페이 홍콩) - `TOUCH_N_GO`: Touch 'n Go (터치앤고) - `G_CASH`: GCash (지캐시) - `DANA`: DANA (다나) - `RABBIT_LINE_PAY`: Rabbit LINE Pay (래빗 라인페이) - `BPI`: BPI - Bank of the Philippine Islands (필리핀 제도 은행) - `BOOST`: Boost (부스트) - `BILL_EASE`: BillEase (빌이즈) - `TINABA`: Tinaba (티나바) - `MPAY`: MPay (엠페이) - `KREDIVO`: Kredivo (크레디보) - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** `fullName`과 `firstName` / `lastName`이 모두 입력된 경우 `fullName`으로 기록됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`이 존재하는 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일 주소** 결제 완료 메일이 발송됩니다.
## 유의 사항
### 결제 승인 위챗페이의 경우 위챗 앱을 이용해 QR코드를 스캔하여 결제를 진행하는 방식으로 결제창이 닫힌 이후에도 구매자가 QR코드를 이미 스캔해둔 상태라면 언제든지 결제 승인이 발생할 수 있습니다. 따라서 PC에서 callback / Mobile에서 redirect 된 이후 결제내역 조회를 통해 확인된 상태값을 100% 신뢰하지 않도록 해야하며 웹훅 연동은 필수로 진행해야합니다. ### 결제 취소 위챗페이의 경우 결제 취소가 비동기로 처리됩니다. 결제 취소 요청에 대한 응답으로 주문 상태를 변경하지 않고 웹훅을 통해 결제 취소 결과를 반영하도록 처리가 필요합니다. ### 도메인 등록 위챗페이는 KICC를 통해 결제창이 오픈될 고객사 결제 페이지 도메인에 대한 등록 요청이 필요합니다. 등록되어있지 않은 도메인에 대해서는 모바일 결제 시도 시 오류 페이지로 연결되므로 유의 바랍니다.
### 결제 승인 알리페이 플러스의 경우 일부 결제 수단은 앱으로 QR코드를 스캔하여 결제를 진행하는 방식으로 결제창이 닫힌 이후에도 구매자가 QR코드를 이미 스캔해둔 상태라면 언제든지 결제 승인이 발생할 수 있습니다. 따라서 PC에서 callback / Mobile에서 redirect 된 이후 결제내역 조회를 통해 확인된 상태값을 100% 신뢰하지 않도록 해야하며 웹훅 연동은 필수로 진행해야합니다.
# https://developers.portone.io/opi/ko/integration/pg/v2/kpn --- title: 한국결제네트웍스(KPN) description: 한국결제네트웍스(KPN) 결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 사전 계약 안내 아래 기능을 사용하시려면 한국결제네트웍스(KPN)에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다. - API를 통한 수기(키인) 결제 (카드, 가상계좌) - API를 통한 빌링키 발급 - 에스크로 결제 (결제창) - 가상계좌 입금통보 설정 (백노티) - 상점분담무이자 설정 - 부분무이자 설정 - 비과세 금액 직접 설정 - 간편결제 다이렉트 호출 - 결제 취소 시 계좌 환불 서비스 설정 ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액 결제 : `MOBILE` - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `CARD` - **API 수기(키인) 결제** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 - 가상계좌: `virtualAccount` 로 설정하여 가상계좌 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/payment#post%20%2Fpayments%2F%7BpaymentId%7D%2Finstant) 를 참고해주시기 바랍니다. - **API 빌링키 발급** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/billingKey#post%20%2Fbilling-keys)를 참고해주시기 바랍니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 한국결제네트웍스(KPN) 채널 사용을 명시해주세요. 한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="SDK 결제 요청" 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${Math.random().toString(36).slice(2)}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", payMethod: "CARD", }); } ``` ### 주요 파라미터 - 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` - bypass?: object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - kpn?: object **한국결제네트웍스(KPN)에서 제공하는 파라미터** - CardSelect?: enum\[] **일부 렌더링할 결제방식 목록** 특정 카드사로 구별되지 않는 결제수단을 지정할 때 사용합니다. - 해외카드 (VISA + MASTER + JCB) : `GLOBAL` - 구인증 : `LEGACY_AUTH` - 키인 : `KEY_IN` ### 유의사항 #### 공통
`paymentId`의 경우 영문 대/소문자 및 숫자만 허용됩니다. `paymentId` 입력시 0-9,a-z,A-Z 의 문자만 입력 가능합니다. 한글이나 `♤`, `♡`, `♧` 등의 특수 문자 입력시 결제가 정상적으로 동작하지 않을 수 있습니다.
결제창 표시 언어 지원 안내 SDK를 통한 결제 요청시 `locale` 파라미터를 사용하여 결제창 내에 언어를 제어할 수 있습니다. 한국결제네트웍스(KPN)의 경우 한국어 및 영어만 지원합니다. - 한국어 : `KO_KR` - 영어 : `EN_US`
지원되는 결제 통화 SDK를 통한 결제 요청시 `currency` 파라미터를 사용하여 통화를 설정할 수 있습니다. 한국결제네트웍스(KPN)의 경우 `KRW` 만 지원합니다. - 원화 : `KRW`
결제 요청 시 면세금액 설정 시 우선 적용 안내 계약 당시 MID를 면세, 과세 용도로 나누어서 발급받은 경우에도 결제 요청시 파라미터로 전달하는 금액 정보를 우선 사용합니다. 고객사에서 면세 또는 과세금액을 계산하여 처리하는 경우 `totalAmount`와 `taxFreeAmount`를 올바르게 전달하여야 합니다.
#### 카드 결제
카드 관련 미지원 파라미터 안내 한국결제네트웍스(KPN)의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useAppCardOnly`: 앱카드만 허용할지 여부 - `useFreeInterestFromMall`: 상점부담무이자 사용 여부
카드 다이렉트 호출 지원 카드사 안내 KPN을 이용하시는 경우 아래 카드사 한해 다이렉트 호출이 가능합니다. - 신한카드 - 현대카드 - 삼성카드 - 농협카드 - 하나카드 - 롯데카드 - 씨티카드 - 우리카드 - 비씨카드 - 국민카드 - 우체국은행 카드 - 새마을금고 카드 - 신협 카드 - 저축은행 카드 - KDB산업은행 카드 - 카카오뱅크 카드 - 케이뱅크 카드 ```typescript title="SDK 카드 다이렉트 결제 요청" 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${Math.random().toString(36).slice(2)}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", payMethod: "CARD", card: { cardCompany: "KOOKMIN_CARD", // 국민카드 다이렉트 }, }); } ```
카드 다이렉트 이용 시 약관동의 절차 안내 다이렉트 호출시 아래 3가지 약관 동의 절차가 고객사 페이지 내에 있어야 합니다. - `https://www.firstpay.co.kr/jsp/common/agreementPopup.jsp?type=1` (전자금융거래 이용약관) - `https://www.firstpay.co.kr/jsp/common/agreementPopup.jsp?type=3` (개인정보 수집 및 이용처리 동의) - `https://www.firstpay.co.kr/jsp/common/agreementPopup.jsp?type=4` (개인정보 제3자 제공 동의) 영어 약관이 필요한 경우 URL 뒤에 `&langType=ENG`을 추가하여 사용할 수 있습니다.
#### 간편 결제
간편결제 다이렉트 호출 지원 안내 한국결제네트웍스(KPN)의 경우 아래 간편결제사를 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 값을 입력하여 간편결제사를 지정하여 호출할 수 있습니다. - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` - 삼성페이: `SAMSUNGPAY` - 토스페이: `TOSSPAY` - 페이코: `PAYCO`
네이버페이 다이렉트 호출 미지원 한국결제네트웍스(KPN)의 경우, 현재 네이버페이 다이렉트 호출은 지원하지 않습니다.
간편결제 관련 미지원 파라미터 안내 한국결제네트웍스(KPN)의 경우 간편결제 결제시 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `useCardPoint`: 카드사 포인트 사용 여부 - `useFreeInterestFromMall`: 상점부담무이자 사용 여부 - `useInstallment`: 할부 사용 여부 - `cashReceiptType`: 현금영수증 타입 - `installment`: 할부 설정 - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션
#### 계좌이체
계좌이체 관련 미지원 파라미터 안내 한국결제네트웍스(KPN)의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 계좌이체 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
현금영수증 발급 유형 지원 안내 현금영수증은 현금성 거래인 실시간 계좌이체 및 가상계좌 발급 시 사용이 가능합니다. 한국결제네트웍스(KPN)의 경우 현금영수증 발급 유형을 `CORPORATE` 혹은 `PERSONAL` 등 파라미터로 제어할 수 없습니다. 결제창 내에서 선택한 유형으로 현금영수증은 발급되며, 결제창 호출 파라미터로는 현금영수증을 발행 여부만을 제어할 수 있습니다. `cashReceiptType` 파라미터를 `ANONYMOUS`로 설정시 결제창에서 현금영수증 발급 UI가 미노출됩니다.
#### 가상계좌 결제
가상계좌 관련 미지원 파라미터 안내 한국결제네트웍스(KPN)의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 가상계좌 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
가상계좌 사용시 입금통보 URL 설정 안내 한국결제네트웍스(KPN)의 경우, 가상계좌를 사용하는 경우 입금통보 URL을 별도로 설정해야 합니다. 자세한 내용은 [가상계좌 입금통보 URL 설정 가이드](https://developers.portone.io/opi/ko/integration/virtual-account/readme?v=v2#notice-config-kpn)를 참조해 주세요.
가상계좌 지원 은행 안내 한국결제네트웍스(KPN)에서 가상계좌 발급이 가능한 은행은 아래와 같습니다. 은행코드는 [BANK ENUM](https://developers.portone.io/api/rest-v2/payment#Bank)으로 정의되어 있으며 아래 목록에 대한 ENUM 코드를 매핑하여 API에 사용하실 수 있습니다. - 기업은행 - 국민은행 - 외환은행 - 농협은행 - 우리은행 - SC은행 - 한국씨티은행 - 대구은행 - 부산은행 - 광주은행 - 경남은행 - 우체국 - KEB하나은행 - 신한은행
현금영수증 발급 유형 지원 안내 현금영수증은 현금성 거래인 실시간 계좌이체 및 가상계좌 발급 시 사용이 가능합니다. 한국결제네트웍스(KPN)의 경우 현금영수증 발급 유형을 `CORPORATE` 혹은 `PERSONAL` 등 파라미터로 제어할 수 없습니다. 결제창 내에서 선택한 유형으로 현금영수증은 발급되며, 결제창 호출 파라미터로는 현금영수증을 발행 여부만을 제어할 수 있습니다. `cashReceiptType` 파라미터를 `ANONYMOUS`로 설정시 결제창에서 현금영수증 발급 UI가 미노출됩니다.
#### 휴대폰 소액결제
필수 입력 파라미터 안내 한국결제네트웍스(KPN)의 경우 **휴대폰 소액결제 시 상품 유형을 구분짓는 `productType` 파라미터를 필수**로 입력해야 합니다. - 실물 : `PRODUCT_TYPE_REAL` - 디지털 : `PRODUCT_TYPE_DIGITAL`
휴대폰 소액결제 관련 미지원 파라미터 한국결제네트웍스(KPN)의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `carrier`: 휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값 - `availableCarriers`: 결제창에 노출될 통신사 리스트 지정 옵션
## SDK 빌링키 발급 요청하기 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 한국결제네트웍스(KPN) 채널 사용을 명시해주세요. 한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="SDK 빌링키 발급 요청" 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: { customerId: "uniqueCustomerId", fullName: "포트원", }, }); } ``` ### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyMethod: string **빌링키 발급수단** 한국결제네트웍스(KPN)는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는 `CARD`로 고정해야 합니다. - customer?: object **고객 정보** - customerId?: string **구매자 고유 ID** - 한국결제네트웍스(KPN)의 경우 구매자 ID를 필수로 입력해야 합니다. - fullName?: string **구매자 전체 이름** - 한국결제네트웍스(KPN)의 경우 `fullName` 혹은 (`firstName` + `lastName`)을 필수로 입력해야 합니다. - firstName?: string **구매자 이름** - 한국결제네트웍스(KPN)의 경우 `fullName` 혹은 (`firstName` + `lastName`)을 필수로 입력해야 합니다. - lastName?: string **구매자 성** - 한국결제네트웍스(KPN)의 경우 `fullName` 혹은 (`firstName` + `lastName`)을 필수로 입력해야 합니다. ### 유의사항
파라미터 입력 형식 안내 SDK를 통한 빌링키 발급 요청 시 `offerPeriod` 파라미터를 사용하여 결제창 내에 제공 기간을 표시할 수 있습니다. 해당 파라미터는 range형태로만 입력 가능합니다. 구체적인 형식은 SDK 가이드를 참고해주세요. [결제요청 파라미터 가이드 바로가기](https://developers.portone.io/docs/ko/v2-payment/v2-sdk/payment-request?v=v2)
결제창 표시 언어 지원 안내 SDK를 통한 빌링키 발급 요청시 `locale` 파라미터를 사용하여 결제창 내에 언어를 제어할 수 있습니다. 한국결제네트웍스(KPN)의 경우 한국어 및 영어만 지원합니다. - 한국어 : `KO_KR` - 영어 : `EN_US`
카드 다이렉트 호출 미지원 안내 한국결제네트웍스(KPN) 경우 빌링키 발급 시 카드사 다이렉트 호출 기능을 지원하지 않습니다. `card.cardCompany` 필드에 값을 입력한 후 빌링키 발급을 요청한 경우에도 빌링키 발급 동작에 아무런 영향을 미치지 않습니다.
## API 수기(키인) 결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant` API를 통해 결제를 요청해야 합니다. ```typescript title="API 수기(키인) 결제 요청" // ... 수기(키인) 결제 const issueResponse = await axios({ url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { paymentId: `payment${Math.random().toString(36).slice(2)}`, channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. orderName: "나이키 와플 트레이너 2 SD", amount: { total: 10000, taxFree: 3000, }, currency: "KRW", customer: { name: { full: "홍길동", }, phoneNumber: "010-1234-0000", }, method: { virtualAccount: { bank: `SHINHAN`, expiry: { dueDate: `2024-11-12T00:00:00+09+00`, // 입금기한은 미래시간만 가능합니다. }, cashReceipt: { type: `PERSONAL`, customerIdentityNumber: `010-1234-0000`, }, }, }, }, }); ``` ### 주요 파라미터 - 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 **발급 은행** - 은행코드는 ENUM으로 정의되어 있습니다. - [BANK ENUM 바로가기](https://developers.portone.io/api/rest-v2/payment#Bank) - expiry: object **입금 만료 기한** - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 ISO8601 형식으로 입력해야 합니다. - option: object **가상계좌 발급 방식** - type: string **가상계좌 발급 유형** 발급 유형은 ENUM으로 정의되어 있습니다. - 회전식 가상계좌 : `NORMAL` 한국결제네트웍스(KPN)의 경우 **회전식 가상계좌**(`NORMAL`)만 지원합니다. 회전식 가상계좌는 일반적으로 사용되는 방식이며 PG사에서 직접 채번한 가상계좌번호를 사용합니다. - cashReceipt: object **현금영수증 정보** - type: string **발급 유형** 발급 유형은 ENUM으로 정의되어 있습니다. - 소득공제용 : `PERSONAL` - 지출증빙용 : `CORPORATE` - 미발행 : `NO_RECEIPT` - customerIdentityNumber: string **현금영수증 식별 번호** - 소득공제인 경우 주민등록번호 혹은 휴대폰 번호를 입력해야 합니다. - 지출증빙인 경우 사업자등록번호를 입력해야 합니다. - card?: object **카드 결제 시 파라미터** - credential: object **인증 관련 정보** - number: string **카드 번호** - expiryYear: string **유효 기간 만료 연도 (YY 형식 ex. 24)** - expiryMonth: string **유효기간 만료 월 (MM 형식 ex. 05)** - birthOrBusinessRegistrationNumber?: string **생년월일 6자리 또는 사업자 등록 번호** - passwordTwoDigits?: string **비밀번호 앞 두자리** - customer?: object **고객 정보** - name?: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first: string **이름** - last: string **성** - phoneNumber?: string **구매자 연락처** ### 유의사항
카드 정보 입력 파라미터 안내 API를 통한 수기(키인) 결제 요청 파라미터에는 카드의 상세 정보를 입력하는 필드가 존재합니다. 한국결제네트웍스(KPN)의 경우 카드 번호 + 유효기간만으로 결제가 가능하나, 일부 고객사의 경우 생년월일 + 비밀번호 앞 두 자리를 추가적으로 입력이 필요할 수 있습니다. 자세한 내용은 한국결제네트웍스(KPN) 담당자에게 문의해주시기 바랍니다.
결제 통화 지원 안내 API를 통한 수기(키인) 결제 요청시 `currency` 파라미터를 이용하여 통화를 지정할 수 있습니다. 한국결제네트웍스(KPN)의 경우 `KRW`와 `USD`를 지원하며, 이 중 `USD`로 지정한 경우 해외카드 결제만 가능합니다. 결제는 1센트 단위로 가능하지만 매입사에 따라 결제 취소가 불가능할 수 있습니다. 결제 취소의 경우 1달러 이상 금액부터 가능한 경우가 발생할 수 있습니다. 자세한 내용은 한국결제네트웍스(KPN) 담당자에게 문의해주시기 바랍니다.
가상계좌 에스크로 결제 미지원 안내 한국결제네트웍스(KPN)의 경우, API 수기(키인) 결제를 통한 가상계좌 발급 시 에스크로 결제는 지원하지 않습니다. 가상계좌 에스크로 결제 이용을 원하시는 경우 결제창 방식으로 발급하여 사용하시길 권장드립니다.
## API 빌링키 발급 요청하기 빌링키를 발급하기 위해서는 `POST /billing-keys` API를 이용하여 빌링키 발급을 요청해야 합니다. 한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="API 빌링키 발급 요청" 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", // 고객사에서 관리하는 고객 고유번호 name: { full: "홍길동", }, phoneNumber: "010-1234-0000", }, 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 **고객 이름** - 한국결제네트웍스(KPN)의 경우 full 혹은 separated를 필수로 입력해야 합니다. * full?: string **한 줄 이름 형식 (ex. 김포트)** * separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** ### 유의사항
필수 파라미터 안내 한국결제네트웍스(KPN)의 경우에는 빌링키 발급 시 아래의 파라미터를 필수로 입력해야 합니다. - `customer.name.full` 혹은 `customer.name.separated` 그 외에는 위에서 설명한 주요 파라미터들을 참고하여 입력해주시기 바랍니다.
## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제를 진행하려면 `POST /payments/${PAYMENT_ID_HERE}/billing-key` API를 이용하여 결제를 요청하실 수 있습니다. 한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="API 빌링키 단건 결제" 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?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 진행하려면 `POST /payments/${PAYMENT_ID_HERE}/schedule` API를 이용하여 결제를 예약하실 수 있습니다. 한국결제네트웍스(KPN) 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="API 예약/반복 결제" 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, taxFree: 3000, }, 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 **고객 이름** - 한국결제네트웍스(KPN)의 경우 full 혹은 separated를 필수로 입력해야 합니다. * full?: string **한 줄 이름 형식 (ex. 김포트)** * separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** ## 공통 유의사항
부가세 지정금액 결제 미지원 한국결제네트웍스(KPN)의 경우 결제 시 부가세액을 직접 지정할 수 없습니다. 결제 요청 파라미터에 VAT(부가세)를 지정하시더라도 해당 값은 무시되며, 결제 금액에 대한 부가세는 한국결제네트웍스(KPN)에서 자동으로 계산됩니다. 만약 결제 요청시 VAT(부가세) 파라미터에 금액을 지정하는 경우 결제 조회시 요청 파라미터에 입력한 값이 응답으로 내려가므로, 부가세 파라미터를 지정하지 않는 것을 권장드립니다.
환불서비스 신청 안내 한국결제네트웍스(KPN)의 경우 계좌 환불의 형태로 결제를 취소하려면 별도 설정을 진행해야 합니다. 일반적으로 아래와 같은 경우에 대해 계좌 환불 서비스 신청이 필요합니다. - 가상계좌 입금 후 환불 - 휴대폰 결제 후 익월 환불 - 계좌이체 취소가 불가능한 경우(환불 기한 초과, 계좌 제한 등) 또한, 위 환불 서비스를 이용할 경우에는 결제 취소시 환불 계좌 정보를 필수적으로 입력해야 합니다. 자세한 내용은 한국결제네트웍스(KPN) 담당자에게 문의해주시기 바랍니다.
# https://developers.portone.io/opi/ko/integration/pg/v2/ksnet --- title: KSNET description: KSNET 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/ksnet/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## 가능한 결제수단 - **SDK 결제** - `payMethod` 파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다. - 신용카드 : `CARD` - 실시간 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 간편 결제 : `EASY_PAY` - **API 수기(키인) 결제** - `method` 파라미터 내부 필드를 결제수단에 따라 아래와 같이 선택해야 합니다. - 신용카드 : `card` - 가상계좌 : `virtualAccount` - **SDK 빌링키 발급** - `billingKeyMethod`(빌링키 발급) 파라미터를 `CARD`로 설정해야 합니다. - **API 빌링키 발급** - `method` 파라미터 내부 필드를 `card`로 선택해야 합니다. ## SDK 결제 및 빌링키 발급 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야합니다. `channelKey` 파라미터에 결제 채널 연동 시 생성된 채널 키값을 지정하여 KSNET 연동임을 명시해주세요. 만약 `channelKey`가 입력되지 않는 경우 `pgProvider` 파라미터에 입력된 값에 따라 결제창이 호출됩니다. KSNET 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. paymentId: `payment-${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "CARD", card: { cardCompany: "BC_CARD", }, }); } ```
## API 수기(키인)결제 및 빌링키 발급 및 예약/반복 결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant/pay`를 이용하여 결제 요청을 해야합니다. 그리고 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. 이후 발급된 빌링키로 예약/반복 결제를 하기위해 `POST /schedules` 를 이용하여 결제를 예약합니다.
```ts // ... 수기(키인) 결제 const issueResponse = await axios({ url: `https://api.portone.io/payments/${encodeURIComponent(PAYMENT_ID_HERE)}/instant`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { channelKey, orderName, productType, customer: { id: customerId, name: { first: firstName, last: lastName, }, }, amount: { total: totalAmount, }, currency, method: { card: { credential: { number: cardNumber, expiryYear, expiryMonth, birthOrBusinessRegistrationNumber, passwordTwoDigits, }, }, }, }, }); ```
```ts // ... 빌링키 발급 const issueResponse = await axios({ url: "https://api.portone.io/billing-keys", method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { channelKey, customer: { id: customerId, }, method: { card: { credential: { number: cardNumber, expiryYear, expiryMonth, birthOrBusinessRegistrationNumber, passwordTwoDigits, }, }, }, }, }); ```
```ts async function schedulePayment() { // 포트원 결제 예약 API 호출 const response = await axios({ url: `https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/schedule`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { payment: { billing_key: BILLING_KEY_HERE, orderName: "월간 이용권 정기결제", customer: { id: CUSTOMER_ID_HERE, // 고객 정보가 필요한 경우 API 명세에 따라 추가해주세요. }, amount: { total: 8900, }, currency: "KRW", }, timeToPay: "2023-08-24T14:15:22Z", // 결제를 시도할 시각 }, }); // 결제 예약 이후 로직을 구성해주세요. } ```
## 주요 파라미터 - storeId: string 고객사의 상점을 식별하는 고유한 값입니다. - paymentId: string 고객사가 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. - orderName: string 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키로 호출하고자 하는 채널을 지정합니다. - totalAmount: number 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string 결제통화로 원화 결제를 원할 시 `KRW`로 입력해야 합니다. KSNET의 경우 `KRW`와 `USD`를 지원합니다. - payMethod: string 결제수단을 구분하는 코드로 원하는 결제수단 값을 입력해야 합니다. - customer.fullName: string 구매자 이름으로 KSNET의 경우 필수로 입력해야 합니다. - taxFreeAmount?: number 면세 금액으로 KSNET과 상점아이디 계약시 복합과세로 계약한 경우 면세 처리를 위해 면세금액을 반드시 입력해야 합니다. 면세금액 미 입력 시 면세금액은 0원으로 자동 처리되며, 결제 요청 금액은 모두 과세 처리 되오니 이 점 유의하시기 바랍니다. - card.cardCompany: string 카드사 다이렉트 호출 시 결제대행사의 통합결제창을 거치지 않고, 지정한 카드사의 결제화면이 호출됩니다. 카드사별로 지원하는 기능이 상이함으로, 카드 다이렉트 호출 유의사항을 확인해 주세요. ## 유의할 파라미터 - SDK ### SDK 결제/빌링키 발급 공통 - windowType?: string - KSNET의 경우 PC는 `IFRAME`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다. - `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다. ```json { "pc": "IFRAME", "mobile": "REDIRECTION" } ``` - locale?: string - KSNET의 경우 `KO_KR`만 지원합니다. 이외의 값을 넣어도 무시됩니다. - redirectUrl?: string - 모바일 환경에서 결제 요청 시 `REDIRECTION` 타입이므로, 필수로 입력해야 합니다. ### API 결제 - productType: string 판매 상품에 대한 상품 유형 파라미터로 API 결제 시 필수로 입력해야 합니다. - `PHYSICAL`: 실물 상품 - `DIGITAL` : 디지털 상품 ### SDK 결제 (`requestPayment`) - productType?: string 휴대폰 결제인 경우 필수로 입력해야 하며, KSNET의 상점아이디에 설정된 상품 유형과 일치해야합니다. 디지털 상품유형으로 설정된 경우 항상 `PRODUCT_TYPE_DIGITAL`로 입력해야 합니다. - `PRODUCT_TYPE_REAL`: 실물 상품 - `PRODUCT_TYPE_DIGITAL` : 디지털 상품 - bypass?: object - ksnet?: object - sndQpayType?: string 카드 결제 시 결제창에 간편 결제 수단 표시 여부를 설정할 수 있습니다. - `0` : 간편결제 수단 표시 하지 않음 - `1` : 간편결제 수단 표시함 - sndKakaopayType?: string 카카오페이 결제시 허용할 결제수단 - `CARD`: 카드 결제만 허용 - `MONEY`: 카카오머니 결제만 허용 - 미입력시 모든 결제수단 허용 ### 카드 다이렉트 호출 - customer?: object - fullName?: string - KSNET을 통한 카드사 다이렉트 호출 시, 구매자명 파라미터는 필수 입력입니다. - phoneNumber?: string - 모바일 환경에서 **BC카드, 수협카드, 전북카드, 광주카드, 카카오뱅크카드** 를 다이렉트 호출하는 경우, 필수 입력입니다. - bypass?: object - ksnet?: object - tcode?: string - 모바일 환경에서 **BC카드, 수협카드, 전북카드, 광주카드, 카카오뱅크카드** 를 다이렉트 호출하는 경우, 필수 입력입니다. - 통신사에 따라 LG는 lgt, KT는 ktf, SKT는 skt로 입력해야 하며, 통신사 구분이 어려우신 경우 임의의 값을 입력하여 요청해도 무방합니다. - url?: string - **우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우 필수 입력입니다. - storeDetails?: object - businessName?: string - **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 필수 입력입니다. - businessRegistrationNumber?: string - **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 필수 입력입니다. - installments?: object - monthOption?: object - availableMonthList?: number\[] - **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 렌더링할 할부개월 리스트를 지정할 수 있습니다. ## 연동 유의사항 ### KSNET과 사전 계약이 필요한 경우 포트원을 통해 KSNET을 이용하고자 하는 고객사의 경우 상점아이디의 과세설정이 반드시 `복합과세`로 설정되어 있어야 합니다. 아래의 기능을 사용하려면 사전 신청을 통해 KSNET과 계약을 완료해야 합니다. 계약을 하지 않은 경우 해당 기능을 이용하여 결제 시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와 다른 응답을 받을 수 있습니다. (ex. 에스크로 결제를 요청하여 결제를 진행하였으나 비-에스크로 결제 응답을 받는 경우) - 키인결제 - 고객사 부담 무이자 할부 설정 - 가상계좌 입금마감기한 지정 - 가상계좌 환불 - 간편결제 - 신용카드 할부 - 에스크로 (배송 에스크로만 지원) - KSNET에서는 일반 에스크로, 배송 에스크로 두 가지 유형의 에스크로를 제공하고있으나, 포트원에서는 KSNET 배송 에스크로만 제공하고 있으므로 에스크로 사용을 원할 시 KSNET에 **배송 에스크로**로 설정을 요청 해야합니다. - 휴대폰 결제 - KSNET을 통해 상품 유형 설정(ex. 실물 혹은 디지털) 요청을 해야합니다. ### 카드 결제 - `card.installment.freeInstallmentPlans.cardCompany` 파라미터는 일부 카드사에 대해서만 적용 가능합니다. - 지원 가능한 카드 : 비씨,국민,하나,삼성,신한,현대,롯데,농협 - 지원 불가능한 카드 : 씨티
파라미터 사용 예시 ```json { "card": { "installment": { "freeInstallmentPlans": [ { "cardCompany": "KOOKMIN_CARD", "months": [9, 10] } ] } } } ```
- 결제 통화 `currency`를 `USD`로 지정하여 결제 요청한 경우 해외 발급 카드로만 결제가 가능합니다. 국내에서 발급받은 해외 겸용 카드는 결제 승인이 불가합니다. ### 간편결제 - 간편결제 시 무이자 할부 설정은 불가능하며, 할부 개월 수 표시 설정은 일부 간편결제에서만 가능합니다. - 지원 가능한 간편결제 : 네이버페이, 카카오페이, L페이 - 지원 불가능한 간편결제 : 페이코, SSG페이 (1\~12개월 표시 고정) - 간편결제로 결제 요청 시 고객사 분담 무이자 설정은 사용이 불가능합니다. - 간편결제 중 카카오페이, 페이코를 통한 카드 결제의 경우 포트원으로 전달되는 결제 응답에 카드정보가 제공되지 않아 결제 정보에 카드사 정보가 제공되지 않습니다. - 카카오페이 사용을 원하실 경우 앱 또는 웹 하단에 대표자명, 주소, 전화번호와 같은 상점정보를 필수로 입력해야합니다. ### 간편결제 다이렉트 - KSNET 간편결제 다이렉트는 아래의 결제 방식을 지원합니다. - 네이버페이 카드 - 카카오페이 카드 및 머니 - 페이코 - L페이 카드 - 네이버페이 머니·포인트의 경우 현재 KSNET에서는 다이렉트 호출을 지원하지 않습니다. - 간편결제 다이렉트를 사용하기 위해서는 `bypass.ksnet.easyPayDirect`를 `true`로 설정하고, `payMethod`를 `EASY_PAY`, `easyPay.easyPayProvider`를 `NAVERPAY`, `KAKAOPAY`, `PAYCO`, `LPAY` 중 하나로 지정합니다. - 구매자 이름(`customer.fullName`)을 입력해야 합니다. - 네이버페이의 경우 - 현재 카드 결제만 가능 - 상점명(`storeDetails.businessName`) 필수 - `customer.email`, `customer.phoneNumber` 선택 - 할부 개월 수 표시 설정 가능 - 이용 가능 카드사 설정 가능 (신한, BC, 국민, 농협, 롯데, 삼성, 시티, 우리, 하나, 현대) - 카카오페이의 경우 - 상점 대표자명(`storeDetails.ceoFullName`) 필수 - 상점 주소(`storeDetails.address`) 필수 - 상점 전화번호(`storeDetails.phoneNumber`) 필수 - `customer.email`, `customer.phoneNumber` 필수 - `easyPay.availablePayMethods`로 결제 유형 한정 가능(`["CARD"]`로 지정할 경우 카드만, `["MONEY"]`로 지정할 경우 머니만) - 할부 개월 수 표시 설정 가능 - 이용 가능 카드사 설정 가능 (신한, BC, 국민, 농협, 롯데, 삼성, 시티, 우리, 하나, 현대) - 페이코의 경우 - 상점명(`storeDetails.businessName`) 필수 - 사업자등록번호(`storeDetails.businessRegistrationNumber`) 필수 - `customer.email`, `customer.phoneNumber` 필수 - L페이의 경우 - `customer.email`, `customer.phoneNumber` 선택 ### 계좌이체 - SDK로 계좌이체 결제 요청 시 결제창 내에서 현금영수증 발급을 위한 정보 입력 시 휴대폰 번호 및 사업자번호는 숫자만 입력해야 합니다. 하이픈(-)을 포함한 다른 문자가 포함되는 경우 별다른 에러 표시 없이 결제는 정상승인되지만 현금영수증이 발급되지 않으니 유의하여 사용이 필요합니다. ### 가상계좌 - KSNET의 경우 가상계좌 발급 시 예금주명은 고객사명으로 고정되어 별도의 지정이 불가능합니다. - KSNET의 경우 일회성 가상계좌의 경우 부가세, 면세 금액 설정을 지원하지 않습니다. - KSNET의 경우 가상계좌 환불 기능은 특약이 있는 고객사만 사용 가능하며, KSNET과 사전에 계약 진행이 필요합니다. - 포트원을 통한 KSNET을 사용하는 경우 가상계좌 발급 시 입금기한을 필수로 입력하여 사용해야 합니다. 입금기한을 입력하지 않는 경우 가상계좌 에러를 리턴하고, 가상계좌가 정상적으로 발급되지 않습니다. - 가상계좌 발급 시 입금 기한은 `virtualAccount.accountExpiry.dueDate` 또는 `virtualAccount.accountExpiry.validHours` 파라미터로 설정해야하며 `dueDate`는 ISO8601 형식으로, `validHours`는 number 형식으로 입력해야 합니다.
ISO8601 형식 예시 - YYYY-MM-DDTHH:mm:ssZ - YYYY-MM-DDTHH:mm:ss±hh:mm
- 가상계좌 결제 건 결제취소(환불)은 06:00 \~ 23:00 까지만 가능하며, 이 외의 시간에 시도하면 에러를 리턴합니다. 이는 KSNET의 정책으로 포트원과 무관합니다. - 가상계좌 결제 시 결제창에서 발급한 현금영수증의 경우 해당 거래가 취소되더라도 자동으로 취소되지 않습니다. 따라서, 직접 현금영수증 발급 취소를 진행해야 하므로 유의하시기 바랍니다. - 복합과세가 적용된 가상계좌 결제 후 부분 취소하는 경우 기존에 발급한 현금영수증을 취소하고, 부분취소 금액이 반영된 금액 정보로 현금영수증을 재발급해야 합니다. ### 휴대폰결제 - 휴대폰 소액 결제 승인 건은 부분취소가 불가능합니다. ### 에스크로 - 에스크로 거래는 SDK 결제에서만 가능합니다. - 에스크로 결제 시 구매 확정을 위해 주문자 이메일(`customer.email`)을 필수로 입력해야 합니다. - 에스크로 거래는 KSNET 관리자 페이지 (ksta.ksnet.co.kr > PG 거래내역 > 배송 에스크로 거래조회)에서 거래 후 30분\~ 1시간 뒤 확인이 가능합니다. 에스크로 정보 수정의 경우도 등록이 완료된 이후부터 가능하오니 유의해서 사용이 필요합니다. - 에스크로 배송정보 등록/변경 API (POST `/payments/${PAYMENT_ID_HERE}/escrow/logis`)에 사용되는 배송정보 발송일시 `logistics_form.send_at` 파라미터는 ISO8601 형식으로 입력해야 합니다.
ISO8601 형식 예시 - YYYY-MM-DDTHH:mm:ssZ - YYYY-MM-DDTHH:mm:ss±hh:mm
### API 수기(키인) 결제 - 고객사 분담 무이자를 원하시는 경우 KSNET과 별도의 계약 후 method.card.useFreeInterestFromMerchant 파라미터를 true로 입력하여 사용 가능합니다. - 포트원을 통한 KSNET API 수기(키인) 결제는 카드 번호와 유효기간만으로 결제를 요청하는 비인증 승인 API만 연동되어 있어 `birthOrBusinessRegistrationNumber` 와 `passwordTwoDigits` 는 검증하지 않습니다. ### API 빌링키 발급 - method.card.credential의 `number`, `expiryYear`, `expiryMonth`, `birthOrBusinessRegistrationNumber`, `passwordTwoDigits` 파라미터는 필수 입력해야 합니다. ### 빌링키 결제 - 고객사 분담 무이자를 원하시는 경우 KSNET과 별도의 계약 후 `card.use_free_interest_from_mall` 파라미터를 true로 입력하여 사용 가능합니다. ### 기타 - 카드, 간편결제를 제외한 결제수단의 경우 매출 전표 확인이 불가능합니다. 이는 KSNET 정책으로 포트원과 무관합니다. - 카드결제, 계좌이체, 가상계좌, 간편결제로 정상 승인된 건에 대해 부분취소를 하는 경우 총 9회까지 가능합니다. - 결제 취소는 결제일 기준 6개월 이내 거래건만 가능합니다. - KSNET의 경우 승인 영수증 및 취소 영수증 확인 시 자동으로 인쇄 기능이 호출되며, 이는 KSNET의 정책으로 포트원과 무관합니다. - 결제 시 면세 금액이 포함된 경우 면세 금액 (`taxFreeAmount`) 파라미터에 정확한 금액을 입력해야 하며, 입력하지 않을 경우 매출전표 및 실제 처리 내역이 다를 수 있습니다. - KSNET의 경우 상점 분담 무이자 할부 설정은 카드 발급사가 **비씨,국민,하나,삼성,신한,현대,롯데,농협**인 카드에 대해서만 가능합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/naverpay --- title: 네이버페이 (결제형) description: 네이버페이 간편결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/naver --- ## 네이버페이 (결제형) 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## 가능한 결제 수단 - 간편 결제 - `payMethod`(결제) 혹은 `billingKeyMethod`(빌링키 발급) 파라미터를 `EASY_PAY` 로 설정해야 합니다. - 결제창 내에서 카드, 계좌이체, 네이버페이 머니 충전식 결제 중 선택이 가능합니다. ## SDK - 유의할 파라미터 ### 결제/빌링키 발급 공통 - `windowType` - 네이버페이의 경우 PC는 `POPUP`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다. - `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다. ```json { "pc": "POPUP", "mobile": "REDIRECTION" } ``` - `locale` - 네이버페이의 경우 `KO_KR`만 지원합니다. 이외의 값을 넣어도 무시됩니다. - `easyPay` - `easyPayProvider` - 네이버페이의 경우 PG사 자체가 간편결제사이므로 `easyPayProvider` 는 비워두어도 무방하며 다른 값을 채울 경우 무시됩니다. - `currency` - 네이버페이의 경우 원화 결제만 지원하므로 `KRW` 이외의 값을 넣으면 에러를 리턴합니다. ### 결제 (`requestPayment`) - `payMethod` - `EASY_PAY` 로 설정해야 합니다. - `bypass` - 포트원에서 정규화한 파라미터 이외에 네이버페이에서만 특수하게 지원하는 파라미터들을 `bypass` 를 통해 넘겨줄 수 있습니다. - `useCfmYmdt` - 이용완료일 - `YYYYMMDD` 형식의 문자열로 넘겨야 합니다. - 상품 유형에 따라 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다 - `productItems` - 상품 정보 - 네이버페이의 상품 정보는 일반화된 Product 파라미터가 아닌 해당 파라미터로 넘겨주어야 합니다.
`productItem`의 배열을 넘겨야 합니다. `productItem` 은 다음 6개의 속성으로 하나의 상품 정보를 표현하는 객체의 배열입니다. - **`categoryType`** (필수) : [공식 매뉴얼](http://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 - **`categoryId`** (필수) : [공식 매뉴얼](http://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 - **`uid`** (필수) : 고객사 내부의 상품 고유 ID를 활용하는 것이 일반적이지만, 네이버페이 가이드 참고가 필요합니다. [공식 매뉴얼](http://developer.pay.naver.com/docs/v2/api#etc-etc_product) - **`name`** (필수) : 주문상품의 명칭 - **`count`** (필수) : 상품 주문 개수 - `sellerId` (선택) : 고객사가 하위 판매자를 식별하기 위한 고유 ID(영문 대소문자 및 숫자 허용)고객사의 업종이 통신판매중개업에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 대상 고객사만 필수 입력합니다.비대상 고객사은 입력하지 않습니다. - `payReferrer` (선택) : 네이버 플랫폼의 타 서비스와 제휴계약 후 유입분석을 진행하는 경우에만 입력 [공식 매뉴얼](http://developer.pay.naver.com/docs/v2/api#etc-etc_product_ref) - `startDate` (선택) : 시작일(YYYYMMDD) - `endDate` (선택) : 종료일(YYYYMMDD)
- `deliveryFee` - 배송비 - `number` 타입으로 넘겨야 합니다. - 예를 들어 아래와 같이 `bypass` 파라미터를 넘겨줄 수 있습니다. ```json { "bypass": { "naverpay": { "useCfmYmdt": "20230421", "productItems": [ { "categoryType": "categoryType", // 결제 상품 유형 "categoryId": "categoryId", // 결제 상품 분류 "uid": "uid", // 결제 상품 식별값 "name": "name", // 상품명 "payReferrer": "NAVER_BOOK", // 결제 상품 유입경로 "startDate": "20230421", // 시작일(YYYYMMDD) "endDate": "20230428", // 종료일(YYYYMMDD) "sellerId": "sellerId", // 하위 판매자 식별키 "count": 5 // 결제 상품 개수 } ], "deliveryFee": 3000 } } } ``` - `orderName` - 주문명 - 네이버페이 내부적으로 **`외 2개`** 의 표현이 자동생성되므로 **"`xxxx 외 2개"`** 대신 `bypass.naverpay.productItems[0].name`(첫번째 상품명)으로 설정하길 권장합니다. - `customer.name` - 고객사 고객의 이름입니다. - 결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사의 경우 필수 입력**합니다. - `customer.birth{Year, Month, Day}` - 각각 고객사 고객의 출생 년도/월/일입니다. - 결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사의 경우 세 필드 모두 필수 입력**합니다. - `easyPay.installment` - 네이버페이는 지원하지 않습니다. - `easyPay.availableCards` - 네이버페이는 지원하지 않습니다. ### 빌링키 발급 (`requestIssueBillingKey`) - `billingKeyMethod` - `EASY_PAY` 로 설정해야 합니다 - `issueId` - 고객사에서 채번하는 빌링키 발급 건 고유 ID - 네이버페이의 경우 필수 입력입니다. - 하나의 네이버 계정에 대해서 같은 issueId를 재사용할 수 없습니다. - `issueName` - 빌링키 발급 시 결제창에 표시되는 제목입니다. - 네이버페이의 경우 필수 입력입니다. - `displayAmount` - 네이버페이의 경우, 빌링키 발급창에 띄워줄 금액 정보를 파라미터로 설정할 수 있습니다. (optional) - 해당 파라미터를 입력할 경우 `currency` 필드도 함께 입력해야 합니다. - `currency` - 네이버페이의 경우, 빌링키 발급창에 띄워줄 금액 정보를 파라미터로 설정할 수 있습니다. (optional) - 해당 파라미터를 입력할 경우 `displayAmount` 필드도 함께 입력해야 합니다. ## 이외 연동 주의사항 - **에러 메시지 비 가공** - 결제창 호출(`requestPayment` 함수)후 결제창 하단의 “취소" 버튼 클릭 등으로 결제 프로세스가 중단되거나 잔액 부족, 한도 초과, 100원 미만 결제 등의 사유로 결제에 실패하면 콜백 함수(popup 방식)/`redirectUrl`(리디렉션 방식)로 전달되는 결제 결과(response 객체/쿼리 파라미터)에 실패 사유(error\_msg)가 전달됩니다. 이 에러 메시지는 사용자에게 가공 없이 그대로 노출되어야 합니다. 해당 규칙 미 준수시 네이버페이 실 검수 진행시 수정 요청을 받게 됩니다. - 예) error\_msg가 “잔액 부족"이라고 가정할때, "결제에 실패하였습니다. 실패 사유:" + "잔액 부족"과 같은 형태로 가공되면 안됨 - **100원 미만 결제 처리** - 네이버페이 - 결제형의 최소 결제 금액은 100원이기 때문에, 100원 미만 결제 요청에 대해 예외 처리가 되어있어야 합니다. - 예) 사용자에게 최소 결제 금액이 100원이라 결제를 할 수 없다는 의미를 담는 에러 메시지가 노출되어야 함 - **"API 호출 권한이 없습니다" 에러** - 네이버페이 결제형 연동은 **네이버페이 검수진행이 시작되기 전까지는 운영환경에서 결제창 호출 시 위와 같은 오류가 도출**됩니다. 해당 부분은 검수가 진행되면 해결되는 부분이기 때문에 무시해주시면 됩니다. # https://developers.portone.io/opi/ko/integration/pg/v2/nice-v2 --- title: 나이스정보통신 description: 나이스정보통신 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/nice-v2/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. V2 결제 모듈을 사용하시려면 나이스정보통신(신모듈)로 연동하셔야 합니다. ## 가능한 결제수단 - **일반 결제** - `payMethod`파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다. - 신용카드 : `CARD` - 실시간 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 상품권결제: `GIFT_CERTIFICATE` - 간편 결제 : `EASY_PAY` - **결제창 빌링키 발급** - 결제창 빌링키 발급은 간편결제(네이버페이 / 카카오페이)만 지원하므로 `billingKeyMethod` 파라미터를 `EASY_PAY`로 설정해야 합니다. - **API 수기(키인) 결제** - `method`파라미터를 `card`로 설정해야 합니다. - **API 빌링키 발급** - `method`파라미터를 `card`로 설정해야 합니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 시 생성된 채널 키값을 지정하여 나이스정보통신 채널 사용을 명시해주세요. 나이스정보통신 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. paymentId: `payment-${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "CARD", }); } ```
### 주요 파라미터 - storeId: string 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. - orderName: string 주문명으로 고객사에서 **40Byte** 이내로 자유롭게 입력합니다. **특수문자 유의사항** - 사용 가능 : **\_** - 사용 불가 : **% & | $ - + = \[ ]** - 사용 가능하나 권장하지 않음 : **( )** - channelKey: string 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키로 호출하고자 하는 채널을 지정합니다. - totalAmount: number 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. 나이스정보통신의 경우 `KRW`와 `USD`를 지원합니다. - payMethod: string 결제수단으로 결제하고자 하는 결제수단의 값을 입력해야 합니다. - taxFreeAmount?: number 면세금액으로 나이스정보통신와 상점아이디 계약시 지정금액 혹은 복합과세 방식으로 계약한 경우 면세 처리를 위해 면세금액을 반드시 입력해야 합니다. 면세금액 미 입력 시 면세금액은 0원으로 자동 처리되며, 결제 요청 금액은 모두 과세 처리 되오니 이 점 유의하시기 바랍니다. ### 유의할 파라미터 - `virtualAccount.accountExpiry` 가상계좌 발급 시 입금 기한은 필수로 입력해야 합니다. - `card.installment.monthOption.fixedMonth` 나이스정보통신은 **카드사 다이렉트 호출시 고정 할부 개월수를 필수로 입력**해야 합니다. 결제 금액이 할부 지원 금액 미만(대부분 50,000원이상 할부지원이나 카드사에 따라 상이함)인 경우 **할부 개월수를 0(일시불)으로 전달**해야 합니다. - `productType` 휴대폰 소액 결제 시 실물/컨텐츠 여부(`productType`) 파라미터는 필수 입력입니다. 입력하지 않는 경우 "나이스페이 V2 휴대폰 소액결제시 상품 유형 파라미터는 필수 입력입니다." 라는 에러 메시지가 리턴되면서 결제창 호출에 실패하오니 유의하시기 바랍니다. 또한 상점아이디 설정과 실물/컨텐츠 여부가 불일치할 경우 "CPID미설정 오류입나다."라는 메시지가 리턴되며 결제창 호출에 실패하니 유의하시기 바랍니다. - `giftCertificate.certificateType` 나이스정보통신은 컬쳐랜드만 지원하므로 상품권 결제시 항상 `CULTURELAND`로 지정해주어야 합니다. - `bypass.nice_v2.MallUserID` 나이스정보통신 상품권 결제시 고객사 구매자 ID를 의미하는 MalluserID는 필수로 입력해주어야 합니다. - `easyPay.availablePayMethods` 나이스정보통신를 통한 간편결제 결제 요청 시 다른 간편결제 수단과 다르게 네이버페이, SSG페이, 토스페이의 경우 어떤 방식으로 결제하느냐에 따라 availablePayMethods을 입력해야 합니다. - 네이버페이의 경우 카드 결제인 경우 `CARD`, 포인트 혹은 머니 결제인 경우 `CHARGE` 로 입력해야 합니다. - SSG페이의 경우 계좌 결제인 경우 `TRANSFER`로 입력해야 하며, SSG페이는 계좌 결제 시에만 다이렉트 호출이 가능합니다. 카드 혹은 머니 결제를 이용하시는 경우 `availablePayMethods`를 제외한채 호출하시길 바랍니다. - 토스페이의 경우 카드 결제인 경우 `CARD`, 머니 결제인 경우 `CHARGE`로 입력해야 합니다. ## 결제창 빌링키 발급 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 나이스정보통신 채널 사용을 명시해주세요. 나이스정보통신 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: "EASY_PAY", // 간편결제만 지원합니다. issueId: "testIssueId", issueName: "testIssueName", customer: { fullName: "포트원", phoneNumber: "010-0000-1234", email: "test@portone.io", }, easyPay: { easyPayProvider: "KAKAOPAY", }, }); } ```
### 주요 파라미터 - storeId: string **스토어 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyMethod: string **빌링키 발급수단** 나이스정보통신은 결제창 방식으로 빌링키 발급 시 간편결제(네이버페이 / 카카오페이)만을 지원하므로 `EASY_PAY`로 설정해야 합니다. - issueId: string **빌링키 발급 건 고유 ID** - 고객사에서 채번하여 사용해야 합니다. - 나이스정보통신의 경우 필수 입력해야 합니다. - 영문 대소문자와 숫자만 사용하여 40자 이내로 입력합니다. - issueName: string **빌링키 발급 시 결제창에 표시되는 제목** - 나이스정보통신의 경우 필수 입력해야 합니다. - customer?: object **고객 정보** - fullName?: string **구매자 전체 이름** - firstName?: string **구매자 이름** - lastName?: string **구매자 성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - easyPay: object - easyPayProvider: string **간편 결제 수단** - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` - availablePayMethods?: string\[] **노출을 허용할 결제 수단의 종류** 네이버페이의 경우 카드와 포인트 중 하나를 선택해야 합니다. - 네이버페이 카드: `CARD` - 네이버페이 포인트: `CHARGE` ## API 수기(키인)결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant`를 이용하여 결제 요청을 해야합니다.
```ts // ... 수기(키인) 결제 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, taxFree: 500, }, currency: "KRW", customer: { name: { full: "홍길동", }, email: "test@test.com", phoneNumber: "01012345678", }, method: { card: { credential: { number: "1111111111111111", expiryMonth: "01", expiryYear: "20", birthOrBusinessRegistrationNumber: "900101", passwordTwoDigits: "00", }, installmentMonth: 3, // 카드 할부 개월수 useFreeInterestFromMerchant: true, // 고객사 분담 무이자 설정 useCardPoint: true, // 카드 포인트 사용 설정 }, }, }, }); ```
### 주요 파라미터 - paymentId: string 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 하며, URL path에 포함돼야 합니다. - channelKey: string 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키로 호출하고자 하는 채널을 지정합니다. - orderName: string 주문명으로 고객사에서 자유롭게 입력합니다. - amount: object 결제 금액에 대한 정보를 담고있는 객체입니다. - total: number 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - taxFree?: number 면세 금액으로 나이스정보통신과 상점아이디 계약시 지정금액 혹은 복합과세 방식으로 계약한 경우 면세 처리를 위해 면세금액을 반드시 입력해야 합니다. 면세금액 미 입력 시 면세금액은 0원으로 자동 처리되며, 결제 요청 금액은 모두 과세 처리 되오니 이 점 유의하시기 바랍니다. - currency: string 결제통화로 원화 결제를 원할 시 `KRW`로 입력해야 합니다. - method: object 결제 수단에 대한 정보를 담고있는 객체입니다. - card: object - credential: object - number: string 카드번호로 10자리 이상 20자리 이하의 숫자만 입력해야 합니다. - expiryMonth: string 카드 유효기간의 월로 2자리 숫자만 입력해야 합니다. - expiryYear: string 카드 유효기간의 년도로 2자리 숫자만 입력해야 합니다. - birthOrBusinessRegistrationNumber: string 카드 소지자의 생년월일 혹은 사업자 등록번호로 6자리 숫자만 입력해야 합니다. - passwordTwoDigits: string 카드 비밀번호 앞 2자리로 2자리 숫자만 입력해야 합니다. - installmentMonth?: number 카드 할부 개월수로 0(일시불) 혹은 2\~12개월까지의 숫자만 입력해야 합니다. - useFreeInterestFromMerchant?: boolean 고객사 부담 무이자 설정으로 `true` 혹은 `false`만 입력 - useCardPoint?: boolean 카드 포인트 사용 설정으로 `true` 혹은 `false`만 입력 ### 유의할 파라미터 - `method.card.InstallmentMonth` 카드 할부 개월수로 0(일시불) 혹은 2\~12개월까지의 숫자만 입력해야 합니다. 입력하지 않은 경우 일시불로 처리됩니다. - `method.useFreeInterestFromMerchant` 고객사 부담 무이자 설정으로 `true` 혹은 `false`만 입력. - `method.card.useCardPoint` 카드 할부 개월수로 0(일시불) 혹은 2\~12개월까지의 숫자만 입력해야 합니다. 입력하지 않은 경우 일시불로 처리됩니다. ## API 빌링키 발급 및 예약/반복 결제 요청하기 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. 이후 발급된 빌링키로 예약/반복 결제를 하기위해 `POST /payments/${PAYMENT_ID_HERE}/schedule` 를 이용하여 결제를 예약합니다.
```ts 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", }, }, }, }, }); ```
```ts 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, taxFree: 500, }, currency: "KRW", useFreeInterestFromMerchant: true, // 고객사 분담 무이자 설정 InstallmentMonth: 3, // 카드 할부 개월수 useCardPoint: true, // 카드 포인트 사용 설정 }, timeToPay: "2023-01-01 00:00:00", // 결제를 시도할 시각 }, }); ```
### 빌링키 발급 주요 파라미터 - channelKey: string 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키로 호출하고자 하는 채널을 지정합니다. - method: object 결제 수단에 대한 정보를 담고있는 객체입니다. - card: object - credential: object - number: string 카드번호로 10자리 이상 20자리 이하의 숫자만 입력해야 합니다. - expiryMonth: string 카드 유효기간의 월로 2자리 숫자만 입력해야 합니다. - expiryYear: string 카드 유효기간의 년도로 2자리 숫자만 입력해야 합니다. - birthOrBusinessRegistrationNumber: string 카드 소지자의 생년월일 혹은 사업자 등록번호로 6자리 숫자만 입력해야 합니다. - passwordTwoDigits: string 카드 비밀번호 앞 2자리로 2자리 숫자만 입력해야 합니다. ### API 예약/반복 결제 주요 파라미터 - paymentId: string 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 하며, URL path에 포함돼야 합니다. - payment: object **빌링키 결제 요청 입력정보** - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** - total: number **총 결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - taxFree?: number **면세액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. 나이스정보통신와 지정금액 혹은 복합과세 방식으로 계약한 경우 면세금액을 반드시 입력해야 합니다. 카드 빌링키의 경우 면세금액 미입력 시 면세금액은 0원으로 자동 처리되며, 결제 요청 금액은 모두 과세 처리 되오니 이 점 유의하시기 바랍니다. 간편결제 빌링키의 경우 면세금액 미입력 시 오류가 발생합니다. - vatAmount?: number **부가세** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. 나이스정보통신와 지정금액 혹은 복합과세 방식으로 계약한 경우 간편결제 빌링키 이용 시 부가세를 반드시 입력해야 합니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. (신)나이스정보통신의 경우 빌링키로 결제시 `KRW`만 지원합니다. - customer: object **고객 정보** - id: string **고객 아이디** 고객사가 지정한 고객의 고유 식별자입니다. - name?: string **고객 이름** 고객의 이름을 입력합니다. 네이버페이 빌링키 결제 시 환금성 업종 가맹점은 필수 입력입니다. - email?: string **이메일** - phoneNumber?: string **전화번호** - birthYear?: string **출생 연도** 네이버페이 빌링키 결제 시 환금성 업종 가맹점은 필수 입력입니다. - birthMonth?: string **출생 월** 네이버페이 빌링키 결제 시 환금성 업종 가맹점은 필수 입력입니다. - birthDay?: string **출생 일** 네이버페이 빌링키 결제 시 환금성 업종 가맹점은 필수 입력입니다. - cashReceipt?: object **현금영수증 입력 정보** 네이버페이 빌링키 결제 시 현금영수증 대상 가맹점의 경우 필수 입력입니다. - type: string **현금영수증 발급 유형** - 소득공제용: `PERSONAL` - 지출증빙용: `CORPORATE` - 미발행: `NO_RECEIPT` - customerIdentityNumber?: string **사용자 식별 번호** - 소득공제용의 경우 휴대폰번호(10자리 혹은 11자리)를 입력합니다. - 지출증빙용의 경우 사업자번호(10자리)를 입력합니다. - timeToPay: string 결제를 시도할 시각으로 ISO 8601 형식으로 입력해야 합니다. ## 연동 유의사항 ### 나이스정보통신와 사전 계약이 필요한 경우 아래 기능을 사용하시려면 나이스정보통신에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 PG창 호출에 실패하거나, 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답을 얻게 될 수 있으니 이 점 유의하시길 바랍니다. - 모든 결제 수단(간편결제 포함) - 면세 / 복합과세 사용 - 부가세 지정 금액 방식 사용(영세율 포함) - 부분 취소 - 할부 사용 - 상점 부담 무이자 할부 사용 - 카드사 포인트 사용 - 에스크로 사용 - 해외 결제 사용 - 일부 bypass 파라미터 - UserCI - MallUserID - DirectCouponYN - PaycoClientId, PaycoAccessToken - SamPayMallType ### 일반결제 공통 유의사항 - 결제창 호출 실패 사유 알 수 없음 - 상점 아이디 설정 이슈, 파라미터 설정 오류 등으로 결제창 호출이 불가능한 경우 PG사로부터 정확한 사유를 전달 받고 있지 않아 “알 수 없는 이유로 결제가 중단되었습니다. 나이스페이로 문의(1661-0808)하세요.”라는 에러를 리턴합니다. 이 메시지를 받으신 경우 결제창 호출 시 사용한 파라미터 전문과 함께 포트원으로 문의해 주시길 바랍니다. ### 카드 일반결제 유의사항 |기능 |사용 가능 여부 | |-------------------------------------|----------------------------------------------------------| |상점 부담 무이자 할부 |가능 | |다이렉트 호출 |`단독 사용 불가능(고정 할부 개월수가 함께 전달 되어야 함)`| |다이렉트 호출 + 고정 할부 개월수 |가능 | |다이렉트 호출 + 리스트 할부 개월수 |`불가능` | |비 다이렉트 호출 + 고정 할부 개월수 |`PC만 가능` | |비 다이렉트 호출 + 리스트 할부 개월수|`PC만 가능` | - 토스뱅크 카드의 경우 카드사 다이렉트 호출 불가능합니다. - 나이스정보통신의 경우 토스뱅크 카드 다이렉트 호출이 지원되지 않습니다. - 모바일 환경에서는 다이렉트 호출시에만 할부 옵션 설정이 가능합니다. -나이스정보통신의 경우 일반 카드 결제 시(간편결제 제외) 할부 옵션(고정 할부 개월수)사용이 가능하나 **모바일 환경**에서는 **카드사 다이렉트 호출할 때만 할부 옵션 사용이 가능합니다.** 만약 모바일 환경에서 다이렉트 호출 코드 없이 할부 옵션을 전달하는 경우 무시됩니다. ### 계좌이체 일반결제 유의사항 - 계좌이체 다이렉트 호출 시 은행 코드 지정이 불가능합니다. - 나이스정보통신의 경우 계좌이체 다이렉트 호출을 하더라도 뱅크페이가 호출되오니 이 점 유의하시기 바랍니다. - 다이렉트 호출을 원하시는 경우 은행코드 대신 bypass 파라미터인 `DirectShowOpt`를 설정하여 사용하시길 바랍니다. - 계좌이체 에스크로 결제시에는 다이렉트 호출이 불가능합니다. - 나이스정보통신 정책상 에스크로를 사용한 계좌이체 결제시에는 다이렉트 호출이 불가능합니다. 아래와 같이 계좌이체 + 에스크로 + 다이렉트 호출을 위한 파라미터를 설정할 경우 "나이스페이 V2 계좌이체 에스크로 결제시 다이렉트 호출은 불가능합니다."라는 에러 메시지가 리턴되며, 결제창이 호출되지 않으니 유의하시기 바랍니다. - 계좌이체 에스크로 결제시 결제창에 올바른 이메일을 입력해야 합니다. - 존재하지 않는 이메일을 입력할 경우 **이메일 주소 오류**라는 에러 메시지와 함께 승인 실패됩니다. 또한 실제로 존재하는 이메일 도메인이더라도 나이스정보통신 정책상 유효하지 않다고 취급하는 이메일 주소((예) )를 입력한 경우 정상 승인되지만 **이후 에스크로 API를 이용하여 배송 정보 등록 시 에스크로 구매 확정 이메일이 전송되지 않습니다.** - 사파리 브라우저의 경우 미지원 대상으로 결제가 원활하지 않습니다. ### 상품권 일반결제 유의사항 - 승인 완료시 나이스정보통신로부터 승인번호(`approvalNumber`)가 전달되지 않으니 이 점 유의하시기 바랍니다. - 나이스정보통신은 상품권 결제시 별도의 승인 번호를 전달하지 않습니다. 따라서 결제 내역 조회시 승인 번호가 null로 리턴됩니다. ### 카카오페이 일반결제 유의사항 |기능 |사용 가능 여부 | |----------------------------------------------|----------------------------------------------------------------------| |상점 부담 무이자 할부 |`불가능` | |카드사 지정 다이렉트 호출 |BC, 국민, 삼성, 신한, 현대, 롯데, 씨티, NH농협 그리고 하나 카드만 가능| |카드사 지정 다이렉트 호출 + 고정 할부 개월수 |BC, 국민, 삼성, 신한, 현대, 롯데, 씨티, NH농협 그리고 하나 카드만 가능| |카드사 지정 다이렉트 호출 + 리스트 할부 개월수|`불가능` | |비 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |비 다이렉트 호출 + 리스트 할부 개월수 |`불가능` | ### 네이버페이 일반결제 유의사항 |기능 |사용 가능 여부 | |----------------------------------------------|----------------------------------------------------------------------| |상점 부담 무이자 할부 |`불가능` | |카드사 지정 다이렉트 호출 |BC, 국민, 삼성, 신한, 현대, 롯데, 씨티, NH농협 그리고 하나 카드만 가능| |카드사 지정 다이렉트 호출 + 고정 할부 개월수 |BC, 국민, 삼성, 신한, 현대, 롯데, 씨티, NH농협 그리고 하나 카드만 가능| |카드사 지정 다이렉트 호출 + 리스트 할부 개월수|가능(단, `일시불이 항상 포함` 됨) | |비 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |비 다이렉트 호출 + 리스트 할부 개월수 |가능(단, `일시불이 항상 포함` 됨) | - 네이버페이 머니와 포인트 복합 결제 시, 포인트가 먼저 사용 됩니다. - 네이버페이 포인트 결제 시 네이버페이 머니, 포인트 또는 복합(머니와 포인트 함께 사용) 방식으로 결제가 가능하며, 만약 복합 방식으로 결제할 경우 포인트 금액이 먼저 차감됩니다. - 네이버페이 포인트 결제 시 현금영수증 정보를 필수 입력해야합니다. - 네이버페이 포인트 결제 시 현금영수증 발급이 가능하며 **현금영수증 정보(`easyPay.cashReceiptType`, `easyPay.customerIdentifier`)를 필수로 입력**해야 합니다. 만약 입력하지 않을 경우 "나이스페이 V2 네이버페이 포인트 결제시 현금영수증 발급 유형은 필수 입력입니다."라는 에러 메시지가 리턴되며, 결제창이 호출되지 않으니 유의하시기 바랍니다. 단, **네이버페이 머니로 결제할 경우에만 현금영수증이 발급**됩니다. 결제 금액 모두 네이버페이 포인트로 결제하는 경우에는 결제창 호출 시 현금영수증 정보를 전달하더라도 발급되지 않습니다. ### 페이코 일반결제 유의사항 |기능 |사용 가능 여부| |----------------------------------------------|--------------| |상점 부담 무이자 할부 |가능 | |카드사 지정 다이렉트 호출 |가능 | |카드사 지정 다이렉트 호출 + 고정 할부 개월수 |가능 | |카드사 지정 다이렉트 호출 + 리스트 할부 개월수|가능 | |비 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |비 다이렉트 호출 + 리스트 할부 개월수 |가능 | ### 삼성페이/11Pay(구.SKPay)/SSGPAY 일반결제 유의사항 |기능 |사용 가능 여부| |----------------------------------------------|--------------| |상점 부담 무이자 할부 |가능 | |카드사 지정 다이렉트 호출 |`불가능` | |카드사 지정 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |카드사 지정 다이렉트 호출 + 리스트 할부 개월수|`불가능` | |비 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |비 다이렉트 호출 + 리스트 할부 개월수 |`불가능` | ### 애플페이/LPAY 일반결제 유의사항 |기능 |사용 가능 여부| |----------------------------------------------|--------------| |상점 부담 무이자 할부 |`불가능` | |카드사 지정 다이렉트 호출 |`불가능` | |카드사 지정 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |카드사 지정 다이렉트 호출 + 리스트 할부 개월수|`불가능` | |비 다이렉트 호출 + 고정 할부 개월수 |`불가능` | |비 다이렉트 호출 + 리스트 할부 개월수 |`불가능` | ### SSG페이 계좌 결제 유의사항 - SSG페이 계좌 결제는 현금성 결제로 현금영수증 발급이 가능하므로 **현금영수증 정보(`easyPay.cashReceiptType`, `easyPay.customerIdentifier`)는 필수 입력**입니다. 만약 입력하지 않을 경우 "나이스페이 V2 SSGPAY 은행 계좌 결제시 현금영수증 발급 유형은 필수 입력입니다."라는 에러 메시지가 뜨면서 결제창이 호출되지 않으니 유의하시기 바랍니다. - SSG페이 계좌 결제 시 주문 번호(`paymentId`)에 특수문자 사용이 불가능합니다. - SSGPAY 계좌 결제 시 현금영수증 발급 정보를 확인할 수 없습니다. - SSGPAY 은행 계좌 결제 시 현금영수증 발급 정보를 입력하여 정상적으로 발급되더라도 승인 완료(status: paid)시 나이스정보통신에서 현금영수증 발급 정보를 전달하지 않아 포트원 API로 결제/현금영수증 발급 내역 조회 또는 포트원 콘솔에서 현금영수증 내역을 확인할 수 없습니다. 단, 나이스정보통신 어드민에서는 확인이 가능하오니 확인이 필요한 경우 나이스정보통신 어드민에서 확인하시길 바랍니다.
파라미터 예시 ```ts PortOne.requestPayment({ // ...중략 payMethod: "EASY_PAY", easyPay: { easyPayProvider: "SSGPAY", availablePayMethods: "TRANSGER", cashReceiptType: "PERSONAL", customerIdentifier: "01000000000", }, }); ```
### 일반결제 현금영수증 유의사항 - SDK 파라미터로 현금영수증 식별 번호를 전달하는 경우 휴대폰 번호만 사용 가능합니다. - 계좌이체 다이렉트 호출, 네이버페이 포인트 결제, SSGPAY 계좌 결제 시 현금영수증 정보는 필수 입력입니다. 단, 휴대폰 번호가 아닌 주민등록번호를 전달한 경우 현금영수증이 정상적으로 발급되지 않으니 유의하시기 바랍니다. - 가상계좌 발급 혹은 일반적인 계좌이체(다이렉트 호출하지 않은 경우) 결제 시 현금영수증 파라미터를 입력에 유의하시기 바랍니다. - 결제창을 통한 가상계좌 발급 또는 일반적인 계좌이체(비 다이렉트 호출) 결제 시에는 현금영수증 정보를 파라미터로 전달할 수 없기(전달하더라도 결제창에 자동 입력되지 않음)때문에 구매자가 결제창에 직접 현금영수증 정보를 입력해야 합니다. 만약 비 다이렉트 호출 시 현금영수증 정보를 파라미터로 넘기는 경우 **결제 창 호출에 실패하였습니다. 나이스페이 V2 계좌이체 결제시 현금영수증 정보는 다이렉트 호출시에만 입력 가능합니다.** 라는 에러메세지와 함께 결제창이 호출되지 않습니다. ### API 지원 기능 나이스정보통신은 API를 통해 아래 기능들을 지원합니다. - 카드 빌링키 발급 - 카드 및 간편결제 빌링키 결제 - 수기(키인) 결제 - 예약 결제 - 결제 취소(가상계좌 환불 포함) - 에스크로 배송 정보 등록, 조회(수정 불가능) - 가상계좌 발급, 말소 - 포트원 외부 결제 건 현금영수증 발급, 조회, 취소 ### 가상계좌 발급 API 유의사항 - 고정식 가상계좌 지원합니다. - 나이스정보통신의 경우 API를 통한 고정식 가상계좌 사용을 지원합니다. 고정식 가상계좌를 사용하기 위해서는 `virtualAccount.option.type`를 `FIXED`로 전달해야 합니다. 단, 고정식 가상계좌 및 과오납체크를 사용하도록 나이스정보통신와 사전 협의가 필요합니다. ### 에스크로 API 유의사항 - 배송 정보 등록시 유의할 파라미터 - 배송자 이름인 `sender.name` 파라미터가 필수 입니다. - 배송지 주소인 `receiver.address` 파라미터가 필수입니다. - 이메일 전송 여부인 `sendEmail` 파라미터가 필수입니다. - 나이스정보통신의 경우 다른 PG에서는 지원하지 않는 `sendEmail` 파라미터를 지원합니다. - 에스크로 구매 확정시 결제 창에 입력했던 이메일로 해당 사실을 전송할지 여부. (기본값: true | boolean type) - 배송 정보 수정 불가합니다. - 나이스정보통신은 API로 에스크로 배송 정보 등록은 가능하지만 **수정은 불가능**합니다. ### 현금영수증 API 유의사항 - 결제창에서 발급 받지 못한 현금영수증은 API로 발급 불가능합니다. - 나이스정보통신의 경우 현금성 결제(가상계좌, 계좌이체, 네이버페이 포인트 결제 등)시 승인 단계에서 현금영수증을 발급 요청할 수 있습니다. 이때 결제 승인 단계에서 현금영수증을 발급 요청하지 못한 경우, 현금영수증 발급 API(`POST /cash-receipts`)를 사용한다고 하더라도 발급이 되지 않으니 참고 부탁드립니다. - API로 현금영수증 발급 시, 현금영수증 카드 사용이 불가능합니다. - API로 현금영수증 발급(`POST /cash-receipts`)시 발급 받을 현금영수증 정보(현금영수증 발급 유형, 현금영수증 발행 식별 정보)를 전달해야 합니다. 단, 나이스정보통신의 경우 **발행 식별 정보 중 현금영수증 카드 번호는 사용이 불가능**하오니 참고 부탁드립니다. # https://developers.portone.io/opi/ko/integration/pg/v2/payletter-global --- title: 페이레터 해외결제 description: 페이레터 해외결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 페이레터 해외결제 채널 설정 내용을 참고하여 채널 설정을 진행합니다. ## 가능한 결제 수단 - **결제창 일반 결제** 페이레터의 경우, `payMethod` 파라미터를 지원하고 있지 않아, 계약된 모든 결제 수단이 페이레터 결제창에 노출됩니다. 특정 결제 수단만 노출하고 싶으신 경우, 아래에 후술될 `bypass.payletter_global.pginfo` 파라미터를 사용하시면 됩니다. - **일반 결제** - 특정 결제 수단만 결제창에 표기하고 싶으신 경우, `bypass.payletter_global.pginfo` 파라미터를 결제수단에 따라 아래와 같이 설정하시면 됩니다. - 해외카드 비인증 : `PLCreditCard` - 해외카드 인증(3DS) : `PLCreditCardMpi` - 유니온페이 : `PLUnionPay_HC` - 위챗페이 PC결제 : `WeChatPayQRCodePayment` - 위챗페이 모바일결제 : `WeChatPayH5Payment` - 알리페이 : `ICBAlipay` - 알리페이 HK (알리페이+) : `AlipayPlusAlipayHK` - BPI (알리페이+) : `AlipayPlusBPI` - Dana (알리페이+) : `AlipayPlusDana` - GCash (알리페이+) : `AlipayPlusGcash` - Rabbit LINE Pay (알리페이+) : `AlipayPlusRabbitLinePay` - Touch 'n Go (알리페이+) : `AlipayPlusTNG` - TrueMoney (알리페이+) : `AlipayPlusTrueMoney` ## SDK 결제 요청하기 결제 요청 시에는 [requestPayment](https://developers.portone.io/sdk/ko/v2-sdk/payment-request?v=v2) 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 페이레터 해외결제 채널 사용을 명시해주세요. 페이레터 연동만을 위한 파라미터는 [requestPayment 요청 형식](https://developers.portone.io/sdk/ko/v2-sdk/payment-request?v=v2#bypass-oneof-object)의 `bypass.payletter_global` 항목을 참조해 주세요. ## 가능한 빌링키 발급 및 결제 수단 - **빌링키 발급 및 결제** 페이레터의 경우, `billingKeyAndPayMethod` 파라미터를 지원하고 있지 않아, 계약된 모든 빌링키 발급 및 결제 수단이 페이레터 결제창에 노출됩니다. 특정 결제 수단만 노출하고 싶으신 경우, 아래에 후술될 `bypass.payletter_global.pginfo` 파라미터를 사용하시면 됩니다. - **가능한 빌링키 발급 및 결제 수단** - 특정 빌링키 발급 및 결제 수단만 결제창에 표기하고 싶으신 경우, `bypass.payletter_global.pginfo` 파라미터를 결제 수단에 따라 아래와 같이 설정하시면 됩니다. - 빌링키 발급 및 결제의 경우, 위챗, 알리페이 등의 간편결제 수단으로 발급하는 것을 지원하지 않고 있어 아래의 결제 수단으로만 발급이 가능합니다. - 해외카드 비인증 : `PLCreditCard` - 해외카드 인증(3DS) : `PLCreditCardMpi` - 유니온페이 : `PLUnionPay_HC` ## SDK 빌링키 발급 및 결제 요청하기 빌링키 발급 및 결제 요청 시에는 [requestIssueBillingKeyAndPay](https://developers.portone.io/sdk/ko/v2-sdk/billing-key-and-pay-request?v=v2) 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 페이레터 해외결제 채널 사용을 명시해주세요. ## 결제수단별 승인 가능 통화 - 카드: `KRW`, `USD`, `JPY` - Alipay: `USD`, `CNY` - Alipay+: `USD` - WeChatPay: `KRW`, `USD`, `CNY` ## 유의사항 - `paymentId` 에는 영문, 숫자만으로 이루어진 문자열만 입력할 수 있습니다. - 페이레터의 경우 구매자 이메일을 필수로 받고있어,`customer.email`을 필수로 입력하셔야 합니다. - WeChatPay, Alipay, Alipay+ 결제 시 `bypass.payletter_global.servicename` 파라미터를 필수로 입력하셔야 합니다. - 페이레터의 경우 결제창을 닫은 이후에 결제가 성공 처리될 수 있습니다. 웹훅을 연동하여 결제 실패 상태에서 결제 성공 상태로 바뀌는 경우를 처리해야 합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/paymentwall --- title: 페이먼트월 description: 페이먼트월 결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 가능한 결제 수단 페이먼트월의 경우, `payMethod` 파라미터를 지원하고 있지 않아, 국가IP에 맞는 결제수단이 기본으로 노출됩니다. 특정 결제수단만 노출하고 싶으신 경우, 아래에 후술될 `bypass.paymentwall.ps` 파라미터를 사용하시면 됩니다. - 페이먼트월 결제수단 코드는 포트원 코드와 상이하므로, [PAYMENTWALL Docs](https://docs.paymentwall.com/reference/payment-system-shortcodes)에서 `Payment System short code`를 확인 후 입력해야 합니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 페이먼트월 채널 사용을 명시해주세요. 페이먼트월 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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: "PortOne Purchase", totalAmount: 1000, currency: "KRW", customer: { customerId: "customer-1234", // 고객사가 구매자에게 부여한 고유 ID email: "test@portone.io", }, }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - paymentId: string **고객사 주문 고유 번호** 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - totalAmount: number **결제 금액** 결제 금액(실제 결제 금액 X 10^ 해당 currency의 scale factor, 예: $1.50 -> 150) - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - locale?: Locale **결제창 언어** - `KO_KR`: 한국어 - `EN_US`: 영어 - `JA_JP`: 일본어 - `ZH_CN`: 중국어 (중국 본토) - `ZH_TW`: 중국어 (대만) - `TH_TH`: 타이어 - `RU_RU`: 러시아어 - `VI_VN`: 베트남어 - `FR_FR`: 프랑스어 - `NL_NL`: 네덜란드어 - `ES_ES`: 에스파냐어 - `PT_PT`: 포르투갈어 - `DE_DE`: 독일어 - `IT_IT`: 이탈리아어 - `PL_PL`: 폴란드어 - `TR_TR`: 터키어 - `SV_SE`: 스웨덴어 - `FI_FI`: 핀란드어 - `UK_UA`: 우크라이나어 - `EL_GR`: 그리스어 - `TL_PH`: 타갈로그어 - `HI_IN`: 힌디어 - `HR_HR`: 크로아티아어 - `LT_LT`: 리투아니아어 - `SL_SI`: 슬로베니아어 - `SR_RS`: 세르비아어 - `BG_BG`: 불가리아어 - `PT_BR`: 포르투갈어 (브라질) - customer: object **고객 정보** 페이먼트월의 경우 구매자 고유 ID와 이메일은 필수 입력 항목입니다. - customerId: string **구매자 고유 ID** 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. - email: string **구매자 이메일** - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - paymentwall?: object **페이먼트월 특수 파라미터** - widget?: string **위젯 코드** `pw_1`과 `t3_1`만 입력 가능하며, 미설정시 기본(`pw_1`) 결제창이 활성화됩니다. - ps?: string **결제수단 단독 노출** 페이먼트월 결제수단 코드는 포트원 코드와 상이하므로, [PAYMENTWALL Docs](https://docs.paymentwall.com/reference/payment-system-shortcodes)에서 `Payment System short code`를 확인 후 입력해야 합니다. - country\_code?: string **국가 코드** 지정된 국가에서 지원되는 결제수단이 결제창에 노출됩니다. [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)를 참고하여 해당하는 국가코드를 입력해야 합니다. ## 유의사항 - 페이먼트월 프로젝트는 반드시 페이먼트월에서 제공하는 포트원 전용 링크를 통해 생성해야 합니다. 정상적으로 생성된 프로젝트는 프로젝트명 뒤에 `[import]`가 표시됩니다. - 페이먼트월을 통해 결제하는 경우 [페이먼트월 배송 정보 등록 API](https://developers.portone.io/api/rest-v2/pgSpecific#post%20%2Fpaymentwall%2Fdelivery%2Fconfirm)를 반드시 연동해야 합니다. 등록된 배송 정보는 차지백 발생 시 상품 배송 완료를 증빙하는 자료로 활용됩니다. - 요청 통화와 승인 통화(프로세싱 통화)가 다른 경우 부분 취소는 지원되지 않으며, 전체 취소만 가능합니다. - 국내 가상계좌 결제는 지원되지 않습니다. # https://developers.portone.io/opi/ko/integration/pg/v2/paypal-v2 --- title: 페이팔 description: 페이팔 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/spb/readme --- ## 채널 설정하기 [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널을 설정해야 합니다. 포트원 V2 결제 모듈을 사용하시려면 페이팔(SPB/RT)로 연동해야 합니다.
포트원 V2에서는 페이팔 일반결제의 경우 SPB(Smart Payment Button), 정기결제의 경우 RT(Reference Transaction) 방식만 지원합니다.
페이팔은 카드나 계좌 등의 결제수단을 지정하여 결제를 호출할 수 없습니다. (단, 페이팔 계정내에서 사용자가 등록한 결제수단에 따라 카드 혹은 계좌 등을 선택할 수 있습니다.)
페이팔의 경우 다른 결제대행사(PG)의 결제창 호출 방식과 달리 **버튼을 렌더링**한 후 결제를 진행해야 합니다.
## 주요 파라미터 - 일반결제 시 `uiType`파라미터를 `PAYPAL_SPB`, 빌링키 발급 시 `PAYPAL_RT`로 설정해야 합니다. 페이팔의 경우 `uiType` 파라미터를 필수로 입력해야 합니다. - 페이팔의 경우 `payMethod`, `windowType` 파라미터를 생략한 채 호출해도 됩니다. - 단, `windowType` 파라미터 지정 시 PC 및 모바일 환경 모두 `UI`로 지정하셔야 하며, 이 외의 값을 입력하는 경우 에러가 리턴됩니다. ## 일반 결제/빌링키 발급 공통 준비 사항 페이팔의 경우 고객사의 화면에 페이팔 결제/빌링키 발급 버튼을 렌더링 한 후, 페이팔의 버튼을 클릭하여 페이팔의 결제/빌링키 발급 창을 호출하는 방식입니다. 페이팔의 버튼을 렌더링 하기 위해, 버튼을 렌더링 할 곳에 클래스명이 `portone-ui-container`인 DOM element를 선언하셔야 합니다. ```html
``` ## 일반 결제(`loadPaymentUI`) 호출하기 일반 결제의 경우, 고객사의 결제 화면에 페이팔 결제 버튼을 렌더링 하기위해 `loadPaymentUI` 함수를 사용해야 합니다. 결제 성공 시의 동작을 `onPaymentSuccess` 콜백 함수에, 결제 실패 시의 동작을 `onPaymentFail`에 작성해야 합니다. ```ts const requestData = { uiType: "PAYPAL_SPB", storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceecl", channelKey: "channel-key-893597d6-e62d-410f-83f9-119f530b4b11", paymentId: `payment-${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", }; const response = await PortOne.loadPaymentUI(requestData, { onPaymentSuccess: (response) => { setResult(response); }, onPaymentFail: (error) => { alert(error); }, }); ``` (관련 이미지 첨부) 따라서 다른 PG사와 결제 플로우가 상이하기 때문에 고객사는 **결제(체크아웃) 페이지가 렌더링 되는 시점에** `PortOne.requestPayment` 함수 대신 **`PortOne.loadPaymentUI`함수를 별도로 호출해 페이팔 결제 버튼을 렌더링**한 후 사용해야 합니다. (이미지 첨부: 페이팔 일반결제 연동 플로우) ### 결제 요청 데이터 업데이트 페이팔의 결제 플로우에 의하면 고객사의 결제 페이지가 렌더링될 때 결제 요청 데이터가 결정되어야 하고, 결제 페이지 내에서 구매자의 정보(ex. 구매자 이름, 구매자 주소 등)가 새로 입력되거나 혹은 변경되거나, 쿠폰 및 포인트 사용으로 인한 결제 금액에 대해 변경이 발생한 경우 최종적으로 결정된 구매 정보를 기준으로 페이팔 결제버튼을 새로 렌더링 시킨 후 사용하도록 권장하고 있습니다. 하지만 이런 방식으로 사용하는 것은 번거롭기에 포트원에서는 고객사의 편의를 위해 최초 페이팔 결제 버튼을 렌더링 시킨 후 주문 정보가 변경되었을 때, 추가로 결제 버튼 렌더링하지 않고 **결제 요청 데이터를 업데이트**할 수 있는 `PortOne.updateLoadPaymentUIRequest` 함수를 제공하고 있습니다. 구매 정보 변경이 있을 경우 **`PortOne.updateLoadPaymentUIRequest`함수를 호출하여 결제 데이터를 업데이트**하시면 구매자가 페이팔 결제 버튼을 누를 때 최종적으로 변경된 결제 요청 데이터로 페이팔 결제창이 호출됩니다. ```ts title="SDK 일반 결제 요청" import * as PortOne from "@portone/browser-sdk/v2"; const requestData = { uiType: "PAYPAL_SPB", orderName: "포트원 페이팔 테스트 결제", // ...중략 }; function loadPaymentUI() { // loadPaymentUI의 파라미터로 결제 요청 데이터, 결제 프로세스 성공, 실패 시 호출될 "콜백 함수"를 전달해야 합니다. PortOne.loadPaymentUI({ requestData, onPaymentSuccess: (response) => { // 성공 시 호출되는 콜백 함수 내용 }, onPaymentFail: (error) => { // 실패 시 호출되는 콜백함수 내용 }, }); } function updateLoadPaymentUIRequest() { // 결제 요청 데이터가 변경되면 고객사에서 선언한 updateLoadPaymentUIRequest 함수가 호출됩니다. // PortOne.updateLoadPaymentUIRequest가 최종적으로 변경 된 결제 요청 데이터를 전달합니다. PortOne.updateLoadPaymentUIRequest(requestData); } ``` ## 빌링키 발급(`loadIssueBillingKeyUI`) 호출하기 빌링키 발급의 경우, 고객사의 빌링키 발급 화면에 페이팔 빌링키 발급 버튼을 렌더링 하기위해 `loadIssueBillingKeyUI` 함수를 사용해야 합니다. 발급 성공 시의 동작을 `onIssueBillingKeySuccess` 콜백 함수에, 발급 실패 시의 동작을 `onIssueBillingKeyFail`에 작성하셔야 합니다. ```ts const requestData = { uiType: "PAYPAL_RT", storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", channelKey: "channel-key-893597d6-e62d-410f-83f9-119f530b4b11", issueId: `issue-id-${crypto.randomUUID()}`, }; const response = await PortOne.loadIssueBillingKeyUI(requestData, { onIssueBillingKeySuccess: (response) => { setResult(response); }, onIssueBillingKeyFail: (error) => { alert(error); }, }); ``` (관련 이미지 첨부) 따라서 다른 PG사와 결제 플로우가 상이하기 때문에 고객사는 **결제(체크아웃) 페이지가 렌더링 되는 시점에** `PortOne.requestIssueBillingKey` 함수 대신 **`PortOne.loadIssueBillingKeyUI`함수를 별도로 호출해 페이팔 빌링키 발급 버튼을 렌더링**한 후 사용해야 합니다. ### 빌링키 발급 요청 데이터 업데이트 페이팔의 결제 플로우에 의하면 고객사의 빌링키 발급 페이지가 렌더링될 때 빌링키 발급 요청 데이터가 결정되어야 하고, 해당 페이지 내에서 구매자의 정보(ex. 구매자 이름, 구매자 주소 등)가 새로 입력되거나 혹은 변경이 발생한 경우 최종적으로 결정된 빌링키 발급 정보를 기준으로 페이팔 빌링키 발급 버튼을 새로 렌더링 시킨 후 사용하도록 권장하고 있습니다. 하지만 이런 방식으로 사용하는 것은 번거롭기에 포트원에서는 고객사의 편의를 위해 최초 페이팔 빌링키 발급 버튼을 렌더링 시킨 후 주문 정보가 변경되었을 때, 추가로 빌링키 발급 버튼을 렌더링하지 않고 **빌링키 발급 요청 데이터를 업데이트**할 수 있는 `PortOne.updateLoadIssueBillingKeyUIRequest` 함수를 제공하고 있습니다. 빌링키 발급 정보 변경이 있을 경우 **`PortOne.updateLoadIssueBillingKeyUIRequest`함수를 호출하여 데이터를 업데이트**하시면 구매자가 페이팔 빌링키 발급 버튼을 누를 때 최종적으로 변경된 데이터로 페이팔 빌링키 발급창이 호출됩니다. (이미지 첨부: 페이팔 정기결제 빌링키 발급 연동 플로우) ```ts title="SDK 빌링키 발급 요청" import * as PortOne from "@portone/browser-sdk/v2"; const requestData = { uiType: "PAYPAL_RT", // ...중략 }; function loadIssueBillingKeyUI() { // loadIssueBillingKeyUI 파라미터로 결제 요청 데이터, 결제 프로세스 성공, 실패 시 호출될 "콜백 함수"를 전달해야 합니다. PortOne.loadIssueBillingKeyUI({ requestData, onIssueBillingKeySuccess: (response) => { // 성공 시 호출되는 콜백 함수 내용 }, onIssueBillingKeyFail: (error) => { // 실패 시 호출되는 콜백함수 내용 }, }); } function updateLoadIssueBillingKeyUIRequest() { // 결제 요청 데이터가 변경되면 고객사에서 선언한 updateLoadIssueBillingKeyUIRequest 함수가 호출됩니다. // PortOne.updateLoadIssueBillingKeyUIRequest가 최종적으로 변경 된 결제 요청 데이터를 전달합니다. PortOne.updateLoadIssueBillingKeyUIRequest(requestData); } ``` ## 비동기 프로세스 처리하기 결제 승인 및 취소 시 비동기 프로세스가 존재하는 경우 결제 상태를 최종적으로 반영하기 위해서 반드시 **웹훅 연동을 해야**합니다. \[[→ 웹훅 연동하기 바로가기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2)] ### 비동기 상태 1. 결제 요청 후 대기 상태 페이팔 결제 건은 결제 승인 요청 시 바로 승인 되지 않고 일정 시간이후 처리되는 "승인 대기(pending)" 상태가 존재합니다. 때문에 트랜잭션 종료 시 콜백 함수로 전달되는 결제 아이디(paymentId)로 결제 내역을 조회하여 status 응답에 따라 후처리 로직을 구현해야 합니다. \[[→ 결제내역 단건조회 API 바로가기](https://developers.portone.io/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D)] 2. 결제 취소 후 대기 상태 결제 취소 시 취소 승인이 바로 되지 않고 일정 시간이후 취소 승인이 처리되는 경우가 존재합니다. 결제 취소 API를 통해 결제를 취소한 경우 API 응답의 `status` 값을 기준으로 취소 승인 여부를 판단해야 합니다. 취소 승인 대기인 경우 `status` 값이 `REQUESTED`로 응답되며 이후 취소 승인이 완료되면 웹훅이 발송됩니다. 콘솔을 통해 결제를 취소한 경우 취소 승인이 바로 되지 않으면 결제 상태는 변경되지 않고, 콘솔 내 \[결제내역 상세 > 취소요청내역] 탭에서 취소 요청 내역을 확인할 수 있습니다. 이후 취소 승인이 되면, 결제 취소로 상태가 변경됩니다.
콘솔 표시 예시 (이미지 첨부: 결제 취소 후 취소 승인 대기상태) (이미지 첨부: 결제 취소 후 취소 승인 대기상태일 때 결제내역 상세)
## 고위험 산업(STC) 안내 페이팔은 판매자 보호 정책을 통해 고객사 거래에서 이상거래나 사기 등 위험 발생 시, 판매자 보호 정책을 통해 고객사의 손해를 보존하는 판매자 보호 프로그램을 가지고 있습니다. 이 판매자 보호 정책을 적용하기 위해서는 페이팔 측에서 제공하는 STC 기능을 사용해야 합니다.
**고위험 산업군(게임과 같은 디지털 상품 또는 중고거래 등)의 경우 페이팔에서 STC API를 통해 판매자 보호 정책을 적용하도록 강력하게 요구하고 있습니다.** **또한, 고위험 산업군이 아닌 경우에도 STC API를 연동하는 것을 권장하고 있습니다.** 판매자 보호 정책에 관한 자세한 내용 및 협의가 필요한 경우 페이팔에 직접 문의해 주세요.
---
고위험 산업에 해당하는 산업군들은 다음과 같습니다. 1. 이벤트/티켓 판매 산업 2. 연료 산업 3. 게임/디지털 상품 산업 4. 마켓플레이스 사업 5. 온라인 여행 산업(렌터카, 숙박, 여행 패키지, 교통) 6. P2P 산업 7. 소매, 식품 산업 - **소매, 식품 산업의 경우 다음과 같은 경우에만 STC 연동이 필요합니다.** - 모바일 기기를 통해 매장 내 구매가 가능한 산업 - **다음 산업의 경우에는 STC 연동이 필요하지 않습니다.** - 타사 배송업체를 통해 주소로 실물 상품을 배송하는 산업 - 자체 배송 트럭을 통해 주소로 실물 상품을 배송하는 산업 - 소비자가 수령할 수 있도록 자체 매장으로 실물 상품을 배송하는 산업 8. 택시, 공유 이동수단 사업 9. 통신사 10. 결제 시스템 보안 서비스 산업
### 결제 처리 STC 기능을 사용하기 위해 다음 정보를 확인해 주세요. 1. 페이팔 Business 계정 가입 시 선택한 산업 종류(Industry)를 확인해야 합니다. 2. 계정의 산업 종류를 확인한 후, 해당 산업에 맞는 파라미터를 아래와 같은 형식으로 loadUI 호출 시 bypass.paypal\_v2 객체에 추가하여 호출해야 합니다.
결제 요청시 STC 적용하기 ```ts // 해당 파라미터들은 예시로 산업군에 따라 추가 또는 제외 가능한 파라미터들이 있습니다. _({ additional_data: [ // 상점의 구매자 계정 기준으로 정보 입력 { key: "sender_account_id", // 구매자 계정 ID value: "A12345N343", }, { key: "sender_first_name", // 구매자 이름 value: "John", }, { key: "sender_last_name", // 구매자 성 value: "Doe", }, { key: "sender_email", // 구매자 이메일 주소 value: "example@example.com", }, { key: "sender_phone", // 구매자 휴대전화 번호 value: "(02)16705176", }, { key: "sender_country_code", // 구매자 국가 코드 value: "KR", // ISO 3166-2 alpha-2 코드 }, { key: "sender_create_date", // 구매자 계정 생성 시각 value: "2023-10-10T23:59:59+09:00", // RFC 3339 형식 }, ], }); ```
### 산업군 별 파라미터 페이팔에서 지원하는 판매자 보호 정책(Seller Protection Policy) 적용을 위해서, 결제 시에 산업군 별 파라미터를 추가하여 전달해야 합니다. 해당 문서의 파라미터들은 모두 optional이지만, 고위험 거래 처리를 위해 하나 이상의 필드를 추가하여 전달해야 합니다. 페이팔에서는 위험도 분석을 위해, 고객사가 제공할 수 있는 최대한의 데이터를 전달하는 것을 권장하고 있습니다. 모든 파라미터는 String 타입으로 전달해야 합니다. 또한 Format이 작성되어 있지 않은 필드들은 자유 형식으로 작성하여 전달해야 합니다.
이벤트/티켓 판매 산업 |Field Name |Description |Format | |---------------------|-------------------------------------------------------|-------------------------------------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호 |E.123 - Telephone Number (national notation) | |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |dg\_delivery\_method |발신 방법 |(`email`, `phone`, `venue_pickup`, `kiosk_pickup`) 중의 하나로 전송해야함| |cd\_string\_one |여분 필드 1(행사일 등의 정보 입력, 중요도 낮음) | | |cd\_string\_two |여분 필드 2 (행사 카테고리 등의 정보 입력, 중요도 낮음)| | |cd\_int\_one |티켓의 수(중요도 낮음) | |
연료 산업 |Field Name |Description |Format | |---------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format |
게임/디지털 상품 산업 |Field Name |Description |Format | |---------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format |
마켓플레이스 산업 |Field Name |Description |Format | |--------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------| |sender\_account\_id |구매자/발신자 계정의 id | | |sender\_first\_name |구매자/발신자의 이름 | | |sender\_last\_name |구매자/발신자의 성 | | |sender\_email |구매자/발신자의 이메일 |E.123 - Email Address | |sender\_phone |구매자/발신자의 휴대전화 번호 |E.123 - Telephone Number (national notation)| |sender\_address\_zip |(미국 머천트 한정) 구매자/발신자가 고객사 계정에 등록한 우편번호 | | |sender\_country\_code |구매자/발신자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자/발신자의 계정 생성일 |ISO 8601 date format | |sender\_signup\_ip |구매자/발신자의 회원 가입 시점의 IP 주소 |IP(IPv4 / IPv6) | |sender\_popularity\_score |구매자/발신자의 신용도 점수 |(high, medium, low) 중의 하나 | |receiver\_account\_id |판매자/수신자 계정의 id | | |receiver\_create\_date |판매자/수신자의 계정 생성일 |ISO 8601 date format | |receiver\_email |판매자/수신자의 이메일 |E.123 - Email Address | |receiver\_address\_country\_code|판매자/수신자의 국가 코드 |ISO Alpha-2 Country Code | |business\_name |판매자/수신자가 계정에 등록한 사업용 이름 | | |recipient\_popularity\_score |판매자/수신자의 신용도 점수 |(high, medium, low) 중의 하나 | |first\_interaction\_date |발신자/수신자의 첫 번째 상호작용 날짜. '상호작용'의 정의는 고객사에서 정의합니다. ex)발신자와 수신자 간의 첫 번째 거래 시도, 발신자와 수신자 간의 친구 추가 날짜 등|ISO 8601 date format | |txn\_count\_total |발신자/구매자가 현재까지 고객사에서 진행한 총 거래 횟수(PayPal 또는 기타 결제수단을 통해) |Number | |transaction\_is\_tangible |판매자/수신자의 거래가 유형 거래인지, 무형 거래인지를 나타내는 필드 |유형 거래인 경우 1, 무형 거래인 경우 0 |
온라인 여행 산업(렌터카, 숙박, 여행 패키지, 교통) |Field Name |Description |Format | |-------------------------|---------------------------------------------------------------------------------------------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호 |E.123 - Telephone Number (national notation)| |sender\_country\_code |구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |ota\_type |여행 산업 종류(숙박인 경우 hotel 등, 교통인 경우 train 등의 종류 입력) | | |ota\_service\_start\_date|서비스 제공 시작일 |ISO 8601 date format | |ota\_service\_end\_date |서비스 제공 종료일 |ISO 8601 date format | |ota\_service\_guest\_t\_f|게스트(서비스를 받는 사람) 변경 가능 여부, 사기범들이 변경 가능 서비스에 비용을 지불하는 경향이 있습니다.|변경 가능시 1, 아닐시 0 | |ota\_start\_country |서비스를 시작한 국가 (ex: 차 렌트, 숙박이 예약된 국가) |ISO Alpha-2 Country Code | |ota\_start\_city |서비스를 시작한 도시 | | |ota\_start\_zip\_code |서비스 시작 장소의 우편 번호 | | |cd\_string\_one |여분 필드 1, 여행 산업 - 교통에 해당하는 머천트만 사용, 티켓 종류 입력 |ISO 8601 date format |
P2P 산업 |Field Name |Description |Format | |--------------------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code |구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |receiver\_account\_id |수신자 계정의 id | | |receiver\_create\_date |수신자의 계정 생성일 |ISO 8601 date format | |receiver\_email |수신자의 이메일 |E.123 - Email Address | |receiver\_address\_country\_code|수신자의 국가 코드 |ISO Alpha-2 Country Code |
소매, 식품 산업 |Field Name |Description |Format | |---------------------|--------------------------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호 |E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |dg\_delivery\_method |발신 방법 |(`email`, `phone`) 중의 하나로 전송해야함 | |highrisk\_txn\_flag |고객사에서 고위험으로 분류한 상품 여부|위험 상품인 경우 1, 아닐 시 0 |
택시, 공유 이동수단 산업 |Field Name |Description |Format | |---------------------|----------------------------------------------------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호 |E.123 - Telephone Number (national notation)| |sender\_address\_zip |(미국 머천트 한정) 구매자/발신자가 고객사 계정에 등록한 우편번호| | |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |highrisk\_txn\_flag |차량 예약과 같은 고객사에서 고위험으로 분류한 결제 건 여부 |위험 거래인 경우 1, 아닐 시 0 | |cd\_string\_one |여분 필드 1 | |
통신사 |Field Name |Description |Format | |---------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format |
결제 시스템 보안 서비스 산업 |Field Name |Description |Format | |---------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format |
기타 산업 |Field Name |Description |Format | |---------------------|----------------------|--------------------------------------------| |sender\_account\_id |구매자 계정의 id | | |sender\_first\_name |구매자의 이름 | | |sender\_last\_name |구매자의 성 | | |sender\_email |구매자의 이메일 |E.123 - Email Address | |sender\_phone |구매자의 휴대전화 번호|E.123 - Telephone Number (national notation)| |sender\_country\_code|구매자의 국가 코드 |ISO Alpha-2 Country Code | |sender\_create\_date |구매자의 계정 생성일 |ISO 8601 date format | |cd\_string\_one |여분 필드 1 | | |cd\_string\_two |여분 필드 2 | | |cd\_int\_one |여분 숫자필드 1 |Number |
## 사용 가능한 결제수단 결제 수단에 따라 가능한 국가 및 통화가 제한적이오니 자세한 사항은 페이팔에 문의해 주세요.
일반 결제수단 - card - credit(PayPal Credit (US, UK)) - paylater - Pay Later (US): 4개월 무이자 할부 또는 6, 12, 24개월 할부 - Pay Later (UK): 3개월 무이자 할부 또는 4개월 무이자 할부 + 이후 유이자 할부 - Pay in 4 (AU): 매 2주마다 4회에 걸쳐 지불 - 4X PayPal (France): 90일 내 4회에 걸쳐 지불 - Später Bezahlen (Germany): 3, 6, 12, 24개월 할부 또는 30일 이내 지불 - Italy: 3개월 할부 - Spain: 3개월 할부 - bancontact(BE / EUR) - blik(PL / PLN) - eps(AT / EUR) - giropay(DE / EUR) - ideal(NL / EUR) - mybank(IT / EUR) - sepa(DE / EUR) - p24(PL / PLN, EUR) - sofort(AT, BE, DE, ES, NL / EUR 또는 GB / GBP)
간편결제수단 (Alternative Methods) - Bancontact - 구매자: BE / EUR - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - BLIK - 구매자: PL/ PLN - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - eps - 구매자: AT / EUR - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - giropay - 구매자: DE / EUR - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - iDEAL - 구매자: IT / EUR - MyBank - 구매자: IT - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - Przelewy24 - 구매자: PL / PLN, EUR - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 - SEPA-Lastschrift - 구매자: DE - SOFORT - 구매자 - AT, BE, DE, ES, NL / EUR - GB / GBP - 머천트: 브라질, 러시아, 일본을 제외한 모든 국가 단, **Venmo(US)와 Pay upon Invoice(DE)는 지원하지 않습니다.**
## 일반결제 유의사항
파라미터 사용 시 유의사항 - orderName: string **주문명** 결제 요청 시 입력한 주문명은 비회원 결제 시에만 결제창에 표기됩니다. (이미지 첨부: 예시) 비회원 결제 화면 1) (이미지 첨부: 예시) 비회원 결제 화면 2) (이미지 첨부: 예시) 회원 결제 화면 1) (이미지 첨부: 예시) 회원 결제 화면 2) - customer.phoneNumber?: string **구매자 연락처** - 페이팔의 경우 [E164 형식](http://www.itu.int/rec/T-REC-E.164-201011-I/en)으로 입력해야 하며, 입력 된 연락처 정보는 페이팔 비회원으로 결제 시 연락처 정보에 자동 입력됩니다. - 예를 들어 한국 구매자의 연락처가 010-1234-5678인 경우 국가번호를 포함하여 821012345678로 입력해야 됩니다. - 만약 접속 국가 형식과 맞지 않는 휴대폰 번호를 입력한 경우 자동완성되지 않고 무시되오니 결제창 호출 시 유의하시기 바랍니다. (이미지 첨부: 예시) 결제창 내 구매자 연락처 입력 화면) - products?: object\[] **구매 상품 상세 정보** - `products.name`(상품명), `products.quantity`(상품 수량), `products.amount`(상품 단위 가격) 정보만 결제창에 표기됩니다. - 각 상품의 수량과 단위 가격을 계산했을 때, 총 주문 금액과 **반드시 일치해야**합니다. 일치하지 않는 경우 에러 메시지가 리턴되면서 결제창이 호출되지 않습니다. - 예를 들어 17달러인 상품 2개와 23달러인 상품 3개에 대한 구매 상품 정보를 기입한 경우 총 주문금액(`totalAmount`)을 `10300`로 입력해야 결제창이 정상적으로 호출됩니다. - 페이팔의 경우 결제 요청 시 **해당 정보를 전달하는 것을 강력하게 권고**하고 있으니 가능한 입력하여 사용하시길 바랍니다. ```ts title="예시 코드" _({ //...중략 products: [ { id: "1666779119262", name: "시그니처 핫 초콜릿", code: "DRINK_SIGNITURE_HOT_CHOCOLATE", amount: 1700, quantity: 2, tag: "TAG-1", }, { id: "1666779134572", name: "아이스 아메리카노", code: "DRINK_AMERICANO", amount: 2300, quantity: 3, tag: "TAG-2", }, ], totalAmount: 10300, currency: "USD", }); ``` (이미지 첨부: 예시) 결제창 내 구매 상품 상세 정보 화면) - name: 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 상품 수량 - currency: string **결제 통화** 페이팔에서 지원하는 통화는 아래 스크린샷을 참고해주세요. 지원하지 않는 통화로 결제 시도시 에러 메시지가 리턴되며 결제창이 호출되지 않습니다. 또한 접속 국가나 결제 수단에 따라 지원하는 통화가 달라질 수 있고, 페이팔의 지원 여부에 따라 결제창 호출이 불가능할 수 있습니다. (이미지 첨부: 사용 가능한 결제 통화) - customer?: object **고객 정보** - 페이팔 결제창 내에서 비회원으로 결제 시 `customer.firstName`과 `customer.lastName`의 정보가 청구인의 이름과 성으로 자동 입력됩니다. `customer.fullName`으로 결제창을 호출하는 경우 자동입력되지 않으니 유의하시기 바랍니다. - 회원으로 결제시에는 **회원 가입시 입력한 이름 정보가 자동으로 입력**되며 결제창 호출 시 입력한 정보로 override 되지 않습니다. (관련 이미지 첨부) - fullName?: string **구매자 전체 이름** `fullName`과 `firstName` / `lastName`이 모두 입력된 경우 `fullName`으로 기록됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`을 입력한 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - paypal\_v2?: object **페이팔에서 제공하는 파라미터 모음** - style?: object **페이팔 버튼 커스텀마이징** 페이팔 결제 버튼을 커스텀마이징 할 경우 자세한 내용은 페이팔에서 제공하는 문서([https://developer.paypal.com/sdk/js/reference/#link-style](http://developer.paypal.com/sdk/js/reference/#link-style))를 참고하세요. - layout?: string **페이팔 버튼 렌더링 방향** - `hotizontal` 적용 시 버튼이 최대 2개까지 밖에 렌더링 되지 않습니다. 때문에 페이팔에서는 `layout`을 `horizontal`이 아닌 `vertical`로 설정하도록 권고하고 있습니다. - 페이팔 버튼은 기본적으로 vertical(수직)로 렌더링 됩니다. ```ts title="예시 코드" PortOne.loadPaymentUI( { //...중략 bypass: { paypal_v2: { style: { //...중략 layout: "horizontal", }, }, }, }, //콜백 함수 ); ``` (이미지 첨부: 예시) vertical style 버튼 표시 화면) (이미지 첨부: 예시) horizontal style 버튼 표시 화면) - color?: string **페이팔 버튼 색상** - `gold`, `blue`, `silver`, `white`, `black` 중 선택할 수 있습니다. - 기본적으로는 `gold`로 표시됩니다. - height?: number **페이팔 버튼 크기** 크기 변경은 25\~55 사이의 값으로만 지정할 수 있습니다. - shape?: string **페이팔 버튼 모양** `rect`(사각 모양)과 `pill`(둥근 모양) 중에 선택할 수 있으며, 기본적으로 `rect` 모양으로 표시됩니다. - label?: string **페이팔 버튼 라벨** - `paypal`, `checkout`, `buynow`, `pay`, `installment` 중 선택할 수 있습니다. - 기본적으로 `paypal`로 표시됩니다. - `installment`는 결제 국가가 `MX`혹은 `BR`인 경우에만 유효합니다. - period?: string **페이팔 버튼에 할부 결제 표시** `label` 파라미터가 `installment`인 경우 버튼에 표시됩니다. - tagline?: boolean **페이팔 버튼에 제공되는 추가 설명** 해당 파라미터를 사용하시기 위해서는 `layout` 파라미터를 `horizontal`로 지정해야 사용하실 수 있습니다. - enable-funding?: string **렌더링할 페이팔 결제 버튼 지정** 결제 버튼 종류를 comma(,) separated string으로 지정하여 결제창을 호출하는 경우 해당 버튼을 포함하여 렌더링됩니다. ```ts title="예시 코드" PortOne.loadPaymentUI( { // ...중략 bypass: { paypal_v2: { "enable-funding": "paylater,card", }, }, }, //콜백 함수 ); ``` (이미지 첨부: 결제 버튼 종류) (이미지 첨부: 예시) 접속 국가: 독일, enable-funding: “paylater” 설정 시 화면) (이미지 첨부: 예시) 접속 국가: 이탈리아, enable-funding: “paylater” 설정 시 화면) (이미지 첨부: 예시) 접속 국가: 벨기에, enable-funding: “paylater” 설정 시 화면) - disable-funding?: string **렌더링에서 제외할 페이팔 결제 버튼 지정** - 결제 버튼 종류를 comma(,) separated string으로 지정하여 결제창을 호출하는 경우 해당 버튼을 제외하고 렌더링됩니다. - 사용 가능한 버튼 종류는 `enable-funding`에서 제공하는 버튼 종류와 동일합니다. (이미지 첨부: 예시) 접속 국가: 이탈리아, enable-funding: 'paylater' 설정 시 화면) (이미지 첨부: 예시) 접속 국가: 이탈리아, enable-funding: 'paylater', disable-funding: 'mybank' 설정 시 화면) - purchase\_units?: object\[] **페이팔 주문 상세 정보** - 각각의 element에 배송 정보를 담을 수 있습니다. - 포트원을 통해 페이팔을 연동하는 고객사는 **`purchase_units`의 길이가 항상 0 또는 1이어야** 합니다. * shipping?: object **상품 배송지 정보** - address?: object **상품 수령 주소** - 결제창 호출 시 기본적으로 구매자가 페이팔에 가입할 때 입력한 배송주소를 렌더링합니다. - `purchase_units\[]`에 입력 된 배송 정보는 결제창에 호출 시 대체로 자동 완성되지만, 페이팔 회원으로 결제할 때와 비회원으로 결제할 때 각각 다른 정책이 적용됩니다. - 주문할 때 입력한 주소로 override하고 싶을 때 `purchase_units\[].shipping.address`에 override할 주소를 입력한 후 결제 요청해야 합니다. 단, **주소가 유효하지 않거나 address\_line\_1을 입력하지 않은 경우엔 override가 되지 않을 수 있습니다.**
예시 1) 페이팔 회원으로 결제 시 `shipping.address` 정보를 입력하지 않은 경우 (이미지 첨부: bypass.paypal\\\_v2.purchase\\\_units\\\[\\].shipping 미입력 → 가입시 설정한 배송 주소로 자동 입력된 화면)
예시 2) 페이팔 회원으로 결제 시 `shipping.address` 정보를 입력한 경우 ```ts PortOne.loadPaymentUI( { bypass: { paypal_v2: { // ...중략 purchase_units: [ { shipping: { address: { // 상품 수령 주소 address_line_1: "세종대로 110", // 도로명 주소 address_line_2: "서울특별시청", // 아파트 동 호수 admin_area_1: "서울특별시", // 주(CA, NY) admin_area_2: "중구", // 시(Los Angeles, New York) postal_code: "04524", // 상품 수령지 우편번호 country_code: "KR", // [필수 입력] 상품 수령지 국가 코드 }, name: { full_name: "홍길동", // 상품 수령인 이름 }, }, }, ], }, }, }, // 콜백 함수 ); ``` (이미지 첨부: bypass.paypal\\\_v2.purchase\\\_units\\\[\\].shipping 입력 → 입력한 배송 주소로 override 된 화면)
예시 3) `shipping.address`의 국가 정보와 구매자의 접속 국가가 일치하지 않은 경우 페이팔 결제창에 렌더링 되는 주소 형식은 구매자의 접속 국가에 따라 결정됩니다. 배송 주소의 국가와 구매자의 접속 국가를 다른 경우, 국가 간 주소 체계가 달라 정상적으로 자동입력 되지 않을 수 있습니다. (이미지 첨부: 접속 국가 : 미국, payer 및 shipping 정보를 한국 주소 체계로 전달한 화면)
- address\_line\_1: string **도로명 주소, ex) `200 N Spring St`** - address\_line\_2?: string **번지 혹은 건물 호수, ex) `Los Angeles City Hall 1`** - admin\_area\_1?: string **주와 같은 큰 단위의 주소, ex) `CA`, `NY`** - country(UK) - state(US) - province(Canada) - 특별시/광역시/도(Korea) - admin\_area\_2?: string **도시, 마을 등 중간 단위의 주소, ex) `Los Angeles`** - postal\_code?: string **우편 번호** - country\_code: string **국가 코드, ex) `KR`** - payer?: object **구매자 상세정보** - tax\_info?: object **구매자 세금 정보** - tax\_id?: string **구매자 세금 ID** - tax\_id\_type?: string **구매자 세금 유형** 브라질(에서 접속한 또는 브라질 계정으로 로그인 한) 구매자인 경우 `bypass.paypal_v2.payer.tax_info` 정보를 필수로 입력해야 합니다. ```ts title="예시 코드" _({ tax_info: { tax_id: "examplestring", tax_id_type: "BR_CPF", }, }); ``` - address?: object **구매자의 결제 금액 청구지 주소 정보(billing address)** 페이팔 비회원 결제 시 페이팔 결제창 내 청구지 주소(billing address) 정보로 사용됩니다. 회원으로 결제하는 경우 회원 가입 시 입력한 billing address가 자동 입력되며 해당 파라미터의 정보는 무시됩니다.
예시 1) 페이팔 회원으로 결제 시 `payer.address` 정보를 입력한 경우 입력된 정보는 무시되고 페이팔 가입 시 기입한 구매자의 청구 주소가 자동 입력됩니다. ```ts title="예시 코드" _({ bypass: { paypal_v2: { // ...중략 payer: { address: { address_line_1: "200 N Spring St", // 도로명 주소 address_line_2: "Los Angeles City Hall", // 아파트 동 호수 admin_area_1: "CA", // 주(CA, NY) admin_area_2: "Los Angeles", // 시(Los Angeles, New York) postal_code: "90012", // 상품 수령지 우편번호 country_code: "US", // [필수 입력] 상품 수령지 국가 코드 }, }, }, }, }); ``` (이미지 첨부: \`payer.address\`입력했음에도 페이팔 가입 시 기입한 정보로 자동 입력된 화면)
예시 2) 페이팔 비회원으로 결제 시 `payer.address` 정보를 입력한 경우 입력된 정보가 구매자의 청구 주소지란에 자동 입력됩니다. ```ts title="예시 코드" _({ bypass: { paypal_v2: { // ...중략 payer: { address: { address_line_1: "200 N Spring St", // 도로명 주소 address_line_2: "Los Angeles City Hall", // 아파트 동 호수 admin_area_1: "CA", // 주(CA, NY) admin_area_2: "Los Angeles", // 시(Los Angeles, New York) postal_code: "90012", // 상품 수령지 우편번호 country_code: "US", // [필수 입력] 상품 수령지 국가 코드 }, }, }, }, }); ``` (이미지 첨부: \`payer.address\`에 입력한 정보로 자동 입력된 화면)
예시 3) 페이팔 비회원으로 결제 시 `payer.address` 정보 미 입력 상태이면서 `shipping.address` 정보를 입력한 경우 구매자의 청구 주소(`bypass.paypal_v2.payer.address`)를 입력하지 않고 배송 주소(`bypass.paypal_v2.pusrchase_units\[].shipping.address`)만 입력한 경우 청구 주소란에 배송 주소가 자동으로 입력됩니다. ```ts title="예시 코드" _({ bypass: { paypal_v2: { // ...중략 purchase_units: [ { shipping: { address: { // 상품 수령 주소 address_line_1: "세종대로 110", // 도로명 주소 address_line_2: "서울특별시청", // 아파트 동 호수 admin_area_1: "서울특별시", // 주(CA, NY) admin_area_2: "중구", // 시(Los Angeles, New York) postal_code: "04524", // 상품 수령지 우편번호 country_code: "KR", // [필수 입력] 상품 수령지 국가 코드 }, name: { full_name: "홍길동", // 상품 수령인 이름 }, }, }, ], }, }, }); ``` (이미지 첨부: 예시) 체크박스 선택 시 청구 주소에 shipping 정보가 자동 입력된 화면) (이미지 첨부: 예시) 체크박스 선택 해제 시 청구 주소와 배송 주소에 모두 shipping 정보가 자동 입력된 화면)
예시 4) 페이팔 비회원으로 결제 시 `payer.address` 정보와 `shipping.address` 정보를 모두 입력한 경우 구매자의 청구 주소(`bypass.paypal_v2.payer.address`)와 배송 주소(`bypass.paypal_v2.shipping.address`)를 모두 입력한 경우엔, **청구 주소와 동일한 배송주소** 체크박스를 해제했을 때 하단에 렌더링 되는 배송 정보란에 배송 주소가 자동 입력됩니다. ```ts title="예시 코드" _({ bypass: { paypal_v2: { // ...중략 purchase_units: [ { shipping: { address: { // 상품 수령 주소 address_line_1: "세종대로 110", // 도로명 주소 address_line_2: "서울특별시청", // 아파트 동 호수 admin_area_1: "서울특별시", // 주(CA, NY) admin_area_2: "중구", // 시(Los Angeles, New York) postal_code: "04524", // 상품 수령지 우편번호 country_code: "KR", // [필수 입력] 상품 수령지 국가 코드 }, name: { full_name: "홍길동", // 상품 수령인 이름 }, }, }, ], payer: { address: { address_line_1: "고산자로 270", // 도로명 주소 address_line_2: "성동구청", // 아파트 동 호수 admin_area_1: "서울특별시", // 주(CA, NY) admin_area_2: "성동구", // 시(Los Angeles, New York) postal_code: "04750", // 상품 수령지 우편번호 country_code: "KR", // [필수 입력] 상품 수령지 국가 코드 }, }, }, }, }); ``` (이미지 첨부: 예시) 체크박스 선택 시 청구 주소란에 payer 정보가 자동 입력된 화면) (이미지 첨부: 예시) 체크박스 해제 시 payer 정보는 청구 주소란에 shipping 정보는 배송 주소란에 정상적으로 자동 입력된 경우)
예시 5) `payer.address`의 국가 정보와 구매자의 접속 국가가 일치하지 않은 경우 페이팔 결제창에 렌더링 되는 주소 형식은 구매자의 접속 국가에 따라 결정됩니다. 청구 주소의 국가와 구매자의 접속 국가를 다른 경우, 국가 간 주소 체계가 달라 정상적으로 자동입력 되지 않을 수 있습니다. (이미지 첨부: 접속 국가 : 미국, \`payer.address\`정보를 한국 주소 체계로 전달한 화면)
- address\_line\_1?: string **도로명 주소, ex) `200 N Spring St`** - address\_line\_2?: string **번지 혹은 건물 호수, ex) `Los Angeles City Hall 1`** - admin\_area\_1?: string **주와 같은 큰 단위의 주소, ex) `CA`, `NY`** - country(UK) - state(US) - province(Canada) - 특별시/광역시/도(Korea) - admin\_area\_2?: string **도시, 마을 등 중간 단위의 주소, ex) `Los Angeles`** - postal\_code?: string **우편 번호** - country\_code: string **국가 코드, ex) `KR`**
미지원 파라미터 - taxFreeAmount?: number **면세 금액** 페이팔은 면세/복합과세를 지원하지 않기 때문에 taxFreeAmount 입력한 경우 “taxFreeAmount must be 0 in Paypal!”이라는 에러 메시지가 리턴되면서 결제창이 호출되지 않습니다. - country?: string **결제 국가** - 페이팔의 경우 실연동 결제 시 **구매자가 접속한 국가에 따라 국가 정보가 자동으로 적용**되어 해당 파라미터로 전달한 국가 정보는 무시됩니다. - 예시) `country : US`를 입력하여 결제창을 호출했지만 구매자가 접속한 환경이 “KR(한국)”인 경우 한국에 지원되는 결제 버튼만 렌더링됩니다. - 페이팔 sandbox 모드인 경우 입력한 국가 정보로 전달됩니다. - customer?: object **고객 정보** - address?: object **구매자 주소** - 페이팔의 경우 사용되는 주소 체계가 달라 구매자 주소 정보는 `customer.address`이 아닌 **`bypass.paypal_v2.payer.address` 혹은 `bypass.paypal_v2.purchase_units\[].shipping.address`를 사용**해야 합니다. - `bypass.paypal_v2.payer.address`, `bypass.paypal_v2.purchase_units\[].shipping.address` 파라미터에 대한 자세한 사항은 **파라미터 사용 시 유의사항** 을 참고하시기 바랍니다. - redirectUrl?: string **리디력션 방식에서 결제 프로세스 완료 후 이동될 고객사 URL** 페이팔의 경우 PC와 모바일 모두 팝업으로 결제창이 렌더링되기 때문에 결제 프로세스 종료시 콜백 함수가 호촐됩니다. 따라서 redirectUrl 파라미터는 무시됩니다. - appScheme?: string **모바일 결제 후 고객사 앱으로 복귀를 위한 URL scheme** 페이팔의 경우 외부 앱으로 이동하지 않아 해당 파라미터는 무시됩니다. - `isEscrow` **에스크로 결제 여부** 페이팔의 경우 에스크로 결제를 지원하지 않기 때문에 해당 파라미터는 무시됩니다. - `locale` **결제창 표시 언어** 페이팔의 경우 구매자가 접속한 환경에 따라 자동 적용되기 때문에 해당 파라미터는 무시됩니다. - `isCulturalExpense` **문화비 지출 여부** 페이팔의 경우 도서 문화비 항목을 지원하지 않아 해당 파라미터는 무시됩니다. - offerPeriod?: string **서비스 제공 기간** 페이팔은 결제창 내 제공 기간 정보 노출을 지원하지 않아 해당 파라미터가 무시됩니다. - storeDetails?: object **상점 정보** 페이팔은 상점 세부 정보를 지원하지 않아 해당 파라미터가 무시됩니다. - card?: object **카드 결제에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 카드 결제 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다. - virtualAccount?: object **가상계좌 발급에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 가상계좌 발급 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다. - transfer?: object **계좌이체 결제에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 계좌이체 결제 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다. - mobile?: object **휴대폰 소액결제에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 휴대폰 소액결제 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다. - giftCertificate?: object **상품권 결제에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 상품권 결제 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다. - easyPay?: object **간편결제 결제에 대한 상세 옵션** 페이팔의 경우 결제 요청 시 결제 수단은 항상 `paypal`로 지정되며, 간편결제 결제 시 사용되는 옵션 설정을 지원하지 않아 해당 파라미터를 사용할 수 없습니다.
### 일반결제 FAQ
모든 결제 건의 결제수단은 `paypal`로 저장되나요? 페이팔을 통해 카드 결제 외 BanContact, BLIK, eps, giropay 등 다양한 결제 수단으로 결제가 가능하지만 **결제 승인 이후 상세 결제 수단 정보**를 알 수 없기에 `paypal`로 일괄 저장됩니다.
할부 결제 여부와 할부 개월수에 대한 정보는 어디서 확인할 수 있나요? 페이팔에서 Pay Later를 통해 할부 결제가 가능하지만 **결제 승인 이후 상세 할부 정보**를 알 수 없기에 할부에 대한 정보는 제공하지 않습니다.
접속한 국가에 따라 렌더링 되는 결제 버튼이 달라요. 페이팔은 **구매자가 접속한 나라에 따라 이용 가능한 결제 수단**이 달라 접속 국가에 따라 렌더링되는 버튼의 종류와 개수가 달라집니다. (이미지 첨부: 예시 1) (이미지 첨부: 예시 2)
페이팔 회원과 비회원에 따라 결제 플로우가 달라요. 페이팔은 기본적으로 구매자가 페이팔에 가입 후 로그인하여 등록된 결제 수단(없다면 새로 등록 또는 카드 정보 직접 입력)으로 결제하는 방식입니다. 다만, 비회원도 결제가 가능하도록 제공하고 있지만 사용 가능한 결제 수단과 렌더링 되는 결제창에 다소 차이가 있습니다. 회원과 비회원간 기능 차이를 간략하게 정리하면 아래와 같습니다. (관련 이미지 첨부)
Pay Later(할부) 기능을 사용하고 싶어요. #### 1. Pay Later 버튼 활성화하기 페이팔의 Pay Later(할부) 결제를 사용하려면 `enable-funding` 파라미터에 `paylater` 입력한 후 호출해야 합니다. 포트원의 경우 Pay Later를 버튼 형태로 제공하고 있으며, 위의 파라미터를 입력하지 않는 시 Pay Later를 지원하는 국가에서 접속하더라도 Pay Later 버튼이 표시되지 않습니다. (단, 미국의 경우 자동으로 표시됩니다.) ```ts PortOne.loadPaymentUI({ // ...중략 bypass: { paypal_v2: { // ...중략 "enable-funding": "paylater", }, }, }); ``` Pay Later 버튼은 **구매자가 접속한 국가에 따라 다른 버튼이 렌더링** 되며, Pay Later 기능을 제공하지 않는 국가에서 접속한 경우 `enable-funding` 파라미터에 `paylater` 값을 전달하더라도 **Pay Later 버튼이 렌더링되지 않습니다.** (이미지 첨부: 예시) 벨기에에서 접속 시 버튼이 렌더링 되지 않음) (이미지 첨부: 예시) 프랑스에서 접속 시 '4X Paypal' 버튼이 렌더링 됨) (이미지 첨부: 예시) 이탈리아에서 접속 시 'Paga in 3 rate' 버튼이 렌더링 됨) Pay Later 기능을 지원하는 국가에서 접속하더라도 구매자 계정에 설정된 국가가 Pay Later를 제공하지 않는 국가인 경우, 일반 카드 결제 화면이 렌더링됩니다.
#### 2. Pay Later 사용 국가별 페이팔 계정 생성하기 Pay Later(할부) 기능을 여러 국가에 제공하기 위해서는 **페이팔 머천트 계정을 국가별로 각각 따로 만들어야** 합니다. 예를 들어 고객사이 \[독일], \[스페인], \[이탈리아] 3개 국가에 대해 Pay Later 서비스를 제공하고자 하는 경우 고객사는 \[독일], \[스페인], \[이탈리아]의 **페이팔 머천트 계정을 각각 따로 만들어야** 합니다. 국가별로 생성한 페이팔 Account ID를 \[결제 연동] > \[채널 관리] 페이지에서 채널 등록 후 결제창 호출 시 지정해야 합니다. **고객사는 구매자가 접속한 국가에 따라 올바른 채널의 채널키를 전달해야** 합니다.
#### 3. Pay Later 국가별 정책 알아보기 - US(미국) / USD(달러) - Pay in 4 - Eligible US buyers can pay in four interest-free payments for purchases of $30 to $1,500. - USD 30 \~ USD 1,500 결제 시 4개월 무이자 할부 제공 - Pay Monthly - Eligible US buyers can pay in 6, 12, or 24 monthly installments for purchases of $199 to $10,000. - USD 199 \~ USD 10,000 결제 시 6, 12, 24개월 (유이자) 할부 중 선택하도록 제공 - AU(호주) / AUD(호주 달러) - Pay in 4 Pay Later in Australia includes Pay in 4, which eligible AU buyers can use to pay in four interest-free payments for purchases of $30 to $2,000 AUD. The first payment is due at the time of the transaction, and subsequent payments are due every two weeks. AUD 30 \~ AUD 2,000 결제 시 2주마다 4번에 걸쳐 결제하도록 제공 - GE(독일) / EUR(유로화) - PayPal Ratenzahlung - Eligible German buyers can pay in 3, 6, 12, or 24 monthly installments for purchases of 99€ to 5,000€. - EUR 99 \~ EUR 5,000 결제 시 3, 6, 12, 24개월 (유이자) 할부 중 선택하도록 제공 - Pay in 30 - Eligible German buyers can pay within 30 days for purchases of 1€ to 1,000€. - EUR 1 \~ EUR 1,000 결제 시 30일 안에 결제되며, 30일 안에 자동으로 결제될 은행 계좌(IBAN, International Bank Account Number) 등록하도록 제공 - ES(스페인) / EUR(유로화) - Pay in 3 installments - Pay Later in Spain includes Pay in 3 instalments, which eligible buyers in Spain can use to pay in three interest-free payments for purchases of 30€ – 2,000€. The first payment is due at the time of the transaction, and subsequent payments are due every month. - EUR 30 \~ EUR 2,000 결제 시 3개월 무이자 할부 제공 - IT(이탈리아) / EUR(유로화) - Pay in 3 installments - Pay Later in Italy includes Pay in 3 installments, which eligible buyers in Italy can use to pay in three interest-free payments for purchases of 30€ – 2,000€. The first payment is due at the time of the transaction, and subsequent payments are due every month. - EUR 30 \~ EUR 2,000 결제 시 3개월 무이자 할부 제공 - FR(프랑스) / EUR(유로화) - Pay in 4X - Pay Later in France includes Pay in 4X, which is an installment offer that allows consumers to spread the cost of a purchases across four equal payments for transactions between 30€ – 2,000€. The first payment is due at the time of the transaction. The subsequent payments spread across 90 days. - EUR 30 \~ EUR 2,000 결제 시 90일동안 4번에 걸쳐 결제하도록 제공 (무이자) - GB(영국) / GBP(영국 파운드화) - Pay in 3 - Eligible UK buyers can pay in three interest-free payments for purchases of £30 – £2,000. - GBP 30 \~ GBP 2,000 결제 시 3개월 무이자 할부 제공 - PayPal Credit - Eligible UK buyers receive a revolving line of credit that they can use to pay over time. PayPal Credit offers either 0% interest for 4 months on purchases over £99 or a merchant-specific Installment offers. For the 0% interest for 4 months offer, any remaining balance due after the promotional period or any transactions under £99 are charged interest at the standard variable rate. Terms and conditions apply. - GBP 99 이상 결제 시 첫 4개월 간 무이자 할부 제공. 4개월 이상 할부 결제 시 5개월째부터는 유이자 할부 적용
간편 결제 수단(Alternative Method) 버튼이 표시되지 않아요. 기본적으로 `loadPaymentUI` 함수를 호출해 페이팔 결제 버튼을 렌더링하는 경우 구매자가 접속한 국가에 따라 이용 가능한 간편 결제 수단 버튼들이 자동으로 렌더링 됩니다. 하지만 일부 버튼의 경우엔 자동으로 렌더링되지 않는 경우가 있습니다. 원하는 간편 결제 수단 버튼이 표시되지 않는 경우 나라별로 지원 가능한 간편 결제 수단(Alternative Method) 식별자를 `enable-funding` 파라미터에 아래와 같이 comma(,)로 구분하여 string(문자열) 형식으로 요청하면 정상적으로 렌더링됩니다. 💡 예) enable-funding: “paylater,bancontact” 렌더링 할 수 있는 버튼의 종류는 아래와 같습니다. (관련 이미지 첨부) />
간편 결제 수단(Alternative Method)을 클릭해도 결제가 되지 않아요. 페이팔은 기본적으로 결제창 호출 시 구매자가 페이팔에 가입할 때 입력한 배송 주소가 자동으로 입력됩니다. 배송 주소를 변경하고자 할 때, 국가 코드(`purchase\_units\[].shipping.address.country\_code`)가 변경하는 경우 변경된 국가 코드에 따라 기존에 선택한 **간편 결제 수단(Alternative Method)이 지원되지 않는 국가인 경우 결제가 불가능**할 수 있습니다. 예를 들어 벨기에(국가코드: BE)에서만 사용 가능한 BanContact로 결제 시, `purchase\_units\[].shipping.address.country\_code`를 BE가 아닌 다른 값으로 변경한 후 BanContact 결제 버튼을 클릭하면 아래와 첨부한 스크린샷과 같이 일반 카드 결제 화면이 렌더링됩니다. (관련 이미지 첨부)
### 정기결제 유의사항
파라미터 사용 시 유의사항 - orderName: string **주문명** 빌링키 발급 창 내 “판매자가 보낸 메모” 내용으로 표기됩니다. (이미지 첨부: 예시) 빌링키 발급 시 화면) - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - paypal\_v2?: object **페이팔에서 제공하는 파라미터 모음** ```ts title="예시 코드" PortOne.loadPaymentUI( { bypass: { paypal_v2: { shipping_address: { // 상품 수령 주소 recipient_name: "홍길동", // 수령인 이름 line1: "세종대로 110", // 도로명 주소 line2: "서울특별시청", // 아파트 동 호수 city: "중구", // 시(Los Angeles, New York) state: "서울특별시", // 주(CA, NY) postal_code: "04524", // 상품 수령지 우편번호 country_code: "KR", // [필수 입력] 상품 수령지 국가 코드 }, }, }, }, // 콜백 함수 ); ``` (이미지 첨부: shipping\_address를 전달하지 않은 경우 구매자 정보로 설정된 화면) (이미지 첨부: shipping\_address에 수령인 이름과 배송 정보를 전달한 경우 수령인 이름과 배송 정보가 override된 화면) - style?: string **페이팔 버튼 커스텀마이징** 페이팔 버튼을 커스텀마이징 할 경우 자세한 내용은 페이팔에서 제공하는 문서([https://developer.paypal.com/sdk/js/reference/#link-style](http://developer.paypal.com/sdk/js/reference/#link-style))를 참고하세요. - layout?: string **페이팔 버튼 렌더링 방향** - `hotizontal` 적용 시 버튼이 최대 2개까지 밖에 렌더링 되지 않습니다. 때문에 페이팔에서는 `layout`을 `horizontal`이 아닌 `vertical`로 설정하도록 권고하고 있습니다. - 페이팔 버튼은 기본적으로 vertical(수직)로 렌더링 됩니다. ```ts title="예시 코드" PortOne.loadPaymentUI( { //...중략 bypass: { paypal_v2: { style: { //...중략 layout: "horizontal", }, }, }, }, //콜백 함수 ); ``` (이미지 첨부: 예시) vertical style 버튼 표시 화면) (이미지 첨부: 예시) horizontal style 버튼 표시 화면) - color?: string **페이팔 버튼 색상** - `gold`, `blue`, `silver`, `white`, `black` 중 선택할 수 있습니다. - 기본적으로는 `gold`로 표시됩니다. - height?: number **페이팔 버튼 크기** 크기 변경은 25\~55 사이의 값으로만 지정할 수 있습니다. - shape?: string **페이팔 버튼 모양** `rect`(사각 모양)과 `pill`(둥근 모양) 중에 선택할 수 있으며, 기본적으로 `rect` 모양으로 표시됩니다. - label?: string **페이팔 버튼 라벨** - `paypal`, `checkout`, `buynow`, `pay`, `installment` 중 선택할 수 있습니다. - 기본적으로 `paypal`로 표시됩니다. - `installment`는 결제 국가가 `MX`혹은 `BR`인 경우에만 유효합니다. - period?: string **페이팔 버튼에 할부 결제 표시** `label:installment`인 경우 버튼에 표시됩니다. - tagline?: boolean **페이팔 버튼에 제공되는 추가 설명** 해당 파라미터를 사용하시기 위해서는 `bypass.paypal_v2.style.layout`을 horizontal로 지정해야 사용하실 수 있습니다. - shipping\_address?: object **주문 상품의 배송 주소** - 배송 정보 중 `line1`, `city` 그리고 `country_code`는 필수 입력해야 합니다. 전달하지 않을 경우 에러가 리턴되며 빌링키 발급창이 호출되지 않습니다. * recipient\_name?: string **수령인 이름** * line1: string **도로명 주소, ex) `200 N Spring St`** * line2?: string **번지 혹은 건물 호수, ex) `Los Angeles City Hall 1`** * city: string **도시, 마을 등 중간 단위의 주소, ex) `Los Angeles`** * state?: string **주와 같은 큰 단위의 주소, ex) `CA`, `NY`** - country(UK) - state(US) - province(Canada) - 특별시/광역시/도(Korea) * postal\_code?: string **우편 번호** * country\_code: string **국가 코드, ex) `KR`** - 페이팔의 경우 빌링키 발급창에 기본적으로 구매자가 페이팔에 가입할 때 입력한 배송 정보가 자동으로 입력됩니다. 만약 이 배송 정보를 override하고 싶다면 `shipping_address` 파라미터에 override할 주소를 입력하고 `shipping_address.recipient_name`에 override할 수령인 이름을 입력하신 후 호출하시면 됩니다.
미지원 파라미터 - totalAmount?: number **총 결제 금액** 빌링키 발급 시 지원하지 않는 파라미터로 발급 시 무조건 0으로 저장됩니다. - taxFreeAmount?: number **면세 금액** 페이팔은 면세/복합과세를 지원하지 않기 때문에 해당 파라미터는 지원하지 않습니다. - country?: string **결제 국가** - 페이팔의 경우 실연동 결제 시 **구매자가 접속한 국가에 따라 국가 정보가 자동으로 적용**되어 해당 파라미터로 전달한 국가 정보는 무시됩니다. - 예시) `country : US`를 입력하여 결제창을 호출했지만 구매자가 접속한 환경이 “KR(한국)”인 경우 한국에 지원되는 결제 버튼만 렌더링됩니다. - 페이팔 sandbox 모드인 경우 입력한 국가 정보로 전달됩니다. - currency?: string **결제 통화** 빌링키 발급 시 결제가 되지 않기 때문에 해당 파라미터는 무시됩니다. - customer?: object **고객 정보** - address?: object **구매자 주소** - 페이팔의 경우 사용되는 주소 체계가 달라 구매자 주소 정보는 `customer.address`이 아닌 **`bypass.paypal_v2.shipping_address`를 사용**해야 합니다. - `bypass.paypal_v2.shipping_address` 파라미터에 대한 자세한 사항은 **파라미터 사용 시 유의사항** 을 참고하시기 바랍니다. - redirectUrl?: string **리디력션 방식에서 결제 프로세스 완료 후 이동될 고객사 URL** 페이팔의 경우 PC와 모바일 모두 팝업으로 빌링키 발급창이 렌더링되기 때문에 프로세스 종료시 콜백 함수가 호촐됩니다. 따라서 redirectUrl 파라미터는 무시됩니다. - appScheme?: string **모바일 결제 후 고객사 앱으로 복귀를 위한 URL scheme** 페이팔의 경우 외부 앱으로 이동하지 않아 해당 파라미터는 무시됩니다. - `isEscrow` **에스크로 결제 여부** 페이팔의 경우 에스크로 결제를 지원하지 않기 때문에 해당 파라미터는 무시됩니다. - `locale` **결제창 표시 언어** 페이팔의 경우 구매자가 접속한 환경에 따라 자동 적용되기 때문에 해당 파라미터는 무시됩니다. - `isCulturalExpense` **문화비 지출 여부** 페이팔의 경우 도서 문화비 항목을 지원하지 않아 해당 파라미터는 무시됩니다. - offerPeriod?: string **서비스 제공 기간** 페이팔은 결제창 내 제공 기간 정보 노출을 지원하지 않아 해당 파라미터가 무시됩니다. - storeDetails?: object **상점 정보** 페이팔은 상점 세부 정보를 지원하지 않아 해당 파라미터가 무시됩니다.
미국 테스트 상점 아이디 사용 불가 페이팔 내부 이슈로 인해 미국 테스트 상점 아이디인 `7WBB3CKT63FRG`을 사용할 수 없습니다. 영국이나 일본 등 다른 테스트 상점 아이디를 통해 테스트가 필요합니다.
**(필독) Risk Data Acquisition 정책** 페이팔은 이상 거래를 줄이기 위해 Risk Data Acquisition 정책을 시행하고 있습니다. 일반적으로 페이팔 창에서 진행되는 결제나 빌링키 발급은 페이팔이 구매자 접속 정보를 직접 확인하여 이상 거래를 판단합니다. 하지만 발급된 빌링키로 브라우저에서 결제하는 경우 \[고객사 브라우저]에서 \[포트원 API]를 통해 \[페이팔 API]가 호출되는 구조로 페이팔이 구매자 접속 정보를 직접 확인할 수 없어 이상거래를 판단하기 어렵습니다. 따라서 구매자의 브라우저/디바이스 접속 정보를 페이팔에 전달해야 합니다. 때문에 브라우저에서 발급된 빌링키를 이용하여 결제를 호출하는 경우 **고객사 클라이언트 페이지에 페이팔 Fraudnet 스크립트/Magnes SDK를 반드시 추가해야** 합니다.
결제 플로우 알아보기 브라우저/앱에 페이팔 Fraudnet Script/Magnes SDK를 추가한 후 빌링키 결제 관련 API를 호출했을 때의 플로우는 다음과 같습니다. (관련 이미지 첨부)
브라우저 내 스크립트 사용 예시 ```html title="코드 예시" ``` - 파라미터 설명 |파라미터 |설명 |예시 | |---------|-------------------------------------------------------------------------------|-----------------------------------------------| |`fncls` |`fnparams-dede7cc5-15fd-4c75-a9f4-36c430ee3a99`로 항상 고정 |`fnparams-dede7cc5-15fd-4c75-a9f4-36c430ee3a99`| |`f` |주문번호(`paymentId`) 전달 |`paymentId_230980198` | |`s` |string (`{페이팔 Account ID}_{페이지 유형}` 형식. 페이지 유형은 아래 목록 참고)|`7WBB3CKT63FRG_checkout-page` | |`sandbox`|페이팔 Account ID가 테스트 용인지 운영 용인지 여부 |`true` | - 페이지 유형 - `home-page` - `search-result-page` - `category-page` - `product-detail-page` - `cart-page` - `inline-cart-page` - `checkout-page`
앱 내 스크립트 사용 예시 - 안드로이드 [**Android Integration of Magnes**](http://developer.paypal.com/limited-release/magnes/integrate/android/) 가이드 문서에 따라 아래와 같이 collectAndSubmit 메서드 호출을 통해 페이팔로 디바이스 정보를 보내야 합니다. 이때 두 번째 파라미터(`paypalClientMetaDataId`)로는 주문번호(`paymentId`)를 전달해야 합니다. ```java title="코드 예시" MagnesResult magnesResult = MagnesSDK.getInstance() .collectAndSubmit( context, // Context paypalClientMetaDataId, // String additionalData // HashMap ) ``` - iOS Switft [**iOS Swift SDK Integration**](http://developer.paypal.com/limited-release/magnes/integrate/ios-swift/) 가이드 문서에 따라 아래와 같이 collectAndSubmit 메서드 호출을 통해 페이팔로 디바이스 정보를 보내야합니다. 이때 첫번째 파라미터(withPayPalClientMetadataId)로는 주문번호(paymentId)를 전달해야 합니다. ```swift title="코드 예시" let magnesResult: MagnesResult = MagnesSDK.shared().collectAndSubmit( withPayPalClientMetadataId: "YOUR-PAYPAL-CLIENT-METADATA-ID", withAdditionalData: [String: String] ) ``` - iOS Objective-C [**iOS Objective-C SDK Integration of Magnes**](http://developer.paypal.com/limited-release/magnes/integrate/ios-objective-c/) 가이드 문서에 따라 아래와 같이 collectAndSubmitWithPayPalClientMetadataId 메서드 호출을 통해 페이팔로 디바이스 정보를 보내야 합니다. 이때 첫번째 파라미터(YOUR-PAYPAL-CLIENT-METADATA-ID)로는 주문번호(paymentId)를 전달해주시면 됩니다. ```objc title="코드 예시" //PPRMOCMagnesSDK *magnesSDK = [PPRMOCMagnesSDK shared]; PPRMOCMagnesSDKResult *magnesResult = [magnesSDK collectAndSubmitWithPayPalClientMetadataId:@"YOUR-PAYPAL-CLIENT-METADATA-ID" withAdditionalData:@{}]; ```
### 정기결제 FAQ
모든 빌링키 발급 건의 결제수단은 paypal로 저장되나요? 페이팔을 통해 카드 결제 외 BanContact, BLIK, eps, giropay 등 다양한 결제 수단으로 결제가 가능하지만 **빌링키 발급 승인 이후 상세 결제 수단 정보**를 알 수 없기에 paypal로 일괄 저장되며 [빌링키 단건 조회 API](https://developers.portone.io/api/rest-v2/billingKey#get%20%2Fbilling-keys%2F%7BbillingKey%7D)로 조회시 결제수단 상세 정보는 모두 null로 내려갑니다.
# https://developers.portone.io/opi/ko/integration/pg/v2/readme --- title: 결제대행사 선택하여 연동하기 description: 각 PG사별 결제 연동 방법을 확인할 수 있습니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/readme --- 하위 페이지에서 각 PG사별 결제 연동 방법을 확인할 수 있습니다. ## PG사별 지원되는 결제 수단 정보 ### 결제 #### 결제대행사 - **토스페이먼츠** - 연동 기능: 인증결제(결제창) / 비인증결제(API) / 정기결제(결제창/API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제 : 카드 / 퀵계좌이체 / 가상계좌 / 휴대폰 소액결제 / 상품권(컬쳐랜드 / 스마트문상 / 도서문화상품권) - 결제창 수기(키인)결제 : 카드 - API 수기(키인)결제 : 카드 / 가상계좌 - 결제창/API 정기결제 : 카드 - 간편결제 허브형 : 카카오페이 / 네이버페이 / 페이코 / SSGPay / LPay / 삼성페이 / 애플페이 / 토스페이 - **KSNET** - 연동 기능: 인증결제(결제창) / 비인증결제(API) / 정기결제(API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제 : 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 소액결제 - API 수기(키인)결제 : 카드 / 가상계좌 - API 정기결제 : 카드 - 간편결제 허브형 : 카카오페이 / 네이버페이 / 페이코 / SSGPay / LPay - **스마트로** - 연동 기능: 인증결제(결제창) / 비인증결제(API) / 정기결제(결제창/API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제 : 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 소액결제 - API 수기(키인)결제 : 가상계좌 - 결제창/API 정기결제 : 카드 - 간편결제 허브형 : 카카오페이 / 네이버페이 / 페이코 / LPay / 핀페이 - **나이스정보통신** - 연동 기능: 인증결제(결제창) / 비인증결제(API) / 정기결제(API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제 : 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 소액결제 / 상품권(컬쳐랜드) - 결제창 정기결제 : 카카오페이 / 네이버페이 - API 수기(키인)결제 : 카드 / 가상계좌 - API 정기결제 : 카드 - 간편결제 허브형 : 카카오페이 / 네이버페이 / 페이코 / SSGPay / LPay / 삼성페이 / 애플페이 / 11Pay / 토스페이 - **KG이니시스** - 연동 기능 : 인증결제(결제창) / 비인증결제(API) / 정기결제(결제창/API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제: 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 결제 / 상품권 결제(컬처랜드/스마트문상/도서문화상품권) - API 수기(키인)결제: 카드 / 가상계좌 - 결제창/API 정기결제: 카드 / 휴대폰 - 간편결제 허브형: 카카오페이 / 네이버페이 / 토스페이 / 삼성페이 / SSGpay / L.Pay / 애플페이 / 페이코 - **KG이니시스 일본결제** - 연동 기능 : 인증결제(결제창) / 간편결제(결제창) - 결제 수단 - 결제창 일반결제: 카드 / 편의점결제 - 간편결제 허브형: RakutenPay, Amazon Pay, Paypay, dBarai, Au Pay, Merpay - **한국결제네트웍스(KPN)** - 연동 기능 : 인증결제(결제창) / 비인증결제(API) / 정기결제(결제창/API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제: 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 결제 - API 수기(키인)결제: 카드 / 가상계좌 - 결제창/API 정기결제: 카드 - 간편결제 허브형: 카카오페이 / 네이버페이 / 토스페이 / 삼성페이 / 페이코 - **NHN KCP** - 연동 기능 : 인증결제(결제창) / 비인증결제(API) / 정기결제(결제창/API) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제: 카드 / 실시간 계좌이체 / 가상계좌 / 휴대폰 결제 - API 수기(키인)결제: 카드 / 가상계좌 - 결제창/API 정기결제: 카드 - 간편결제 허브형: 카카오페이 / 네이버페이 / 토스페이 / 삼성페이 / SSGpay / L.Pay / 애플페이 / 페이코 - **엑심베이** - 연동 기능 : 인증결제(결제창) / 간편결제(결제창/다이렉트 호출) - 결제 수단 - 결제창 일반결제: 카드 / 실시간 계좌이체 / 가상계좌 - 간편결제 허브형: 카카오페이 / 토스페이 / 페이코 #### 간편결제 직연동 - **카카오페이** - 연동 기능: 간편결제(결제창) - 결제 수단 - 간편결제: 카카오페이 - **네이버페이** - 연동 기능: 간편결제(결제창) - 결제 수단 - 간편결제: 네이버페이 - **토스페이** - 연동 기능 : 간편결제(결제창) - 결제 수단 - 간편결제 : 토스페이 #### 해외결제 - **페이팔** - 연동 기능 : 인증결제(결제창) / 정기결제(결제창) - 결제 수단 - 해외결제 일반결제 / 정기결제 : 카드 / 계좌이체 (구매자 페이팔 계정에 등록 후 사용 가능) - **엑심베이** - 연동 기능 : 인증결제(결제창) / 정기결제(결제창) - 결제 수단 - 해외결제 일반결제 : 카드 / 유니온페이 / 알리페이 / 위챗페이 / 일본 편의점 결제 등 - 해외결제 정기결제 : 카드 - **페이레터** - 연동 기능 : 인증결제(결제창) / 정기결제(결제창/API) - 결제 수단 - 해외결제 일반결제 : 카드 / 유니온페이 / 알리페이 / 위챗페이 - 해외결제 정기결제 : 카드 / 유니온페이 - **이지페이(KICC)** - 연동 기능 : 인증결제(결제창) - 결제 수단 - 해외결제 일반결제 : 위챗페이 / 알리페이 플러스 - **페이먼트월** - 연동 기능 : 인증결제(결제창) - 결제 수단 - 해외결제 일반결제 ### 본인인증 - **다날 본인인증** - 연동 기능: SMS 문자 메세지를 통한 본인인증 / PASS APP을 통한 본인인증 - 본인인증 수단 - SDK 본인인증: SMS / PASS - API 본인인증: SMS / PASS - **이니시스 통합인증** - 연동 기능: 민간인증서 및 PASS APP을 통한 본인인증 - 본인인증 수단 - SDK 본인인증만 지원 # https://developers.portone.io/opi/ko/integration/pg/v2/smartro-v2 --- title: 스마트로 description: 스마트로 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/smartro-v2/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. V2 결제 모듈을 사용하시려면 스마트로(신모듈)로 연동하셔야 합니다. ## 가능한 결제 수단 - **결제창 일반결제** `payMethod` 파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다. - 신용카드 : `CARD` - 실시간 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 간편 결제 : `EASY_PAY` - **결제창 빌링키발급** `payMethod` 파라미터를 `card`로 설정해야 합니다 - **API 수기(키인) 결제** `method` 파라미터를 `virtualAccount`로 설정해야 합니다. - **API 빌링키 발급** `method` 파라미터를 `card`로 설정해야 합니다. ## 공통 유의사항
주문 번호(`paymentId`)에 특수문자를 사용할 수 없습니다. SDK 및 API를 이용하여 결제 요청시 숫자, 문자(알파벳 소문자와 대문자) 또는 그 조합으로 이루어진 거래 번호를 사용해야 합니다.
주문 번호(`paymentId`)는 최대 40자까지 입력할 수 있습니다. 스마트로의 경우 `paymentId`는 최대 40자까지 가능하며, 40자가 넘을 경우 40자까지 잘려서 저장됩니다.
결제통화(`currency`) 파라미터가 적용되지 않습니다. 일반적으로 `currency` 파라미터를 이용하여 결제통화를 지정할 수 있지만 스마트로의 경우 상점아이디 설정에 따라 사용 가능한 통화가 자동으로 결정됩니다. 따라서 결제 요청 시 `currency`를 입력하더라도 적용되지 않습니다. 스마트로의 경우 `KRW`와 `USD`만 지원하며 이 외의 값을 입력하는 경우 에러를 리턴하며 결제가 진행되지 않습니다.
## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 스마트로 채널 사용을 명시해주세요. 스마트로 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "CARD", customer: { phoneNumber: "010-0000-1234", }, }); } ```
### 주요 파라미터 - 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 **고객 정보** - customerId?: string **구매자 고유 ID** - 스마트로의 경우 간편결제로 결제 요청시 필수로 입력해야 합니다. - 20자 이하로만 입력 가능합니다. - phoneNumber?: string **구매자 연락처** - 스마트로의 경우 결제창 호출 시 필수로 입력합니다. - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - smartro\_v2?: object **스마트로에서 제공하는 파라미터 모음** - GoodsCnt?: number **결제 상품 품목 갯수** - SkinColor?: string **UI 색상 스타일** - 미 설정시 기본으로 `RED`로 적용됩니다. - `RED`, `GREEN`, `BLUE`, `PURPLE`를 선택할 수 있습니다. - OpenType?: string **해외 카드 사용 설정** - 국내 카드: `KR`, 해외 카드: `EN` - 미 설정시 기본으로 `KR`로 적용됩니다. - `EN`으로 설정 시 해외 카드만 결제가 가능합니다. - 예시 코드 ```json { "bypass": { "smartro_v2": { "GoodsCnt": 2, "SkinColor": "BLUE", "OpenType": "EN" } } } ``` ## SDK 빌링키 발급 요청하기 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 스마트로 채널 사용을 명시해주세요. 스마트로 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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", }); } ```
### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyMethod: string **빌링키 발급수단** 스마트로는 카드 이외 발급 수단은 지원하지 않아 `CARD`로 설정해야 합니다. - issueId: string **빌링키 발급 건 고유 ID** - 고객사에서 채번하여 사용해야 합니다. - 스마트로의 경우 필수 입력해야 하며, 특수문자는 사용이 불가합니다. - customer?: object **고객 정보** - customerId?: string **구매자 고유 ID** - 스마트로의 경우 빌링키 발급 시 필수로 입력해야 합니다. - 20자 이하로만 입력 가능합니다. - bypass?: oneof object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - smartro\_v2?: object **스마트로에서 제공하는 파라미터 모음** - SkinColor?: string **UI 색상 스타일** - 미 설정시 기본으로 `RED`로 적용됩니다. - `RED`, `GREEN`, `BLUE`, `PURPLE`를 선택할 수 있습니다. - IsPwdPass?: string **결제 비밀번호 등록 Skip 여부** - 비밀번호 설정 미사용: `Y`, 비밀번호 설정 사용: `N` - 미 설정시 기본으로 `N`으로 적용됩니다. ### SDK 연동 유의사항 #### 사전 계약 아래 기능을 사용하시려면 스마트로에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답( ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다. - 간편결제 사용 - 면세 / 복합과세 사용 - 할부 사용 - 상점 부담 무이자 할부 사용 - 카드사 포인트 사용 - 에스크로 사용 - \[TBD] 해외 결제 사용 #### 카드 결제
할부 개월수 리스트 제어가 불가능합니다. 일반적으로 `card.installment.monthOption.availableMonthList` 파라미터를 사용하여 구매자에게 노출할 할부 개월수 리스트를 제어할 수 있으나 **스마트로의 경우 해당 기능을 지원하지 않습니다.** 추가로 상점 아이디에 무이자 할부 설정에 따라 무이자 정보가 자동 표기됩니다.
카드사 다이렉트 호출 시 할부 개월수를 고정해야합니다. 스마트로의 경우 **카드사 다이렉트 호출 파라미터와 고정 할부 개월수는 항상 같이 사용** 해야 합니다. 하나의 파라미터만 설정하는 경우 에러가 리턴되며 정상적으로 결제가 진행되지 않습니다.
카드사 포인트 사용 여부 파라미터로 제어가 불가능합니다. 일반적으로 `card.useCardPoint` 파라미터로 카드사 포인트 사용 여부를 설정할 수 있지만 **스마트로는 상점 아이디 설정에 따라 카드사 포인트 사용 여부가 결정**됩니다.
일부 카드 다이렉트 호출 시 윈도우 환경에서만 가능합니다. 스마트로의 경우 윈도우 OS에서만 전북 카드(code: `372`)와 카카오뱅크 카드(code: `090`)로 다이렉트 호출이 가능합니다.
#### 간편 결제
스마트로-네이버페이 결제 시 카드결제만 가능합니다. 스마트로를 통한 네이버페이를 다이렉트로 호출하여 결제하는 경우 등록된 카드로만 결제가 가능하고 네이버페이 포인트/머니 결제는 불가능합니다. 네이버페이 포인트/머니로 결제를 원하시면 결제창 호출 시 결제수단을 카드로 지정하여 호출한 뒤, 결제를 진행해야합니다.
#### 가상계좌 결제
현금영수증 파라미터 사용 시 다이렉트로 호출해야 합니다. 기본적으로 결제창을 통하여 현금성 결제수단(실시간 계좌이체, 가상계좌)으로 결제하는 경우 현금영수증을 발급할 수 있으며, 결제창 내에서 현금영수증 정보(현금영수증 발급 유형, 현금영수증 발행 식별 번호)를 입력할 수 있습니다. 스마트로의 경우 결제 요청 시 **`virtualAccount.cashReceiptType`와 `virtualAccount.customerIdentifier`를 이용하여 현금영수증 정보를 사전에 정보를 전달할** 수 있으며, 전달한 정보는 결제창에 자동 입력됩니다. 단, 이 파라미터를 이용하려면 스마트로 정책상 다이렉트로 호출해야 합니다. 예시코드 ```ts import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "VIRTUAL_ACCOUNT", virtualAccount: { accountExpiry: { dueDate: `2024-11-12T23:59:59+09:00`, // 입금기한은 미래시간만 가능합니다. }, cashReceiptType: `PERSONAL`, customerIdentifier: `01088325501`, bankCode: `KOOOKMIN_BANK`, }, }); } ```
#### 휴대폰 소액결제
`productType` 파라미터는 필수 입력해야 합니다. - 스마트로의 경우 **휴대폰 소액결제시 상품 유형을 구분 짓는 `productType` 파라미터가 필수**로 요구됩니다. - `productType`의 값은 `PRODUCT_TYPE_REAL` 또는 `PRODUCT_TYPE_DIGITAL`를 입력해야 합니다. - 상품 유형은 스마트로 상점아이디의 설정과 일치해야 합니다. 일치하지 않는 경우 호출한 결제창 내에 에러가 리턴되며, 결제가 불가능합니다.
#### 빌링키 발급
결제창 빌링키 발급 시 한국어만 지원됩니다. 스마트로의 경우 결제창 호출 시 한국어 또는 영어로 지원됩니다만 **빌링키 발급**시에는 한국어만 지원합니다.
휴대폰 본인인증 프로세스를 진행해야 빌링키 발급이 가능합니다. 스마트로의 경우 **빌링키 발급시 휴대폰 본인인증 프로세스**를 진행해야 합니다. 동일 고객에 한하여 휴대폰 본인인증은 최초 1회만 진행하고 있습니다. 따라서 `customerId` 파라미터에 고객을 식별할 수 있는 값을 넣어 사용해야 합니다. 단, 동일한 고객이더라도 `customerId`가 달라지는 경우 휴대폰 프로세스를 다시 진행해야 합니다.
#### 에스크로 결제
에스크로 결제시 카드사/가상계좌 다이렉트 호출 사용이 불가능합니다. 스마트로는 에스크로 결제시 카드사 다이렉트 호출 및 가상계좌 다이렉트 호출이 불가능합니다. 만약 에스크로 결제시 아래와 같이 다이렉트 호출을 할 경우 에러가 리턴되면서 결제창이 호출되지 않습니다. 예시코드 - V2 에스크로 + 카드사 다이렉트 호출 ```ts PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "CARD", totalAmount: 50000, isEscrow: true, // 에스크로 결제 card: { cardCompany: "BC_CARD", // 카드사 다이렉트 호출 installment: { monthOption: { fixedMonth: 5, }, }, }, }); ``` - V2 에스크로 + 가상계좌 다이렉트 호출 ```ts PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "VIRTUAL_ACCOUNT", virtualAccount: { accountExpiry: { dueDate: `2024-11-12T23:59:59+09:00`, // 입금기한은 미래시간만 가능합니다. }, }, totalAmount: 50000, isEscrow: true, // 에스크로 결제 virtualAccount: { bankCode: "SHINHAN_BANK", // 은행 다이렉트 호출 }, }); ```
에스크로 계좌이체 결제시 현금영수증 파라미터 사용이 불가능합니다. 에스크로 결제 시에는 `cashReceiptType`와 `customerIdentifier` 파라미터를 사용할 수 없습니다. 해당 파라미터를 전달하는 경우 에러가 리턴되면서 결제창이 호출되지 않습니다. 예시코드 - V2 에스크로 + 계좌이체 + 현금영수증 정보 전달 ```ts PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. totalAmount: 50000, payMethod: "TRANSFER", // 계좌이체 결제 isEscrow: true, // 에스크로 결제 transfer: { // 현금영수증 정보 전달 cashReceiptType: "CORPORATE", customerIdentifier: "1178178260", }, }); ```
#### 기타
서비스 제공기간(`offerPeriod`) 이용시 시작일(`from`)과 종료일(`to`)를 모두 입력해야 합니다. 결제창 내 서비스 제공 기간 노출을 원하는 경우 `offerPeriod`를 이용하여 제어할 수 있습니다. 해당 파라미터 이용시에는 `from` 및 `to` 파라미터를 모두 입력해야 결제창에 정상적으로 노출됩니다.
현금영수증 관련 파라미터 사용시 발급 유형( `cashReceiptType`)에 따라 발행 대상 식별 정보(`customerIdentifier`)를 올바르게 입력해야 합니다. `cashReceiptType: ANONYMOUS`일 때, `customerIdentifier`에 값을 입력하거나 `cashReceiptType: PERSONAL` 혹은 `cashReceiptType: CORPORATE`일 때, `customerIdentifier`에 값을 입력하지 않으면 에러가 리턴되면서 결제창이 호출되지 않습니다.
### SDK 결제 FAQ
\[테스트연동] 부분취소는 안되나요? 테스트 모드로 연동한 채널을 이용하여 결제한 체크카드 거래건의 경우 전액 취소만 가능하며 부분취소는 불가능합니다.
\[테스트연동] 국민카드/카카오뱅크카드 사용 시 결제가 자꾸 실패해요. 테스트 모드로 연동한 채널을 이용하는 경우 국민카드 또는 카카오뱅크로 결제가 불가능합니다. 다른 카드사의 카드로 테스트 해보시길 바랍니다.
\[테스트연동] 카카오페이/페이코 결제 시 결제가 안돼요 테스트 모드로 연동한 채널을 이용하여 카카오페이 또는 페이코 결제 시 삼성/현대/농협/신한 카드만 사용이 가능합니다. 이 외의 카드는 결제가 불가능합니다.
\[테스트연동] Kbank로 가상계좌 발급이 불가능해요 테스트 모드로 연동한 채널을 이용하여 가상계좌 발급 요청시 Kbank, 국민은행, 전북은행, 광주은행, 대구은행 등 일부 은행에서는 발급이 불가능합니다.
\[테스트연동] 카카오페이 결제 시 자동으로 취소가 되나요? 테스트 모드로 연동한 채널을 이용하여 카카오페이 결제 시 자동취소가 불가능합니다. 테스트 결제 건에 대해 직접 취소처리 하셔야 합니다. 취소는 포트원 콘솔 내 결제내역 혹은 결제 취소 API (POST /payments/{paymentId}/cancel)를 이용하여 취소할 수 있습니다.
### API 수기(키인)결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant`를 이용하여 결제 요청을 해야합니다. 스마트로의 경우 결제수단은 가상계좌 발급만 가능하며, 예시코드는 아래와 같습니다.
```ts // ... 수기(키인) 결제 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`, //입금기한은 미래시간만 가능합니다. }, option: `NOMAL`, 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 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - method: object **결제수단 정보** 스마트로의 경우 가상계좌만 지원합니다. - virtualAccount: object **가상계좌 결제 시 파라미터** - bank: string **발급 은행** - 은행코드는 ENUM으로 정의되어 있습니다. - [BANK ENUM 바로가기](https://developers.portone.io/api/rest-v2/payment#Bank) - expiry: object **입금 만료 기한** - validHours?: integer **유효 시간** - dueDate?: string **만료 시점** 시간은 ISO8601 형식으로 입력해야 합니다. - option: object **가상계좌 발급 방식** - type: string **가상계좌 발급 유형** 발급 유형은 ENUM으로 정의되어 있습니다. - 회전식 가상계좌 : `NORMAL` - 고정식 가상계좌 : `FIXED` - 회전식 가상계좌는 일반적으로 사용되는 방식이며 PG사에서 직접 채번한 가상계좌번호를 사용합니다. - fixed?: object **고정식 가상계좌 발급 유형** - pgAccountId?: string **고정식 가상계좌 ID** - 고객사가 가상계좌번호를 직접 관리하지 않고 PG사가 pgAccountId에 매핑되는 가상계좌번호를 내려주는 방식입니다. 동일한 pgAccountId로 가상계좌 발급 요청시에는 항상 같은 가상계좌번호가 내려옵니다. - 스마트로의 경우 해당 방식만 지원합니다. - cashReceipt?: object **현금영수증 정보** - type?: string **발급 유형** 발급 유형은 ENUM으로 정의되어 있습니다. - 소득공제용 : `PERSONAL` - 지출증빙용 : `CORPORATE` - 미발행 : `NO_RECEIPT` - customerIdentityNumber?: string **현금영수증 식별 번호** - 소득공제인 경우 주민등록번호 혹은 휴대폰 번호를 입력해야 합니다. - 지출증빈인 경우 사업자등록번호를 입력해야 합니다. - remitteeName?: string **예금주명** - customer?: object **고객 정보** - name?: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** - productCount?: integer **상품 개수** ### API 빌링키 발급 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. 예시코드
```ts 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 **고객 정보** - customerId?: string **구매자 고유 ID** - 스마트로의 경우 빌링키 발급 시 필수로 입력해야 합니다. - 20자 이하로만 입력 가능합니다. ### API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제를 하기 위해 `POST /payments/${PAYMENT_ID_HERE}/billing-key`를 이용하여 결제를 요청합니다. 예시코드
```ts 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 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - customer?: object **고객 정보** - name: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber: string **구매자 연락처** - email: string **구매자 이메일** - productCount?: integer **상품 개수** ### API 빌링키 예약/반복 결제 예약 결제를 하기위해서는 `POST /payments/${PAYMENT_ID_HERE}/schedule` 를 이용하여 결제를 예약합니다. 예시코드
```ts 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 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - timeToPay: string **결제 예정 시점** # https://developers.portone.io/opi/ko/integration/pg/v2/tosspay-v2 --- title: 토스페이 description: 토스페이 간편결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/tosspay-v2/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 간편결제 : `EASY_PAY` ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 토스페이 채널 사용을 명시해주세요. 토스페이 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="SDK 결제 요청" 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${Math.random().toString(36).slice(2)}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", payMethod: "EASY_PAY", }); } ``` ### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - paymentId: string **고객사 주문 고유 번호** 고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** 주문명으로 고객사에서 자유롭게 입력합니다. - totalAmount: number **결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - payMethod: string **결제수단 구분코드** 결제 호출 시 결제수단을 지정할 때 사용됩니다. 간편 결제의 경우 `EASY_PAY`로 입력해야 합니다. - bypass?: object **PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음** - tosspay\_v2?: object **토스페이에서 제공하는 파라미터** - expiredTime?: string **결제 만료 기한** `yyyy-MM-dd HH:mm:ss` 의 형식으로 입력해야 합니다. 입력하지 않을 경우, 기본값인 15분으로 설정됩니다. 최대 60분까지 설정할 수 있습니다. - cashReceiptTradeOption?: string **현금영수증 발급 대상 타입** 전달하지 않을경우, 기본값은 GENERAL 입니다. 일반 (default) : `GENERAL` / 문화비 : `CULTURE` / 교통비 : `PUBLIC_TP` ### 유의사항 #### 공통
매출전표 지원 안내 카드결제인 경우에만 매출전표가 제공됩니다.
현금영수증 발급 안내 토스페이의 경우, 현금영수증 발급에 대한 정보를 따로 입력받지 않고 앱에 저장된 식별정보로 현금영수증이 발급됩니다. 이 때문에 현금영수증 타입을 personal, corporate로 지정하더라도 실제로는 다른 타입의 현금영수증이 발급될 수 있습니다.
## SDK 빌링키 발급 요청하기 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 토스페이 채널 사용을 명시해주세요. 토스페이 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="SDK 빌링키 발급 요청" 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: "EASY_PAY", issueId: "test-issueId", issueName: "test-issueName", customer: { customerId: "uniqueCustomerId", }, redirectUrl: "http://localhost", }); } ``` ### 주요 파라미터 - storeId: string **상점 아이디** 포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다. - channelKey: string **채널 키** 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - billingKeyMethod: string **빌링키 발급수단** 토스페이는 빌링키 발급 수단으로 간편결제(토스페이)만을 지원하므로 해당 파라미터는 `EASY_PAY`로 고정해야 합니다. - customer?: object **고객 정보** - customerId?: string **구매자 고유 ID** - 토스페이의 경우 구매자 ID를 필수로 입력해야 합니다. - redirectUrl: string **빌링키 발급 후 이동할 URL** 모바일 환경의 경우, 필수 입력입니다. ### 유의사항
빌링키 발급 웹훅 연동 안내 토스페이 빌링키 발급시 빌링키 발급 웹훅을 반드시 연동하는 것이 좋습니다. 콘솔에서 웹훅 URL을 설정하거나, `requestIssueBillingKey` 함수 파라미터 중 noticeUrls를 입력하여 웹훅을 전달받을 수 있습니다. 만약 웹훅을 연동하지 않은 경우, 엔드유저가 빌링키 발급 도중 팝업이나 브라우저를 끄는 행위등으로 인해 고객사의 SDK 콜백 코드가 실행되지 않아 실제로 빌링키가 발급됐으나 발급정보가 누락될 수 있습니다. [웹훅 연동 가이드 바로가기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2)
빌링키 업데이트 웹훅 연동 안내 빌링키가 발급된후에 토스페이앱에서 엔드유저가 직접 빌링키에 연결된 결제수단을 변경할 수 있습니다. 콘솔에 웹훅 URL을 설정해 둔 경우라면 이 때 빌링키 업데이트 웹훅이 전송됩니다. 만약 빌링키에 연결된 결제수단을 서비스 내부적으로 사용하고 있다면, 빌링키 업데이트 웹훅을 연동하시거나 정보를 표시하기 전 포트원의 빌링키 정보 조회 API를 호출하여 데이터를 최신화하기를 권장합니다. [웹훅 연동 가이드 바로가기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2)
## API 빌링키 단건 결제 요청하기 발급된 빌링키로 단건 결제를 진행하려면 `POST /payments/${PAYMENT_ID_HERE}/billing-key` API를 이용하여 결제를 요청하실 수 있습니다. 토스페이 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="API 빌링키 단건 결제" const response = await axios({ url: `https://api.portone.io/payments/${encodeURIComponent(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: 50000, taxFree: 3000, }, currency: "KRW", }, }); ``` ### 주요 파라미터 - paymentId: string **결제 주문 번호** - 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다. - URL path에 포함하여 요청해야 합니다. - billingKey: string **빌링키 결제에 사용할 빌링키** - orderName: string **주문명** - amount: object **결제 금액** - total: number **총 결제 금액** 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - customer?: object **고객 정보** - name?: object **고객 이름** - full?: string **한 줄 이름 형식 (ex. 김포트)** - separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** ## API 빌링키 예약/반복 결제 요청하기 예약 결제를 진행하려면 `POST /payments/${PAYMENT_ID_HERE}/schedule` API를 이용하여 결제를 예약하실 수 있습니다. 토스페이 기준으로 작성한 예시 코드는 아래와 같습니다. ```typescript title="API 예약/반복 결제" 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, taxFree: 3000, }, 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. 김포트)** - separated?: object **분리된 이름** - first?: string **이름** - last?: string **성** - phoneNumber?: string **구매자 연락처** - email?: string **구매자 이메일** # https://developers.portone.io/opi/ko/integration/pg/v2/tosspayments --- title: 토스페이먼츠 description: 토스페이먼츠 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/newtoss/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. - V2 결제 모듈을 사용하시려면 토스페이먼츠(신모듈)로 연동하셔야 합니다. (관련 이미지 첨부) ## 가능한 결제수단 - **일반 결제** - `payMethod`파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다. - 신용카드 : `CARD` - 퀵계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 휴대폰 소액결제 : `MOBILE` - 간편 결제 : `EASY_PAY` - 상품권 결제 : `GIFT_CERTIFICATE` - **빌링키 발급** - `billingKeyMethod`(빌링키 발급) 파라미터를 `CARD`로 설정해야 합니다. ## SDK 결제 및 빌링키 발급 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출하고, 빌링키 발급 시에는 `requestIssueBillingKey` 함수를 호출해야합니다. `channelKey` 파라미터에 결제 채널 연동 시 입력한 채널 키를 지정하여 토스페이먼츠 연동임을 명시해주세요. 만약 `channelKey`가 입력되지 않는 경우 `pgProvider` 파라미터에 입력된 값에 따라 결제 및 빌링키 발급 창이 호출됩니다. 토스페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts import * as PortOne from "@portone/browser-sdk/v2"; function requestPayment() { PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. paymentId: `payment-{${crypto.randomUUID()}`, orderName: "나이키 와플 트레이너 2 SD", totalAmount: 1000, currency: "CURRENCY_KRW", channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. payMethod: "CARD", }); } ```
```ts 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", }); } ```
## API 빌링키 발급 및 예약/반복 결제 요청하기 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. 이후 발급된 빌링키로 예약/반복 결제를 하기위해 `POST /payments/${PAYMENT_ID_HERE}/schedules` 를 이용하여 결제를 예약합니다.
```ts // ... 빌링키 발급 const issueResponse = await axios({ url: `https://api.portone.io/billing-keys`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { channelKey, customer: { id: customerId, }, method: { card: { credential: { number: cardNumber, expiryYear, expiryMonth, birthOrBusinessRegistrationNumber, passwordTwoDigits, }, }, }, }, }); ```
```ts async function schedulePayment() { // 포트원 결제 예약 API 호출 const response = await axios({ url: `https://api.portone.io/payments/${encodeURIComponent(PAYMENT_ID_HERE)}/schedules`, method: "post", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, data: { payment: { billingKey: BILLING_KEY_HERE, orderName: "월간 이용권 정기결제", customer: { id: CUSTOMER_ID_HERE, // 고객 정보가 필요한 경우 API 명세에 따라 추가해주세요. }, amount: { total: 8900, }, currency: "KRW", }, timeToPay: "2023-08-24T14:15:22Z", // 결제를 시도할 시각 }, }); // 결제 예약 이후 로직을 구성해주세요. } ```
## 주요 파라미터 - storeId: string 고객사의 상점을 식별하는 고유한 값입니다. - paymentId: string 고객사가 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. - orderName: string 주문명으로 고객사에서 자유롭게 입력합니다. - channelKey: string 콘솔의 결제 연동 메뉴에 표시되는 채널 키를 입력해야 합니다. - totalAmount: number 결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다. - currency: string 결제통화로 원화 결제를 원할 시 `KRW`로 입력해야 합니다. - payMethod: string 결제수단을 구분하는 코드로 원하는 결제수단 값을 입력해야 합니다. ## 유의할 파라미터 - SDK ### 결제/빌링키 발급 공통 - `windowType` - 토스페이먼츠의 경우 PC는 `IFRAME`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다. - `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다. ```json { "pc": "IFRAME", "mobile": "REDIRECTION" } ``` - `locale` - 토스페이먼츠의 경우 `KO_KR`만 지원합니다. 이외의 값을 넣어도 무시됩니다. - `redirectUrl` - 모바일 환경에서 결제 요청 시 `REDIRECTION` 타입이므로, 필수로 입력해야 합니다. ### 결제 (`requestPayment`) - `easyPay` - `easyPayProvider` - 간편결제 결제 요청 시, 사용하고자 하는 간편 결제사에 따라 아래 목록을 참고하여 `easyPayProvider` 파라미터를 입력해야 합니다. - 페이코 : `PAYCO` - 삼성페이 : `SAMSUNGPAY` - SSG페이 : `SSGPAY` - 카카오페이 : `KAKAOPAY` - 네이버페이 : `NAVERPAY` - L페이 : `LPAY` - 토스페이 : `TOSSPAY` - 애플페이 : `APPLEPAY` - `giftCertificate` - `giftCertificateType` - 상품권 결제 요청 시, 사용하고자 하는 상품권 종류에 따라 아래 목록을 참고하여 `giftCertificateType` 파라미터를 입력해야 합니다. - 도서문화상품권 : `BOOKNLIFE` - 스마트문상 ((구)게임문화상품권) : `SMART_MUNSANG` - 컬쳐랜드 문화상품권 : `CULTURELAND` - `paymentId` - 토스페이먼츠를 사용하는 경우 영문 대소문자, 숫자, 특수문자(-,\_)만 허용되며, 6자 이상 64자 이하만 가능합니다. - `currency` - 토스페이먼츠의 경우 원화 결제만 지원하므로 `KRW` 이외의 값을 넣으면 에러를 리턴합니다. - `isCulturalExpense` - 문화비(도서, 공연, 박물관 등) 지출 여부를 구분하고자 할 때 파라미터를 입력하여 사용할 수 있습니다. - `card.installment.monthOption.fixedMonth` - 토스페이먼츠의 경우 현대카드는 1만원, 그 외는 5만원 이상 결제에 대해서만 적용됩니다. - `bypass` - 토스페이먼츠에서는 아래의 파라미터를 지원합니다. - `tosspayments` - `discountCode` - 토스페이먼츠와 고객사 간의 계약에 따라 프로모션을 적용할 수 있습니다. ```json { "tosspayments": { "discountCode": "즉시 할인 코드(카드사 고유 번호)" } } ``` - `useInternationalCardOnly` - 해외 카드로만 결제가 가능하도록 설정할 수 있습니다. ```json { "tosspayments": { "useInternationalCardOnly": true } } ``` ### 빌링키 발급 (`requestIssueBillingKey`) - 없음 ## 연동 유의사항 ### 토스페이먼츠와 사전 계약이 필요한 경우 아래의 기능을 사용하려면 사전 신청을 통해 토스페이먼츠와 계약을 완료해야 합니다. 계약을 하지 않은 경우에 해당 기능을 이용하여 결제 시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와 다른 응답을 받을 수 있습니다. (ex. 에스크로 결제를 요청하여 결제를 진행하였으나 비-에스크로 결제 응답을 받는 경우) - 휴대폰 소액결제 - 간편결제 - 상품권 결제 - 면세 / 복합과세 - 신용카드 할부 - 상점 분담 무이자 할부 - 카드사 포인트 사용 - 에스크로 ### 카드 결제 - `card.useAppCardOnly` 파라미터는 일부 카드사에 대해서만 적용 가능합니다. - 지원 가능한 카드 : 국민, 농협, 롯데, 삼성, 신한, 현대, 우리, 하나 - 지원 불가능한 카드 : 씨티 - `card.installment.monthOption.availableMonthList` 파라미터의 경우 다른 PG사들과 다르게 동작합니다. - 해당 파라미터로 결제창에 랜더링 될 할부 리스트를 제어할 수 있습니다. 다른 PG사의 경우 전달한 값만 랜더링 되지만, 토스페이먼츠의 경우에는 토스페이먼츠 자체 정책에 따라 **일시불 \~ 전달한 값 중 최대값까지 모두** 랜더링됩니다.
파라미터 사용 예시 - 예1. 일시불만 허용하고 싶은 경우 (토스페이먼츠 가능) ```json { "card": { "installment": { "monthOption": { "availableMonthList": [0] } } } } ``` - 예2. 5개월만 허용하고 싶은 경우 (토스페이먼츠 불가능) ```json { "card": { "installment": { "monthOption": { "availableMonthList": [5] } } } } ``` - 예3. 다른 PG사 호출 시 일시불\~5개월까지 허용하고 싶은 경우 ```json { "card": { "installment": { "monthOption": { "availableMonthList": [0, 1, 2, 3, 4, 5] } } } } ``` - 예4. 토스페이먼츠 호출 시 일시불\~5개월까지 허용하고 싶은 경우 ```json { "card": { "installment": { "monthOption": { "availableMonthList": [0, 1, 2, 3, 4, 5] // [5], [3,5] 로 입력해도 됨 } } } } ``` - 예5. 토스페이먼츠 호출 시 3개월과 5개월까지 허용하고 싶은 경우 -> 불가능 ```json { "card": { "installment": { "monthOption": { "availableMonthList": [0, 1, 2, 3, 4, 5] // [5], [3,5] 로 입력해도 됨 } } } } ``` - 예6. 다른 PG사 호출 시 3개월과 5개월까지 허용하고 싶은 경우 ```json { "card": { "installment": { "monthOption": { "availableMonthList": [3, 5] } } } } ```
- 무이자 할부가 적용 되어도 ISP 계열 카드로 결제시에는 `무이자` 표기가 되지 않습니다. 고객사은 토스페이먼츠와 사전 계약 또는 카드사 정책에 따라 무이자 할부 기능을 사용할 수 있습니다. 이에 따라 결제창 내에서 각 카드사별 최대 무이자 할부 개월 수에 따라 할부 개월 수 옆에 `무이자` 또는 `무`라고 표기됩니다.
예시 - 예1. 삼성카드 - 최대 3개월 무이자 할부 적용 -> 3개월까지 `무` 표기 (관련 이미지 첨부) - 예2. BC카드 - 최대 12개월 무이자 할부 적용 -> 표기되지 않음 -> 실제 결제 승인 시 무이자 할부 적용 됩니다. 이는 ISP 계열 카드사 결제 시 사용되는 페이북 앱 특성에 따른 것으로 실제 결제 승인시에는 정상적으로 무이자 할부가 적용됩니다. (관련 이미지 첨부)
- ISP 계열 카드 및 간편결제의 경우 해당 앱 내에서 할부 기간 선택이 가능합니다. - 간편결제의 경우 모바일 웹에서 결제 요청 시 토스페이먼츠 결제창 내에서의 할부기간 선택은 불가능하며, 간편결제 앱 내에서 할부 선택이 가능합니다. - ISP 계열 카드의 경우 PC 웹에서 결제 요청 시 토스페이먼츠 결제창 내에서의 할부기간 선택은 불가능하며, ISP 앱 내에서 할부 선택이 가능합니다. - 카카오페이의 경우 카카오페이 정책 상 13개월 이상 할부 결제를 지원하지 않기 때문에, 카카오페이로 결제 요청 시에는 최대 12개월까지만 할부 결제가 가능합니다. ### 가상계좌 - 토스페이먼츠를 통한 가상계좌는 경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, DGB대구은행, 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 하나은행에서 발급받을 수 있습니다. ### 카드사 다이렉트 호출 - 토스페이먼츠의 경우 카드사 다이렉트 (`card.cardCompany`) 호출 시 할부 결제를 하려면 고정 할부 개월수 (`card.installment.monthOption.fixedMonth`)를 입력한 후 요청해야합니다. 만약, `fixedMonth` 값을 전달하지 않는 경우에는 무조건 **일시불**로 결제가 됩니다. - 카드사 다이렉트 호출 기능을 사용하고자 한다면 자체적으로 구매자가 할부 개월 수를 선택할 수 있는 UI/UX를 구현한 뒤 결제 요청 시 해당 값을 함께 요청해주셔야 합니다.
예시 - 예1. 현대카드 다이렉트 호출 후 결제 시 일시불로 결제됩니다. ```json { // ... 기타 파라미터 "card": { "cardCompany": "HYUNDAI_CARD" } } ``` - 예2. 삼성카드 다이렉트 호출 후 결제 시 5개월 할부로 결제 됩니다. ```json { // ... 기타 파라미터 "card": { "cardCompany": "SAMSUNG_CARD", "installment": { "monthOption": { "fixedMonth": 5 } } } } ```
- 고정 할부 개월수 (`card.installment.monthOption.fixedMonth`)를 입력한 후 결제 요청 시 앱카드 내에서 확인이 가능합니다. 결제창 혹은 앱카드 내에서 개월수가 확인되지 않더라도 실제 결제 승인 시 `fixedMonth`에 요청한 값으로 승인 됩니다.
예시 - 예1. BD카드 다이렉트 호출 후 결제 시 5개월 할부로 결제 됩니다. ```json { // ... 기타 파라미터 "card": { "cardCompany": "BC_CARD", "installment": { "monthOption": { "fixedMonth": 5 } } } } ``` (관련 이미지 첨부)
- 페이북을 통한 ISP 계열 카드 결제 시 실물 카드 번호와 다를 수 있습니다. 토스페이먼츠가 실제 카드 번호와 다른 카드 번호를 전달하고 있어 결제 내역 단건 조회 (POST `/payments/{payment_id}`) 시 응답되는 `payment_method_detail.card.detail.bin` 정보가 정확하지 않을 수 있습니다. - 사파리 브라우저에서는 페이북 결제 시 팝업 호출 이슈가 있어 ISP 계열 카드 결제가 불가능합니다. 이는 토스페이먼츠 결제창에서 페이북으로 넘어가는 과정에서 발생하는 이슈로 포트원과는 무관합니다. ### 간편결제 - 테스트MID로 간편결제 호출 시 테스트가 원활하지 않을 수 있습니다. 간편결제의 경우 사전에 토스페이먼츠와 사전계약이 필요하며, ` [PAY_PROCESS_ABORTED] Toss Payments와 계약된 결제수단(NAVERPAY)이 아닙니다.` 와 같은 에러 발생 시 고객사의 실 상점아이디로 토스페이먼츠와 계약 후 사용이 가능합니다. - 일부 간편결제 사 (ex. 토스페이, L페이 등)의 경우 해당 간편결제사 정책에 따라 고정 할부 개월수 파라미터를 입력해도 해당 할부 개월 수와 일시불이 동시에 표기되는 경우가 있습니다. ### 기타 - 상품권 결제는 부분취소가 불가능합니다. - 테스트 결제 건은 매출 전표 확인이 불가능합니다. - 간편결제를 통해 카드 외의 결제수단으로 결제한 경우 매출 전표 확인이 불가능합니다. - 토스페이먼츠를 통한 SSG페이 결제 시 토스페이먼츠 결제창에서 휴대폰 번호가 선택사항이어서 미입력시에도 다음단계로 진입이 가능합니다. 이 때, SSG페이의 경우 입력받은 휴대폰 전화번호로 앱푸시 알람이 가도록 로직이 구현되어있기 때문에 사용자가 앱푸시 알람을 받지 못할 수 있습니다. 휴대폰 번호 입력이 필수로 되어있지 않는 것은 토스페이먼츠의 정책으로 포트원과 무관합니다. - API를 통한 현금영수증 (POST `/payments/cash-receipts`) 발급 시 현금영수증 유형(type) 과 현금영수증 발급 번호(identifier)의 유효성을 검증하지 않고 발급 요청한 값대로 승인되오니 API 이용 시 현금영수증 정보를 정확하게 입력해야 합니다.
예시 - 예1. 현금영수증 발급 유형이 지출 증빙일 때, 현금영수증 발급 번호에 휴대폰 번호를 입력하는 경우 정상 처리됩니다.
- 삼성페이를 통한 결제 도중 세션값이 만료된 경우 안내 메세지가 잘려서 보일 수 있습니다. 이는 토스페이먼츠에서 발생하는 이슈로 포트원과 무관합니다.
예시 (관련 이미지 첨부)
- 사파리 또는 파이어폭스 브라우저의 경우 팝업 차단 해제가 설정되어있지 않는 경우 페이북, 가상계좌 발급, 휴대폰 소액결제 등 결제가 정상적으로 진행되지 않을 수 있으니, 팝업을 해제하고 사용할 수 있도록 안내가 필요합니다. - IE 브라우저에서 페이코 결제 시 결제창이 잘릴 수 있습니다. 이는 토스페이먼츠에서 발생하는 이슈로 포트원과 무관합니다. - IE 브라우저 결제 중단 시 일부 메세지가 인코딩 된 메세지로 전달될 수 있으며, 이는 토스페이먼츠에서 발생하는 이슈로 포트원과 무관합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/triple-a --- title: Triple-A description: Triple-A 결제 연동 방법을 안내합니다. targetVersions: - v2 --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키를 지정하여 Triple-A 채널 사용을 명시해주세요.
```javascript import * as PortOne from "@portone/browser-sdk/v2"; PortOne.requestPayment({ storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요. channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. paymentId: `payment${crypto.randomUUID()}`, orderName: "PortOne Purchase", totalAmount: 100, // 1 USD currency: "USD", customer: { fullName: "PortOne", email: "test@example.com", }, }); ```
### 사용 가능 파라미터 - storeId: string **상점 아이디** - paymentId: string **고객사 주문 고유 번호** - 고객사가 채번하는 주문 고유 번호입니다. - 이미 승인된 `paymentId`로 결제를 시도하는 경우 에러가 발생합니다. - orderName: string **주문명** Triple-A로 전달되지 않으며 포트원 결제 내역 확인 시에만 사용됩니다. - channelKey: string **채널 키** Triple-A 채널의 채널키를 입력합니다. - totalAmount: number **결제 금액** 결제 금액을 정수로 나타냅니다. 해외 통화의 경우 통화의 최소 단위(minor unit)를 기준으로 합니다. 예를 들어, USD의 최소 단위는 센트(0.01 USD)이므로, 6 USD의 경우 100배하여 600으로 입력합니다. 최소 단위는 [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)에 표준화된 것을 기준으로 합니다. - KRW: 1배 - USD: 100배 - JPY: 1배 - currency: string **결제 통화 코드** - ISO 4217 통화 코드 - [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) - Triple-A에서 사용 가능한 통화 목록은 [Triple-A 공식 문서](https://developers.triple-a.io/docs/triplea-api-doc/8974dfffa9418-presentment-currencies-for-crypto-payments)에서 확인할 수 있습니다. - locale?: Locale **결제창 언어** - `EN_US`: 영어 - `ZH_CN`: 중국어 (중국 본토) - `JA_JP`: 일본어 - `RU_RU`: 러시아어 - `VI_VN`: 베트남어 - `ID_ID`: 인도네시아어 - `FR_FR`: 프랑스어 - `NL_NL`: 네덜란드어 - `ES_ES`: 스페인어 - `PT_PT`: 포르투갈어 - `DE_DE`: 독일어 - `IT_IT`: 이탈리아어 - `PL_PL`: 폴란드어 - `AR_001`: 현대 표준 아랍어 - customer?: object **고객 정보** - customerId?: string **구매자 ID** 구매자를 식별하는 고유한 값으로, 값이 없으면 포트원에서 자동으로 생성합니다. - fullName?: string **구매자 전체 이름** `fullName`이 없고 `firstName`과 `lastName`이 있는 경우 `${lastName} ${firstName}`이 대신 사용됩니다. - firstName?: string **구매자 이름** `firstName`을 입력하는 경우 `lastName`도 필수로 입력해야 합니다. `fullName`이 없고, `firstName`과 `lastName`이 존재하는 경우 `{firstName} {lastName}`으로 저장됩니다. - lastName?: string **구매자 성** `lastName`을 입력하는 경우 `firstName`도 필수로 입력해야 합니다. - phoneNumber?: string **구매자 휴대전화 번호** `+6591234567`과 같이 `+(국가코드)`로 시작하는 [E.164](https://www.itu.int/rec/T-REC-E.164/) 형식의 전화번호를 입력합니다. - email?: string **구매자 이메일 주소** - products?: object\[] **구매 상품 정보** 입력 시 결제창에 상품 정보가 표시됩니다. - id: string **상품 ID** - name: string **상품명** - amount: number **상품 단위 가격** 상품의 단위당 가격을 정수로 나타냅니다. 해외 통화의 경우 통화의 최소 단위(minor unit)를 기준으로 합니다. 예를 들어, USD의 최소 단위는 센트(0.01 USD)이므로, 6 USD의 경우 100배하여 600으로 입력합니다. 최소 단위는 [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)에 표준화된 것을 기준으로 합니다. - KRW: 1배 - USD: 100배 - JPY: 1배 - quantity: number **상품 수량** - bypass?: oneof object - triple\_a?: object **Triple-A 특수 파라미터** - payer\_poi?: string **결제자 신원 증명 정보** 신분증, 여권 등 결제자의 신원을 증명할 수 있는 자료의 URL을 입력합니다. SGD 1500 이상의 결제 등 결제자 신원 조회가 필요한 경우에, `payer_poi`를 입력하면 별도의 신원 요청 과정을 거치지 않고 결제가 진행됩니다. - shipping\_cost?: number **배송비** 결제창에 표시할 배송비를 정수로 나타냅니다. `products`가 지정된 경우에만 사용할 수 있습니다. 해외 통화의 경우 통화의 최소 단위(minor unit)를 기준으로 합니다. 예를 들어, USD의 최소 단위는 센트(0.01 USD)이므로, 6 USD의 경우 100배하여 600으로 입력합니다. 최소 단위는 [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)에 표준화된 것을 기준으로 합니다. - KRW: 1배 - USD: 100배 - JPY: 1배 - shipping\_discount?: number **배송비 할인 금액** 결제창에 표시할 배송비 할인 금액을 정수로 나타냅니다. `products`가 지정된 경우에만 사용할 수 있습니다. - tax\_cost?: number **세금** 결제창에 표시할 세금을 정수로 나타냅니다. `products`가 지정된 경우에만 사용할 수 있습니다. ## API 결제 취소 요청하기 암호화폐 결제의 경우 결제 취소를 위해서는 환불받을 지갑 주소를 입력받아야 합니다. API로 취소 요청 시, 구매자의 이메일 주소를 전달하면 해당 메일을 통해 지갑 주소 입력 및 환불 절차가 진행됩니다. 결제 취소 요청을 구매자가 확인하고 지갑 주소를 입력하는 시점에 환불 금액이 확정됩니다. 환불 금액은 결제 요청 금액을 환불 시점에 암호화폐로 환산한 금액입니다. 환불 금액이 확정된 이후 입력한 지갑 주소로 환불이 진행됩니다.
```ts const response = await fetch( `https://api.portone.io/payments/${paymentId}/cancel`, { method: "POST", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}`, "Content-Type": "application/json", }, body: JSON.stringify({ reason: "단순 변심 전체 취소", refundEmail: "buyer@example.com", }), }, ); const { cancellation: { id }, } = await response.json(); // id: 취소 요청 아이디 ```
### 사용 가능 파라미터 - paymentId: string **고객사 주문 고유 번호** - 결제 요청 시에 사용한 `paymentId`를 입력합니다. - storeId?: string **상점 아이디** 하위 상점의 결제를 취소할 경우 필수로 입력합니다. - amount?: number 취소 총 금액 값을 입력하지 않으면 전액 취소됩니다. - currentCancellableAmount?: number **결제 건의 취소 가능 잔액** 본 취소 요청 이전의 취소 가능 잔액으로써, 값을 입력하면 잔액이 일치하는 경우에만 취소가 진행됩니다. 값을 입력하지 않으면 별도의 검증 처리를 수행하지 않습니다. - refundEmail: string **환불 이메일** Triple-A 결제 환불에 필요합니다. 해당 이메일로 환불 안내가 발송됩니다. - reason: string **취소 사유** - skipWebhook?: boolean **웹훅 생략 여부** 취소가 성공했을 때 웹훅을 전송하지 않으려면 `true`로 설정합니다. ## API 결제 취소 요청 취소 결제 취소를 요청했을 때, 구매자가 아직 지갑 주소를 입력하지 않았다면 취소 요청을 취소할 수 있습니다. 결제 취소 요청 결과로 획득한 `cancellation.id` 값을 사용하여 요청합니다.
```ts const response = await fetch( `https://api.portone.io/payments/${paymentId}/cancellations/${cancellationId}/stop`, { method: "POST", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, }, ); ```
### 사용 가능 파라미터 - paymentId: string **고객사 주문 고유 번호** - 결제 요청 시에 사용한 `paymentId`를 입력합니다. - cancellationId: string **취소 요청 아이디** - storeId?: string **상점 아이디** 하위 상점의 취소 요청인 경우 필수로 입력합니다. # https://developers.portone.io/opi/ko/integration/pg/v2/welcome --- title: 웰컴페이먼츠 description: 웰컴페이먼츠 결제 연동 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/pg/v1/welcome/readme --- ## 채널 설정하기 - [결제대행사 채널 설정하기](https://developers.portone.io/opi/ko/integration/ready/readme#3-결제대행사-채널-설정하기)의 내용을 참고하여 PG 설정을 진행합니다. ## 사전 계약 안내 아래 기능을 사용하시려면 웰컴페이먼츠에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다. - 간편결제 사용 - 면세 / 복합과세 / 지정금액 방식 사용 - 할부 사용 - 상점 부담 무이자 할부 사용 - 카드사 포인트 사용 - 에스크로 사용 - 휴대폰 실물 / 컨텐츠 사용 - 휴대폰 빌링키 발급과 동시에 결제 실물 / 컨텐츠 사용 ## 가능한 결제 수단 - **결제창 일반 결제** `payMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드 : `CARD` - 계좌이체 : `TRANSFER` - 가상계좌 : `VIRTUAL_ACCOUNT` - 상품권 : `GIFT_CERTIFICATE` - 휴대폰 소액 결제 : `MOBILE` - 간편결제 : `EASY_PAY` - **결제창 빌링키 발급** 카드 결제는 `requestIssueBillingKey` 함수, 휴대폰 결제는 `requestIssueBillingKeyAndPay` 함수를 이용합니다. `requestIssueBillingKeyAndPay` 함수를 이용할 때에는 빌링키 발급과 동시에 결제가 일어납니다. `billingKeyMethod` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `CARD` - 휴대폰: `MOBILE` - **API 수기(키인) 결제** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 - 가상계좌: `virtualAccount` 로 설정하여 가상계좌 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/payment#post%20%2Fpayments%2F%7BpaymentId%7D%2Finstant) 를 참고해주시기 바랍니다. - **API 빌링키 발급** `method` 파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다. - 카드: `card` 로 설졍하여 카드 관련 파라미터 입력 자세한 파라미터 구성은 [REST API Docs](https://developers.portone.io/api/rest-v2/billingKey#post%20%2Fbilling-keys)를 참고해주시기 바랍니다. ## SDK 결제 요청하기 결제 요청 시에는 `requestPayment` 함수를 호출해야 합니다. `channelKey`파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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 예시 코드** ```json { "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) | |below1000 |1,000원 미만 결제 허용 여부
- 기본값: 허용하지 않음 | |paypopup |안심클릭을 팝업 형태로 렌더링 시킬지 여부
- 기본값: 레이어 | |onlyeasypaycode(간편 결제 리스트)|카드 결제창 내 렌더링 될 간편 결제 리스트
예) 카카오페이, 엘페이, 페이코만 렌더링 → ”kakaopay:lpay:payco” 전달
- 카카오페이: `kakaopay`
- 엘페이: `lpay`
- 페이코: `payco`
- 토스페이: `tosspay`
- 네이버페이: `npay`| |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 : 수정 가능(기본)
| ```json { "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://) 호출 ### 유의사항 #### 공통
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 결제와 모바일 결제에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 PC 결제에서는 필수이지만, 모바일 결제에서는 선택입니다. - `customer.fullName` 혹은 `customer.firstName + customer.lastName` - `customer.phoneNumber` - `customer.email`
`paymentId` 에는 ASCII 문자만 허용됩니다. `paymentId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
지원되는 결제창 언어 SDK를 통한 결제 요청 파라미터에는 결제창 언어를 지정할 수 있는 `locale` 파라미터가 존재합니다. PC 결제의 경우 `KO_KR`, `EN_US`, `ZH_CN`을 지원하며, 모바일 결제의 경우 `KO_KR`, `EN_US`만을 지원합니다.
지원되는 결제 통화 SDK를 통한 결제 요청 파라미터에는 결제 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. 웰컴페이먼츠의 경우 `KRW`만을 지원합니다.
부가세, 면세금액 직접 지정을 위해서는 별도 계약이 필요합니다. SDK를 통한 결제 요청 파라미터에는 부가세를 지정할 수 있는 `vat` 파라미터와 면세 금액을 지정할 수 있는 `taxFreeAmount` 파라미터가 존재합니다. 웰컴페이먼츠의 경우 부가세 및 면세금액을 직접 지정하기 위해서는 별도 계약이 필요합니다. 별도 계약이 되지 않은 상태에서 `vat`와 `taxFreeAmount`에 값을 지정해 결제를 요청하면 요청한 내용과 다른 금액으로 실결제가 발생할 수 있습니다.
웰컴페이먼츠에서 지원하는 현금영수증 발급 유형 현금영수증은 현금성 거래인 실시간 계좌이체 및 가상계좌 발급 시 사용이 가능합니다. 웰컴페이먼츠의 경우 현금영수증 발급 유형을 `CORPORATE` 혹은 `PERSONAL` 등 파라미터로 제어할 수 없습니다. 어떤 유형의 현금영수증을 발행할지는 항상 결제창 내에서 선택 가능하며, 결제창 호출 파라미터로는 현금영수증을 발행 여부만을 제어할 수 있습니다. `cashReceiptType` 파라미터를 `ANONYMOUS`로 설정 시 결제창에서 현금영수증 발급 UI가 미노출됩니다.
#### 카드 결제
카드사 다이렉트 호출 시 할부 개월 수 옵션은 고정 할부 개월 수만 지원합니다. 웰컴페이먼츠 경우 **카드사 다이렉트 호출 시 할부 개월 수 옵션은** 고정 할부 개월 수만 지원합니다. 카드사 다이렉트 호출을 설정했으나 할부 개월 수 옵션을 `card.installment.monthOption.fixedMonth` 가 아닌 `card.installment.monthOption.availableMonthList`로 설정할 경우 에러가 발생합니다.
카드사 다이렉트 호출 시 지원하는 카드사 종류 웰컴페이먼츠의 경우 **포트원에서 관리하는 카드사 중 토스뱅크를 제외한 모든 카드사를 지원**합니다. 포트원에서 관리하는 카드사 목록을 확인하시려면 [JS SDK 결제요청 파라미터](https://developers.portone.io/sdk/ko/v2-sdk/payment-request) 페이지에서 `card` -> `cardCompany` 필드 설명을 참고해주세요.
웰컴페이먼츠에서 지원하지 않는 카드 관련 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useAppCardOnly`: 앱카드만 허용할지 여부 - `useInstallment`: 할부 사용 여부. (웰컴페이먼츠의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (웰컴페이먼츠의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 간편 결제
웰컴페이먼츠에서 지원하는 간편결제사 종류 웰컴페이먼츠의 경우 아래 간편결제사를 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. - 카카오페이: `KAKAOPAY` - lpay: `LPAY` - 토스페이: `TOSSPAY` - 페이코: `PAYCO` - 네이버페이: `NAVERPAY`
웰컴페이먼츠에서 지원하지 않는 간편결제 관련 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useCardPoint`: 카드사 포인트 사용 여부 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션 - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - `useInstallment`: 할부 사용 여부. (웰컴페이먼츠의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (웰컴페이먼츠의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.)
#### 계좌이체
웰컴페이먼츠에서 지원하지 않는 계좌이체 관련 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 계좌이체 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보
#### 가상계좌 결제
웰컴페이먼츠에서 지원하지 않는 가상계좌 관련 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `bankCode`: 가상계좌 은행 다이렉트 호출 시 은행 코드 - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 - `fixedOption`: 고정식 가상계좌 옵션. (웰컴페이먼츠의 경우 API를 통해서만 고정식 가상계좌 발급이 가능합니다.)
#### 상품권 결제
웰컴페이먼츠에서 지원하는 상품권 종류 및 필수 여부 웰컴페이먼츠 모바일 결제의 경우 `giftCertificateType`을 필수로 입력해야 하며, PC 결제의 경우는 선택 사항입니다. PC 결제에서 해당 파라미터를 입력하지 않을 경우 결제창 내에서 상품권 종류를 선택할 수 있습니다. 웰컴페이먼츠에서 지원하는 상품권 종류는 아래와 같습니다. - 도서문화상품권: `BOOKNLIFE` - 스마트문상: `SMART_MUNSANG` - 컬쳐랜드 문화상품권: `CULTURELAND`
#### 휴대폰 소액 결제
`productType` 파라미터는 필수 입력해야 합니다. - 웰컴페이먼츠의 경우 **휴대폰 소액결제시 상품 유형을 구분 짓는 `productType` 파라미터가 필수**로 입력해야 합니다. - `productType`의 값은 `PRODUCT_TYPE_REAL` 또는 `PRODUCT_TYPE_DIGITAL`를 입력해야 합니다.
결제창에 노출될 통신사 리스트 지정 옵션 지원 여부 웰컴페이먼츠 모바일 결제의 경우 `availableCarriers` 필드를 통해 결제창에 노출될 통신사 리스트를 지정할 수 있습니다. PC에서는 해당 파라미터를 지원하지 않습니다.
웰컴페이먼츠에서 지원하지 않는 휴대폰 소액결제 관련 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `carrier`: 휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값
## SDK 카드 빌링키 발급 요청하기 카드 빌링키 발급 요청 시에는 `requestIssueBillingKey` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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' 입력 시 법인 카드로만 결제를 진행 할 수 있습니다. ### 유의사항
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 빌링키 발급과 모바일 빌링키 발급에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 PC에서는 필수이지만, 모바일에서는 선택입니다. - `customer.fullName` 혹은 `customer.firstName + customer.lastName` - `customer.phoneNumber` - `customer.email` 아래 필드들은 모바일에서는 필수이지만, PC에서는 선택입니다. - `offerPeriod`
`issueId` 에는 ASCII 문자만 허용됩니다. `issueId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
`offerPeriod` 파라미터 제약 사항 SDK를 통한 빌링키 발급 요청 파라미터에는 제공 기간을 나타내는 `offerPeriod` 파라미터가 존재합니다. 날짜 범위를 입력하는 방식(`range`)과 간격을 입력하는 방식(`interval`) 중 하나를 선택하여 입력할 수 있습니다. - `range` 방식으로 입력할 경우 `from`과 `to` 모두를 입력하셔야 하, `from`은 `to`보다 과거 시간이어야 합니다. - `interval` 방식으로 입력할 경우는 `1m` 또는 `1y`만 허용됩니다. `1m`를 입력할 경우 `월 정기결제`, `1y`를 입력할 경우 `연 정기결제` 로 빌링키 발급 창에 노출됩니다.
지원되는 결제창 언어 SDK를 통한 빌링키 발급 요청 파라미터에는 결제창 언어를 지정할 수 있는 `locale` 파라미터가 존재합니다. PC 빌링키 발급의 경우 `KO_KR`, `EN_US`, `ZH_CN`을 지원하며, 모바일 빌링키 발급의 경우 해당 파라미터를 지원하지 않고 항상 한국어로 노출됩니다.
지원되는 결제 통화 SDK를 통한 빌링키 발급 요청 파라미터에는 displayAmount에 대한 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. 웰컴페이먼츠는 `KRW`만 지원합니다.
카드사 다이렉트 호출을 지원하지 않습니다. 웰컴페이먼츠 경우 카드사 다이렉트 호출을 통한 빌링키 발급을 지원하지 않습니다. `card.cardCompany` 필드에 값을 채워도 빌링키 발급 동작에 아무런 영향을 미치지 않습니다.
## SDK 휴대폰 빌링키 발급 및 결제 요청하기 휴대폰 빌링키 발급 및 결제 요청 시에는 `requestIssueBillingKeyAndPay` 함수를 호출해야 합니다. `channelKey` 파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 웰컴페이먼츠 채널 사용을 명시해주세요. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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) ### 유의사항
PC와 모바일에서 파라미터 필수 여부가 상이합니다. 위의 주요 파라미터 설명에도 안내되어 있듯이, PC 빌링키 발급 및 결제와 모바일 빌링키 발급 및 결제에서 필수 여부가 상이한 파라미터가 존재합니다. 아래 필드들은 모바일에서는 필수이지만, PC에서는 선택입니다. - `offerPeriod`
`paymentId` 에는 ASCII 문자만 허용됩니다. `paymentId` 에는 ASCII 문자만으로 이루어진 문자열만 입력할 수 있습니다. ASCII 문자에 포함되지 않는 한글이나 `♤`, `♡`, `♧` 등의 특수 문자는 허용되지 않습니다. 입력 가능한 ASCII 문자의 종류는 [링크](http://www.ascii-code.com/) → `ASCII printable characters` 섹션을 참고하세요.
`productType` 파라미터는 필수 입력해야 합니다. - 웰컴페이먼츠의 경우 **빌링키 발급 및 결제 시 상품 유형을 구분 짓는 `productType` 파라미터가 필수**로 입력해야 합니다. - `productType`의 값은 `PRODUCT_TYPE_REAL` 또는 `PRODUCT_TYPE_DIGITAL`를 입력해야 합니다.
`offerPeriod` 파라미터 제약 사항 SDK를 통한 빌링키 발급 및 결제 요청 파라미터에는 제공 기간을 나타내는 `offerPeriod` 파라미터가 존재합니다. 날짜 범위를 입력하는 방식(`range`)과 간격을 입력하는 방식(`interval`) 중 하나를 선택하여 입력할 수 있습니다. - `range` 방식으로 입력할 경우 `from`과 `to` 모두를 입력하셔야 하, `from`은 `to`보다 과거 시간이어야 합니다. - `interval` 방식으로 입력할 경우는 `1m` 또는 `1y`만 허용됩니다. `1m`를 입력할 경우 `월 정기결제`, `1y`를 입력할 경우 `연 정기결제` 로 빌링키 발급 및 결제 창에 노출됩니다.
웰컴페이먼츠에서 지원하지 않는 빌링키 발급 및 결제 파라미터 웰컴페이먼츠의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `locale`: 결제창 언어를 지정하기 위한 값 - `mobile.carrier`: 휴대폰 소액결제 통신사 바로 호출을 위한 통신사 구분 값 - `mobile.availableCarriers`: 빌링키 발급 및 결제창에 노출될 통신사 리스트
지원되는 결제 통화 SDK를 통한 빌링키 발급 및 결제 요청 파라미터에는 totalAmount에 대한 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. 웰컴페이먼츠 빌링키 발급 및 결제의 경우, `KRW`만 지원합니다.
## API 수기(키인)결제 요청하기 수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant`를 이용하여 결제 요청을 해야합니다.
```javascript // ... 수기(키인) 결제 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 **발급 은행** - 은행코드는 ENUM으로 정의되어 있습니다. - [BANK ENUM 바로가기](https://developers.portone.io/api/rest-v2/payment#Bank) - 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`를 이용하여 빌링키 발급 요청을 해야합니다. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```javascript 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`를 이용하여 결제를 요청합니다. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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` 를 이용하여 결제를 예약합니다. 웰컴페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.
```ts 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 **구매자 이메일** - 웰컴페이먼츠의 경우 필수로 입력해야 합니다. ### 유의사항 #### 공통
웰컴페이먼츠 필수 파라미터 웰컴페이먼츠의 경우에는 키인(수기)결제, 빌링키 발급, 빌링키 단건 결제 시 아래의 파라미터를 필수로 입력해야 합니다. - `customer.name.full` 혹은 `customer.name.separated` - `customer.phoneNumber` - `customer.email`
#### 에스크로
웰컴페이먼츠에서 에스크로 배송 등록시 필수 파라미터 웰컴페이먼츠의 경우 에스크로 배송 등록 시 아래의 파라미터를 필수로 입력해야 합니다. - `sender.name` - `sender.phoneNumber` - `sender.zipcode` - `sender.address` - `receiver.name` - `receiver.phoneNumber` - `receiver.zipcode` - `receiver.address` - `products`
# https://developers.portone.io/opi/ko/integration/start/v2/billing/issue --- title: 1. 빌링키 발급하기 description: 결제창 또는 API를 이용하여 빌링키를 발급할 수 있습니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/start/v1/non-auth --- 포트원에서는 PG사 결제창을 통해 빌링키를 발급하는 방법과 API를 이용하여 빌링키를 발급하는 방법을 지원합니다. 결제창을 이용한 빌링키 발급과 API를 통한 빌링키 발급 방식의 장단점은 아래와 같습니다. **결제창을 통한 빌링키 발급** - **장점** - 결제 수단 정보가 고객사나 포트원의 서버를 거치지 않고 직접 PG사로 전달되기 때문에 보안 문제가 일어날 가능성이 적습니다. - **단점** - PG사의 일반결제창을 통해 카드정보를 입력받기 때문에 웹브라우저를 통해서만 빌링키 발급이 이루어지며, **카드정보 입력란을 커스터마이징 할 수 없습니다.** **API를 통한 빌링키 발급** - **장점** - 고객사가 원하는 형태의 화면으로 **카드정보 입력란을 커스터마이징**할 수 있습니다. - 고객사 UI/UX 친화적인 결제 환경을 계획하고 계시다면 API 연동 개발을 선택하시길 권장드립니다. - **단점** - **개인정보 이용약관**을 명시해야 하며 PG사 및 카드사 심사가 까다롭고 개인정보 유출에 유의해야 합니다. ## 결제창을 통한 빌링키 발급 결제창을 이용해 빌링키를 발급할 때는 포트원 SDK를 이용합니다. 포트원 SDK를 설치하는 방법은 [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/checkout) 문서를 참고하세요. `PortOne.requestIssueBillingKey()` 함수를 호출하면 빌링키를 발급하기 위한 결제창을 열 수 있습니다. 브라우저에서 포트원 SDK를 호출하여 빌링키를 발급하고, 서버로 빌링키를 전달합니다. ```ts const issueResponse = await PortOne.requestIssueBillingKey({ storeId: "store-9bf6076d-beef-4729-9521-ae66c14e0569", channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", billingKeyMethod: "CARD", }); // 빌링키가 제대로 발급되지 않은 경우 에러 코드가 존재합니다 if (issueResponse.code !== undefined) { return alert(issueResponse.message); } // 고객사 서버에 빌링키를 전달합니다 const response = await fetch(`${MY_SEVER_URL}/billings`, { method: "POST", header: { "Content-Type": "application/json" }, body: JSON.stringify({ billingKey: issueResponse.billingKey, // ... }), }); if (!response.ok) throw new Error(`response: ${await response.json()}`); ``` ## API를 통한 빌링키 발급 고객 결제 정보를 이용하여 포트원 빌링키 발급 API를 호출하면 포트원 서버가 PG사를 통해 빌링키를 발급받습니다. 이 과정에서 카드 정보는 포트원 서버에 기록되지 않습니다. 브라우저로부터 결제 정보를 전달 받은 뒤, 서버에서 포트원 API를 호출하세요. ```ts title="server-side" // customerId, cardNumber, expiryYear, expiryMonth, birthOrBusinessRegistrationNumber, passwordTwoDigits 등 정보를 전달받습니다. // 포트원 빌링키 발급 API 호출 const issueResponse = await fetch("https://api.portone.io/billing-keys", { method: "POST", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}`, "Content-Type": "application/json", }, body: JSON.stringify({ channelKey: CHANNEL_KEY_HERE, customer: { id: customerId, }, method: { card: { credential: { number: cardNumber, expiryYear, expiryMonth, birthOrBusinessRegistrationNumber, passwordTwoDigits, }, }, }, }), }); if (!issueResponse.ok) throw new Error(`issueResponse: ${await issueResponse.json()}`); const { billingKeyInfo: { billingKey }, } = await issueResponse.json(); // 빌링키가 발급되었습니다! 빌링키를 저장하거나 결제하는 로직을 구성하세요. ``` ## 빌링키 발급 방식에 따른 인증과정 필수 여부 빌링키를 발급 받는 단계에서 인증과정은 다음과 같이 구분할 수 있습니다. 1. PG사의 결제창을 띄우는 방식 - PG사의 결제창 안에서 '공인인증(본인인증)' 절차를 요구하게 됩니다. 2. API 호출 방식 - API 호출만으로 빌링키 발급이 가능하기 때문에 인증 절차가 없습니다. 인증과정 포함 여부는 결제대행사별로 다르므로 상세 내용은 아래 링크에서 확인하세요. - [정기결제의 인증 과정 필수 여부](https://help.portone.io/content/schedule-requirement) # https://developers.portone.io/opi/ko/integration/start/v2/billing/payment --- title: 2. 결제 요청하기 description: 포트원 빌링키 결제 API를 사용해 바로 결제를 요청합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/start/v1/non-auth --- 포트원의 빌링키 결제 API를 호출하여 결제를 진행합니다. 바로 결제를 진행하고 싶은 것이 아니라 미래 특정 시점에 결제가 일어나게 하고 싶다면 [결제 예약하기](https://developers.portone.io/opi/ko/integration/start/v2/billing/schedule)을 참고하세요. ```ts title="server-side" // 고객사에서 채번하는 새로운 결제 ID를 만들어주세요. const paymentId = OrderService.getNewPaymentId(); // 포트원 빌링키 결제 API 호출 const paymentResponse = await fetch( `https://api.portone.io/payments/${encodeURIComponent(paymentId)}/billing-key`, { method: "POST", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}`, "Content-Type": "application/json", }, body: JSON.stringify({ billingKey, orderName: "월간 이용권 정기결제", // 빌링키 결제 API를 참고해 고객 정보를 채워주세요. customer: YOUR_CUSTOMER_INFO, amount: { total: 8900, }, currency: "KRW", }), }, ); if (!paymentResponse.ok) throw new Error(`paymentResponse: ${await paymentResponse.json()}`); ``` # https://developers.portone.io/opi/ko/integration/start/v2/billing/readme --- title: 빌링키 결제 연동하기 description: 카드 혹은 휴대 전화 정보를 이용하여 빌링키를 발급하고, 빌링키를 이용해 결제를 요청하는 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/start/v1/non-auth --- ## 빌링키란? 구독형 정기결제, 종량제 과금결제 등 고객사가 원하는 시점에 결제를 일으키기 위한 결제용 비밀 키입니다. 고객사가 고객의 카드정보를 저장할 수 없기 때문에, 해당 카드에 대응하는 빌링키를 발급 받아 저장하고, 결제 시점에는 결제 정보 대신 빌링키를 이용하여 요청하는 방식을 씁니다. 가지고 있는 빌링키를 사용해 즉시 결제를 요청하거나, 시간을 정해 결제를 예약할 수 있습니다.
### 빌링키는 정기 구독에만 사용이 가능합니다. 빌링키를 이용한 결제는 결제수단이 본인 소유인지 확인이 어려워 관리가 어렵고, 카드사 심사 시 빌링키를 사용한 비정기적인 결제를 허용하지 않을 수 있습니다.
# https://developers.portone.io/opi/ko/integration/start/v2/billing/schedule --- title: 3. 예약/반복결제 구현하기 description: 발급한 빌링키로 예약/반복결제를 구현하는 방법을 안내합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/start/v1/non-auth --- ## 1. 결제 예약하기 미래의 특정 시점에 결제가 진행되도록 할 때는 **포트원 결제 예약 API**를 이용합니다. ```ts title="server-side" // 포트원 결제 예약 API 호출 const scheduleResponse = await fetch( `https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/schedule`, { method: "POST", headers: { Authorization: `PortOne ${PORTONE_API_SECRET}`, "Content-Type": "application/json", }, body: JSON.stringify({ payment: { billingKey: BILLING_KEY_HERE, orderName: "월간 이용권 정기결제", customer: { id: CUSTOMER_ID_HERE, // 고객 정보가 필요한 경우 API 명세에 따라 추가해주세요. }, amount: { total: 8900, }, currency: "KRW", }, timeToPay: "2023-08-24T14:15:22Z", // 결제를 시도할 시각 }), }, ); if (!scheduleResponse.ok) throw new Error(`scheduleResponse: ${await scheduleResponse.json()}`); ``` ## 2. 결제 결과 수신하기 예약한 시간에 결제가 시도되면 지정한 서버의 웹훅 URL로 고객사 거래 번호(**`payment_id`**)가 전달됩니다. 결제 결과를 확인하신 뒤 결제 완료 처리를 하시면 됩니다. 웹훅을 받아 결제 결과를 확인하는 방법은 [웹훅 연동하기](https://developers.portone.io/opi/ko/integration/webhook/readme-v2)를 참고해주세요. ## 3. 반복 결제 구현하기 반복 결제는 예약된 결제가 완료된 뒤 다음 결제를 예약하는 식으로 구현할 수 있습니다. # https://developers.portone.io/opi/ko/integration/start/v2/checkout --- title: 인증 결제 연동하기 description: PG 결제창을 이용하는 인증 결제를 연동합니다. targetVersions: - v2 versionVariants: v1: /opi/ko/integration/start/v1/auth --- ## **SDK 일반 결제**
영상으로 보기 [포트원 인증 결제의 이해 - 쇼핑몰 멀티PG 연동하기](https://www.youtube.com/watch?v=DhcQFLYV9Q8)
## **결제 연동 샘플 프로젝트** SDK를 지원하지 않는 플랫폼을 포함하여 다양한 플랫폼에서 결제 연동 예시를 확인하실 수 있도록 [portone-sample GitHub 저장소](https://github.com/portone-io/portone-sample)에서 샘플 프로젝트를 제공하고 있습니다. 일부 플랫폼의 경우 devcontainers 환경에서 바로 실행해보실 수 있습니다. ## 1. 포트원 SDK 설치 포트원은 다양한 PG의 결제창을 통일된 방법으로 호출할 수 있도록 자바스크립트 SDK를 제공합니다. 브라우저에서 포트원 SDK를 호출하여 결제를 진행하게 됩니다. 포트원 V2 SDK는 npm 레지스트리와 CDN을 통해 배포되고 있습니다. - npm, yarn 등 패키지 매니저를 사용한다면 의존 대상으로 [@portone/browser-sdk](http://www.npmjs.com/package/@portone/browser-sdk)를 추가하세요. - 패키지 매니저를 사용하지 않는다면 ` ``` ` ``` `