Markdown으로 복사

서버 연동

결제 생성

결제창을 열기 전에 가맹점 서버에서 결제 세션을 생성합니다.

요청 값

필드	필수	설명
amount	필수	구매자가 결제할 총액
productName	필수	결제창에 표시할 상품명
displayMerchantName	선택	결제 UI에 표시할 가맹점 상호명 (미지정 시 productName 사용)
taxFreeAmount	선택	총액에 포함된 면세 금액
vat	선택	총액에 포함된 부가세
tradeOpt	선택	현금영수증 상품 분류

기본 요청
{
  "amount": 10000,
  "productName": "아메리카노 외 1건",
  "displayMerchantName": "포인트쓰리 스토어"
}

10% 세율이 적용되는 일반 상품의 경우 amount와 productName만 전달하세요. 면세 상품이나 영세율이 적용되는 상품의 경우 세금 처리를 확인하여 결제 세션을 생성하세요.

결제 금액과 EOB 점검 시간

적용 수수료보다 큰 금액으로 요청하세요. 일반적인 최소 수수료는 77원이며, 실제 적용 요율과 최소 수수료는 가맹점 대시보드의 계약사항에서 확인할 수 있습니다. 수수료 조건은 결제 최종 확인 단계에서 검증됩니다.

매일 23:30부터 다음 날 00:30까지(KST)는 점검 시간으로 결제 세션을 생성할 수 없습니다. 점검 중에는 503 temporarilyUnavailable과 함께 error.eob가 반환됩니다. 점검 시작·종료 시각은 startsAt과 endsAt에 날짜와 UTC 오프셋을 포함합니다.

응답 처리

성공하면 status: created인 결제 세션을 반환합니다.

확인할 응답 값
{
  "id": "pymt_sess-019f0000-0000-7000-9000-000000000000",
  "status": "created",
  "amount": 10000
}

1. 응답의 id는 해당 결제의 식별자로서, sessionId로 사용합니다.
2. 가맹점 서버는 주문에 sessionId를 저장한 뒤 가맹점 화면에 전달합니다.

시간 초과나 네트워크 오류, 5xx 등으로 응답을 받지 못했다면 같은 주문으로 결제 세션을 새로 생성하고, 새로 받은 sessionId를 주문에 저장하세요. 결제 세션은 구매자가 결제 의사를 확정하고 가맹점 서버가 결제를 승인해야 결제가 이루어지므로, 응답을 받지 못한 세션은 사용되지 않고 결제되지 않습니다.

결제 세션 조회

가맹점 서버는 발급한 세션 식별자로 결제 세션의 진행 상태와 상세 정보를 언제든 조회할 수 있습니다. 결제 승인 API를 호출한 뒤에 상태 조회가 필요할 경우 이 조회 결과로 최종 결제 상태를 확인할 수 있습니다.

코드
GET https://api.point3.io/payment/v3/session/{sessionId}

결제 세션의 상태는 다음과 같습니다.

상태 값	의미	처리
created, identified, initiated	결제 진행 중
committed	결제 승인 준비 완료	결제 승인 API 호출
processing	결제 처리 중	잠시 기다렸다가 다시 조회
captured	결제 성공	결과 확인 완료
failed	결제 실패	결과 확인 완료
expired	결제 승인 기한 만료	새 결제 세션으로 다시 시작

전체 필드와 오류 응답은 결제 API 레퍼런스에서 확인하세요.

결제 세션이 생성되었으면 세션 아이디를 가맹점 화면으로 전달하여 point3 결제창을 표시하도록 해야합니다. 연동 방식 선택을 참고하세요.