Markdown으로 복사

연동 가이드

결제 흐름과 상태

point3 결제는 가맹점 서버, 가맹점 화면, point3 사이에서 진행됩니다. 세 주체가 주고받는 값과 그 과정에서 결제 세션이 거치는 상태를 확인하세요.

전체 흐름

가맹점 화면

가맹점 서버

1주문 요청

2결제 세션 생성

POST /payment/v3/session

3sessionId 발급

status: created

4sessionId 전달

5결제창 열기

구매자의 결제 의사 확정

6승인 준비 신호

successUrl로 이동

7sessionId, payerId 전달

8결제 승인

POST /capture/v2/{sessionId}

9승인 결과

captured · failed

결제 세션 생성과 결제 승인은 웹과 앱 모두 같습니다. 결제창은 JavaScript SDK로 열고, 앱에서는 SDK를 연동한 HTML을 WebView로 띄웁니다. 차이는 연동 방식 선택에서 확인하세요.

서버에서 승인하는 이유

결제창이 닫히거나 성공 URL로 이동했다고 해서 결제가 완료된 것은 아닙니다. 구매자가 결제 의사를 확정하면 point3는 결제를 승인할 준비가 되었다는 신호만 가맹점 화면에 보냅니다. 실제 결제는 가맹점 서버가 결제 승인 API를 호출할 때 일어납니다.

결제의 최종 결정권을 가맹점 서버에 두기 위해서입니다. 브라우저에서 오는 값은 조작될 수 있으므로, 가맹점 서버는 화면에서 받은 sessionId가 현재 구매자의 주문에 저장된 값과 같은지 확인한 뒤에만 승인을 요청합니다. 그리고 승인 API 응답이나 결제 세션 조회 응답의 status로만 결제 성공 여부를 판단합니다.

결제 세션 상태

결제 세션은 생성부터 확정까지 다음 상태를 거칩니다.

created세션 생성

…

committed승인 준비 완료

결제 승인 요청 후

processing승인 처리 중

captured결제 성공

failed결제 실패

상태	의미	가맹점 서버의 처리
created	세션이 생성되었습니다.	sessionId를 가맹점 화면에 전달합니다.
identified	구매자 본인인증이 끝났습니다.
initiated	결제가 진행 중입니다.
committed	구매자가 결제 의사를 확정했습니다.	결제 승인 API를 호출합니다.
processing	승인 처리 중입니다.	잠시 기다렸다가 다시 조회합니다.
captured	결제가 성공했습니다.	주문을 완료합니다. 최종 상태
failed	결제가 실패했습니다.	실패를 안내합니다. 최종 상태

승인 기한이 지나면 승인 API가 422로 응답하고, 결제 세션 조회 결과는 expired가 됩니다. 이 세션으로는 더 이상 결제할 수 없으므로 새 결제 세션을 만들어 처음부터 다시 시작합니다.

processing은 잠시 뒤 captured 또는 failed로 확정됩니다. 최종 상태는 captured와 failed 두 가지입니다.

시간 제약

결제 흐름에는 두 가지 시간 제약이 있습니다.

승인 기한

결제 승인 요청은 구매자가 결제 의사를 확정한 당일 자정(KST)까지 유효합니다. 예를 들어 15일 22:00에 구매자가 결제 의사를 확정했다면 16일 00:00 전까지 승인해야 합니다. 구매자가 결제 의사를 확정하면 곧바로 승인을 요청하세요.

EOB 점검 시간

매일 23:30부터 다음 날 00:30까지(KST)는 점검 시간으로 결제 세션 생성, 결제 진행, 결제 취소가 제한됩니다. 이 시간에 결제창을 열면 구매자가 결제를 마칠 수 없으므로, 결제창을 열기 전에 구매자에게 점검 시간을 안내해야 합니다. 응답 형식은 EOB 점검 시간에서 확인하세요.

결과를 알 수 없을 때

네트워크 오류나 타임아웃으로 승인 응답을 받지 못하면 결제가 성공했는지 알 수 없습니다. 이때 같은 주문으로 새 결제를 시작하거나 실패로 처리하면 이중 결제나 누락이 생길 수 있습니다.

결제 승인 API는 같은 sessionId로 여러 번 호출해도 결제가 한 번만 일어나도록 설계되어 있습니다. 결과를 알 수 없으면 시간을 두고 같은 sessionId로 승인을 다시 요청하거나 결제 세션을 조회하고, captured 또는 failed가 확인될 때까지 주문을 확정하지 마세요.

다음 단계

• 서버 연동 방법은 서버 연동 개요를 참고하세요.
• 결제창 연동 방법은 연동 방식 선택과 JavaScript SDK 설정 및 초기화를 참고하세요.