연동 가이드

빠른 시작

point3 결제는 결제 세션 생성, 결제창 열기, 결제 승인의 세 단계로 진행돼요. 가맹점 서버에서 결제 세션을 생성하고, 환경에 따라 연동 방식을 선택하여 결제창을 열고, 결제를 승인하여 완료합니다.

준비하기

담당자 안내에 따라 대시보드 가입을 완료해주세요. 아직 도입을 결정하지 않았다면 홈페이지에 문의를 남겨주세요.
대시보드의 현금영수증 정보 페이지에서 현금영수증 자동 발급을 활성화 하세요.
대시보드의 개발정보 관리 페이지에서 결제 모듈을 활성화 하세요.
같은 페이지에서 API 키를 발급받고 가맹점 아이디를 확인하세요.

값	형식	사용하는 곳
가맹점 아이디	`client-...`	가맹점 화면: 결제창을 열 때 `client_id`로 전달
API 키	`s2scred-...`	가맹점 서버: API를 호출할 때 `Authorization` 헤더로 전달

API 키는 가맹점 서버에만 보관하고 브라우저 코드에 넣지 마세요.

1. 결제 세션 생성 (서버)

결제 세션은 결제 금액, 상품명 등 결제 한 건을 처리할 때 필요한 정보를 담는 point3의 결제 처리 단위입니다. 가맹점 서버가 결제창을 열기 전에 생성하고, 결제 세션의 아이디인 sessionId로 이후 결제창 열기부터 승인, 조회, 취소를 진행하게 됩니다.

코드
curl -X POST https://api.point3.io/payment/v3/session \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "productName": "아메리카노 외 1건" }'

가맹점에서 결제 금액과 상품명을 지정하여 결제 세션 생성을 요청하면 응답으로 세션 아이디를 받습니다. 해당 세션 아이디를 가맹점의 주문과 연결하여 저장해두세요.

자세한 요청 값과 세금 처리는 결제 생성에서 확인하세요.

2. 결제창 열기 (화면)

이전 단계에서 생성한 결제 세션의 sessionId를 서버에서 화면으로 전달하고, 결제창을 열어야합니다. 결제창을 열면 구매자가 결제 내용을 확인하고 결제 의사를 확정할 수 있습니다. 결제창은 JavaScript SDK로 엽니다. React Native, Flutter, 네이티브 앱은 SDK를 연동한 HTML을 WebView로 띄웁니다.

JavaScript SDK

SDK를 설치하고 client_id로 초기화한 뒤 requestPayment()를 호출합니다. orderId에는 가맹점 주문번호가 아닌 결제 세션의 sessionId를 넣습니다.

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

await widgets.setAmount({ currency: 'KRW', value: 10000 })
await widgets.requestPayment({
  orderId: sessionId,
  orderName: '아메리카노 외 1건',
  successUrl: 'https://merchant.example.com/payments/success', // 결제 요청이 성공하면 이동할 URL
  failUrl: 'https://merchant.example.com/payments/fail' // 결제 요청이 실패하면 이동할 URL
})

구매자가 결제를 확정하면 SDK가 successUrl로 이동하며 orderId와 payerId를 전달합니다. 두 값은 가맹점 서버가 결제를 최종으로 처리하기 위해 필요합니다. 화면이 값을 받으면 서버에 데이터를 전달하도록 구현해주세요.

SDK에 대한 자세한 내용은 JavaScript SDK 결제 연동을 참고하세요.

앱

결제하기 화면이 네이티브 앱 화면이라면 결제창을 연동한 HTML 단일 페이지를 앱의 정적 에셋에 포함하고 WebView로 띄우세요. 하이브리드 앱이나 웹 앱이라면, 별도의 HTML 없이 JavaScript SDK를 연동한 결제하기 페이지를 그대로 띄우면 됩니다. 자세한 내용은 연동 방식 선택을 참고하세요.

결제창 성공은 결제 성공이 아닙니다

successUrl로 이동했다고 해서 결제가 완료된 것이 아닙니다. 상품을 지급하거나 성공 화면을 표시하지 마세요.

3. 결제 승인 (서버)

화면에서 받은 값이 주문에 저장한 sessionId와 같은지 확인한 뒤 결제 승인 API를 호출합니다.

코드
curl -X POST https://api.point3.io/capture/v2/$SESSION_ID \
  -H "Authorization: Bearer $API_KEY"

결과는 HTTP 상태 코드가 아니라 응답 본문의 status로 판단합니다. 실패가 확정된 경우에도 HTTP 200이 반환됩니다.

captured: 결제 완료
failed: 결제 실패. 잔액 부족, 이체한도 초과 같은 사유는 outcome.code로 구분합니다. 처음 받은 outcome.code를 주문에 저장해 두세요.
processing(HTTP 202): 아직 처리 중이며 실패가 아닙니다. 응답을 받지 못했을 때와 같이 sessionId로 결제 세션을 조회합니다.

이미 실패한 결제를 다시 승인 요청하면 원래 사유 대신 PAYMENT_CAPTURE_ALREADY_FAILED가 반환됩니다. 실패 사유를 확인하려고 승인 API를 다시 호출하지 마세요.

결제 승인 요청은 구매자가 결제 의사를 확정한 당일 자정까지 유효합니다.

실패 코드별 처리 방법은 문제 해결에서 확인하세요.

자세한 처리 방법은 결제 승인에서 확인하세요.

다음 단계

승인된 결제의 취소는 결제 취소를 참고하세요.
결제창을 열기 전에 구매자에게 EOB 점검 시간을 안내해주세요.
구매자에게 결제 수단을 미리 등록받으려면 등록 전용 위젯을 참고하세요.
로그인한 회원의 결제에서 문자 인증을 생략하려면 위임 인증을 참고하세요.

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

AI로 시작하기