JavaScript SDK 결제 연동
point3 JavaScript SDK의 결제창 연동 방법을 알아봅니다. 먼저 JavaScript SDK 설정 및 초기화을 완료하세요.
widgets()로 결제 객체를 만들고, 토스페이먼츠 SDK 호환을 위한 금액을 설정한 뒤 requestPayment()로 결제창을 엽니다.
실제 결제 금액은 가맹점 서버에서 생성한 point3 결제 세션을 기준으로 결정됩니다.
결제 연동
point3.widgets()
widgets() 메서드로 결제 서비스를 초기화합니다. 저장된 point3 payerId가 없다면 ANONYMOUS를 사용하세요.
payerId는 point3가 발급하는 구매자 식별값입니다. 임의로 만들거나 형식을 바꿀 수 없습니다. 자세한 내용은 구매자 아이디를 참고하세요.
customerKey에는 point3 payerId를 사용하세요
customerKey는 토스페이먼츠 SDK 호환을 위해 유지한 파라미터 이름입니다. 가맹점이 임의로 만든 고객 키가 아니라 point3
결제 화면에서 받은 payerId를 전달하고, 저장된 payerId가 없을 때만 ANONYMOUS를 사용하세요.
파라미터
| 이름 | 필수 여부 | 타입 | 설명 |
|---|---|---|---|
customerKey | 필수 | string | 저장된 point3 payerId입니다. 값이 없으면 ANONYMOUS를 사용합니다. |
로그인한 회원의 결제에서 문자 인증을 생략하려면 brandpay.redirectUrl 옵션을 함께 전달합니다. 자세한 내용은 JavaScript SDK 위임 인증을 참고하세요.
응답
결제 금액을 설정하고 결제창을 열 수 있는 widgets 객체를 반환합니다.
widgets.setAmount()
setAmount() 메서드로 결제 금액을 전달합니다. requestPayment()보다 먼저 호출하세요.
실제 결제 금액은 결제 세션이 결정합니다
구매자에게 청구되는 금액은 가맹점 서버가 생성한 결제 세션의 금액입니다. setAmount()에는 결제 세션과 같은 금액을 전달하세요.
파라미터
| 이름 | 필수 여부 | 타입 | 설명 |
|---|---|---|---|
currency | 필수 | string | KRW만 지원합니다. |
value | 필수 | number | 결제 금액입니다. 1원 이상의 정수입니다. |
할인 등으로 실제 결제 금액이 바뀌었다면 변경된 주문 금액으로 새 결제 세션을 생성하세요. 브라우저의 setAmount() 값으로
서버가 확정한 결제 금액을 변경할 수 없습니다.
응답
설정이 완료되면 별도의 값을 반환하지 않습니다.
widgets.requestPayment()
requestPayment() 메서드로 전체 화면 결제창을 엽니다.
결제 결과 URL은 가맹점이 정합니다
successUrl과 failUrl에는 가맹점이 사용하는 결과 페이지의 절대 URL을 전달하세요. point3가 특정 경로를 정하지
않으며, SDK 예제의 변수도 가맹점 환경에서 직접 구성해야 합니다.
파라미터
| 이름 | 필수 여부 | 타입 | 설명 |
|---|---|---|---|
orderId | 필수 | string | 결제 세션 생성 API 응답의 id인 point3 sessionId입니다. |
orderName | 필수 | string | 결제 세션의 상품명과 일치하는 공백이 아닌 100자 이하의 주문 상품명입니다. |
successUrl | 필수 | string | 결제 승인 준비가 끝나면 이동할 가맹점의 HTTPS 절대 URL입니다. |
failUrl | 필수 | string | 결제 요청을 완료하지 못하면 이동할 가맹점의 HTTPS 절대 URL입니다. |
orderId는 토스페이먼츠 SDK 호환을 위해 유지한 파라미터 이름입니다. orderId에는 point3 결제
세션 생성 API가 반환한 id를 입력하세요.
EOB 점검 시간을 안내하세요
매일 23:30부터 다음 날 00:30까지(KST)는 점검 시간입니다. 결제 세션 생성이 거절되면 구매자에게 error.eob.endsAt으로 종료 시각을 안내하고, 그 이후 다시 요청하세요. 응답 예시는 EOB 점검 시간을 참고하세요.
로컬 개발에서는 localhost, 127.0.0.1, [::1]에 한해 HTTP 결과 URL을 사용할 수 있습니다. 운영 환경에서는 HTTPS
주소를 사용하세요.
응답
결제 승인 준비가 끝나면 SDK가 successUrl에 다음 쿼리 파라미터를 추가해 이동합니다.
| 이름 | 설명 |
|---|---|
orderId | point3 결제 세션 생성 API가 반환한 id |
payerId | 결제를 진행한 구매자의 구매자 아이디 |
amount | setAmount()에 전달한 값 |
토스페이먼츠 SDK와의 호환을 위해 성공 URL에서도 orderId라는 이름을 사용합니다. point3 연동에서 orderId의 값은
requestPayment()에 전달한 결제 세션 id, 즉 point3 sessionId입니다. 별도의 sessionId 쿼리 파라미터는 제공하지
않습니다.
가맹점 서버에 저장한 현재 주문의 sessionId와 결과 URL의 orderId가 같은지 확인한 뒤 결제 승인 API를
호출하세요. amount는 실제 결제 금액의 검증 기준으로 사용하지 말고, 서버에 저장한 주문과 결제 세션의 금액을 기준으로 처리하세요.
payerId는 다음 결제의 customerKey로 다시 사용할 수 있도록 가맹점 회원 정보에 저장하세요. URL에서 받은 값은 조작될 수
있으므로 결제 세션 조회 응답의 payerId와 대조하세요. 자세한 내용은 구매자 아이디를 참고하세요.
성공 URL 이동은 최종 결제 성공이 아닙니다
최종 결제 결과는 가맹점 서버가 결제 승인 API 응답을 확인한 뒤 결정하세요.
사용자가 결제창을 닫거나 결제 요청을 완료하지 못하면 SDK가 다음 쿼리 파라미터를 추가한 failUrl로 이동합니다.
앱의 WebView에서도 동일하게 동작합니다. 앱에서 결과를 받는 방법은 연동 방식 선택을 참고하세요.
| 이름 | 설명 |
|---|---|
code | 실패 결과를 구분하는 코드 |
message | 실패 사유를 설명하는 메시지 |
결제창은 SDK가 자동으로 닫습니다. 실패 결과 화면에서는 code에 맞는
안내를 표시하고, 결과 처리는 message가 아닌 code를 기준으로 하세요.
| 코드 | 안내 문구 예시 |
|---|---|
PAYMENT_WINDOW_CLOSED | 결제창이 닫혔습니다. |
PAYER_DEACTIVATED | 탈퇴가 완료되어 결제가 종료되었습니다. |
SESSION_EXPIRED | 결제 세션이 만료되었습니다. 결제를 다시 시도해 주세요. |
INVALID_SESSION | 결제 세션 정보를 확인할 수 없습니다. 결제를 다시 시작하세요. |
PAYMENT_FAILED | 결제 요청이 거절되었습니다. 예: 결제 금액은 적용 수수료보다 커야 합니다. |
SDK는 가맹점이 결과 URL에 미리 추가한 쿼리 파라미터를 유지합니다. 현재 주문이나 결제 시도 식별값이 필요하면 failUrl에 직접 추가하세요.
PAYMENT_FAILED는 결제 요청이 거절됐음을 나타냅니다. 수수료 조건을 충족하지 못한 경우 message에 결제 금액은 적용 수수료보다 커야 합니다.가 전달됩니다.
point3 SDK 오류
아래 오류는 failUrl로 전달되지 않으며, 오류 객체의 code로 확인할 수 있습니다.
| 오류 코드 | 설명 |
|---|---|
INVALID_CLIENT_KEY | Point3()에 전달한 clientId가 client-... 형식이 아닙니다. |
INVALID_PAYMENT_REQUEST | 요청값 또는 SDK 호출 순서가 올바르지 않습니다. |
PAYMENT_REQUEST_IN_PROGRESS | 결제나 등록이 진행 중인 상태에서 다시 요청했습니다. |