JavaScript SDK

JavaScript SDK 등록 연동

point3 JavaScript SDK로 등록 전용 위젯을 연동합니다. 먼저 JavaScript SDK 설정 및 초기화을 완료하세요. 등록에는 결제 세션이나 금액 설정이 필요하지 않습니다.

등록 전용 위젯은 필수가 아닌 선택적 기능으로, 결제 위젯만 연동해도 구매자가 결제 수단을 등록하는 데에 문제가 없습니다.

다만, 사용자 경험을 위하여 선택적으로 등록 전용 위젯을 연동하여 결제 퍼널을 개선할 수 있습니다. 등록 전용 위젯은 결제 위젯과 달리 세션이나 금액 설정이 필요하지 않으며, 구매자가 등록만 진행할 수 있는 별도의 등록창입니다.

앱에서는 결제창과 같은 방법으로 등록창을 연동한 HTML을 WebView로 띄웁니다.

등록 연동

point3.widgets()

widgets() 메서드로 등록 서비스를 초기화합니다.

const widgets = point3.widgets({
  customerKey: Point3.ANONYMOUS
})

point3는 SDK 설정 및 초기화에서 초기화한 객체입니다.

파라미터

이름	필수 여부	타입	설명
`customerKey`	필수	`string`	`Point3.ANONYMOUS` 고정

응답

등록창을 열 수 있는 widgets 객체를 반환합니다.

widgets.requestPayment()

requestPayment()에 orderId: ''를 전달하면 등록창을 엽니다. 등록에는 setAmount() 호출이나 결제 세션 생성이 필요하지 않습니다.

await widgets.requestPayment({
  orderId: '',
  orderName: '등록',
  successUrl: 'https://merchant.example/registration/success',
  failUrl: 'https://merchant.example/registration/fail'
})

파라미터

이름	필수 여부	타입	설명
`orderId`	필수	`string`	빈 문자열 `''`을 고정 사용합니다.
`orderName`	필수	`string`	`'등록'` 문자열을 고정 사용합니다.
`successUrl`	필수	`string`	등록 성공 후 이동할 가맹점의 HTTPS 절대 URL입니다.
`failUrl`	필수	`string`	등록을 완료하지 못했을 때 이동할 가맹점의 HTTPS 절대 URL입니다.

로컬 개발에서는 localhost, 127.0.0.1, [::1]에 한해 HTTP 결과 URL을 사용할 수 있습니다. 운영 환경에서는 HTTPS 주소를 사용하세요.

응답

사용자가 등록창에서 등록을 마치면 SDK가 successUrl에 payerId를 추가해 이동합니다. 예를 들어 다음과 같이 이동합니다.

코드
https://merchant.example/registration/success?payerId=payer:00000000000000000000000000

결과 페이지에서는 다음과 같이 값을 읽을 수 있습니다.

const params = new URLSearchParams(window.location.search)
const payerId = params.get('payerId')

받은 payerId를 가맹점 회원 정보에 저장하고, 다음 결제의 customerKey로 사용하세요. 이미 결제 세션 조회를 통해 저장된 값이 있다면, 해당 값을 신뢰하고 화면에서 받은 값으로 덮어쓰지 마세요. 자세한 내용은 구매자 아이디를 참고하세요.

취소와 오류 처리

취소하거나 등록을 완료하지 못하면 SDK가 failUrl에 code와 message를 추가해 이동합니다. 가맹점 화면은 message가 아닌 code를 기준으로 처리하고, 다음과 같은 안내를 표시하세요.

코드	안내 문구 예시
`REGISTRATION_CANCELLED`	등록이 취소됐습니다.
`AUTHENTICATION_EXPIRED`	인증이 만료됐습니다. 등록을 다시 시작하세요.
`REGISTRATION_FAILED`	등록을 완료하지 못했습니다. 안내를 확인한 뒤 다시 시도하세요.
`REGISTRATION_RESULT_UNAVAILABLE`	등록 결과를 확인할 수 없습니다.

위 표에 없는 code는 "등록을 완료하지 못했습니다."로 안내하세요.

SDK 초기화·시작 전 오류

다음 오류는 failUrl로 전달되지 않습니다. SDK 초기화와 등록 요청을 try/catch로 감싸고 오류 객체의 code를 확인하세요.

오류 코드	처리
`INVALID_CLIENT_KEY`	발급받은 `client_id`와 `client-...` 형식을 확인하세요.
`INVALID_PAYMENT_REQUEST`	빈 `orderId`, `orderName`, 결과 URL을 확인하세요.
`PAYMENT_REQUEST_IN_PROGRESS`	이미 열린 등록창의 진행을 마무리하세요.
`BROWSER_NOT_READY`	문서 준비 상태, 보안 컨텍스트와 `crypto.randomUUID()` 지원을 확인하세요.

등록창은 SDK가 닫으므로 가맹점에서 직접 제거하지 마세요. 취소·오류로 종료된 뒤에는 사용자가 버튼을 눌러 다시 시작할 수 있게 하세요. 인증이 만료됐다면 본인인증부터 다시 진행합니다.

등록 후 결제

등록 후 결제하려면 가맹점 서버에서 별도의 결제 세션을 생성하세요. 결제 생성, SDK 결제 연동, 결제 승인을 참고하세요.

마지막 수정: 2026년 10월 27일

결제창 연동 위임 인증