JavaScript SDK

JavaScript SDK 위임 인증

JavaScript SDK 결제창에 위임 인증을 적용하는 방법을 알아봅니다. 먼저 JavaScript SDK 결제 연동을 완료하고, 가맹점 서버에서 위임 인증을 생성해 authorization_url을 받으세요.

결제창 연동과 달라지는 것은 widgets() 옵션 하나입니다. setAmount(), requestPayment()와 결과 URL 처리는 그대로 사용합니다.

위임 인증 연동

point3.widgets()

widgets()의 brandpay.redirectUrl에 authorization_url을 전달합니다. customerKey에는 위임 인증을 생성한 회원의 payerId를 전달합니다.

const widgets = point3.widgets({
  customerKey: savedPayerId,
  brandpay: { redirectUrl: authorizationUrl }
})

파라미터

이름	타입	설명
`customerKey`	`string`	위임 인증을 생성한 회원의 `payerId`입니다.
`brandpay.redirectUrl`	`string`	위임 인증 생성 응답의 `authorization_url`입니다. 생략하면 위임 인증 없이 결제창이 열립니다.

customerKey에도 같은 payerId를 전달하세요

위임 인증을 완료하지 못하면 결제창은 customerKey의 구매자로 문자 인증을 진행합니다. customerKey 필드를 비우거나 ANONYMOUS를 전달하지 마세요.

응답

JavaScript SDK 결제 연동과 같은 widgets 객체를 반환합니다. 이어서 setAmount()와 requestPayment()를 호출하세요.

위임 인증 생성에 실패했을 때

가맹점 서버가 위임 인증을 생성하지 못했다면 brandpay 옵션 없이 결제창을 엽니다.

const widgets = point3.widgets({
  customerKey: savedPayerId,
  ...(authorizationUrl ? { brandpay: { redirectUrl: authorizationUrl } } : {})
})

await widgets.setAmount({ currency: 'KRW', value: 10000 })
await widgets.requestPayment({ orderId: sessionId, orderName, successUrl, failUrl })

전달 규칙

authorization_url은 받은 문자열을 그대로 전달하세요. 주소, 경로, 쿼리를 바꾸면 SDK가 결제창을 열지 않고 INVALID_PAYMENT_REQUEST 오류를 발생시킵니다.
위임 인증은 결제에만 사용할 수 있습니다. orderId를 빈 문자열로 보내는 등록 전용 위젯과 함께 사용하면 INVALID_PAYMENT_REQUEST 오류가 발생합니다.
위임 인증은 한 번의 결제창 실행에만 사용할 수 있습니다. 결제를 다시 시도할 때에는 가맹점 서버에서 새로 생성한 authorization_url을 사용하세요.

결과 처리

결과 URL은 JavaScript SDK 결제 연동과 같습니다. 결제 승인 준비가 끝나면 successUrl로, 결제를 완료하지 못하면 failUrl로 이동합니다.

성공 URL의 orderId와 payerId는 위임 인증을 사용하지 않을 때와 같은 방법으로 확인하고 결제 승인 API를 호출하세요.

성공 URL 이동은 최종 결제 성공이 아닙니다

위임 인증을 사용해도 최종 결제 결과는 가맹점 서버가 결제 승인 API 응답을 확인한 뒤 결정하세요.

point3 SDK 오류

아래 오류는 failUrl로 전달되지 않으며, 오류 객체의 code로 확인할 수 있습니다.

오류 코드	원인
`INVALID_PAYMENT_REQUEST`	`brandpay.redirectUrl`이 위임 인증 생성 응답의 `authorization_url`이 아니거나, 빈 `orderId`와 함께 전달됨
`BROWSER_NOT_READY`	문서 준비 상태, 보안 컨텍스트 또는 `crypto.randomUUID()` 미지원

그 밖의 오류는 JavaScript SDK 결제 연동과 같습니다.

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

등록 전용 위젯