결제

결제창을 열기 전에 결제 세션을 만들고, 구매자가 결제를 진행한 뒤 결제 결과를 확인합니다.

결제 세션 조회

GET

https://api.point3.io

/payment/v3/session/{sessionId}

결제 세션 아이디로 결제 세션 정보를 조회합니다. 정상 조회는 HTTP 200으로 반환되며 응답 본문의 status로 진행 상태와 최종 결과를 판단합니다. processing이면 잠시 기다렸다가 같은 세션을 다시 조회하세요. captured 또는 failed가 확인되면 결제 결과가 확정된 것입니다.

결제 세션 조회 › 경로 파라미터

sessionId

string · 필수

조회할 결제 세션 식별자

결제 세션 조회 › 응답

결제 세션 조회 성공

조회된 결제 세션 리소스입니다.

PaymentSessionResponse

id

string · 필수

결제 세션 식별값입니다.

예시: pymt_sess-019f0000-0000-7000-9000-000000000000

status

string · enum · 필수

현재 결제 세션 상태입니다. processing이면 다시 조회하고, captured 또는 failed가 확인되면 결제 결과가 확정된 것입니다. expired는 결제 승인 기한이 지나 더 이상 결제할 수 없는 세션입니다.

허용 값:

created

identified

initiated

committed

processing

captured

failed

expired

예시: captured

clientId

string · 필수

결제 세션을 생성한 가맹점 클라이언트 식별값

예시: client-019f0000-0000-7000-9000-000000000001

amount

integer · min: 1 · 필수

VAT를 포함한 최종 결제 총액(원)

예시: 10000

currency

string · enum · 필수

결제 통화

허용 값:

KRW

supplyAmount

integer · min: 0 · 필수

과세 공급가액(원)

예시: 9091

taxFreeAmount

integer · min: 0 · 필수

총액에 포함된 면세 금액(원)

예시: 0

vat

integer · min: 0 · 필수

확정된 부가세 금액(원)

예시: 909

productName

string · 필수

결제 상품명

예시: 아메리카노 외 1건

tradeOpt

string · enum · 필수

현금영수증 분류

허용 값:

GENERAL

BOOK_CULTURE

PUBLIC_TRANSPORT

createdAt

string · date-time · 필수

결제 세션 생성 시각

예시: 2026-08-21T00:00:00.000Z

updatedAt

string · date-time · 필수

결제 세션 최종 수정 시각

예시: 2026-08-21T00:00:00.000Z

displayMerchantName

string

결제 UI에 표시되는 가맹점 상호명

예시: 포인트쓰리 스토어

payerId

string

본인인증 완료(identified 이상) 후 공개되는 결제자 식별자입니다.

예시: payer:00000000000000000000000000

결제 세션 생성

POST

https://api.point3.io

/payment/v3/session

가맹점 서버가 주문과 결제 금액을 확인한 뒤 결제창을 열기 전에 호출합니다. 매일 23:30 이상 다음 날 00:30 미만(Asia/Seoul)에는 EOB 점검으로 생성을 차단합니다. 차단된 요청은 세션을 저장하지 않습니다. 성공하면 생성된 결제 세션 리소스를 직접 반환합니다. 응답의 id는 sessionId로서 주문과 함께 저장하세요.

결제 세션 생성 › 요청 본문

CreatePaymentSessionRequest

amount

integer · 필수

사용자가 지불할 결제 총액입니다. 대한민국 원(KRW) 단위입니다.

예시: 10000

productName

string · 필수

결제창에 표시할 상품명입니다.

예시: 아메리카노 외 1건

displayMerchantName

string

결제 UI에 표시할 가맹점 상호명입니다. 미지정 시 productName 을 사용합니다.

예시: 포인트쓰리 스토어

vat

integer

부가세 금액입니다. 서버가 자동으로 계산하며, 수동 설정이 필요할 경우 지정합니다. 자세한 내용은 세금 처리를 확인하세요.

예시: 909

taxFreeAmount

integer

면세 금액입니다. 면세 상품의 경우 지정합니다. 자세한 내용은 세금 처리를 확인하세요.

예시: 0

기본값: 0

tradeOpt

string · enum

세금 처리를 위한 결제 분류입니다. 세법 상 도서·문화 또는 대중교통 분류 상품의 경우 지정합니다.

허용 값:

GENERAL

BOOK_CULTURE

PUBLIC_TRANSPORT

기본값: GENERAL

결제 세션 생성 › 응답

결제 세션 생성 성공

생성된 결제 세션 리소스입니다. 별도의 성공 응답 래퍼 없이 직접 반환됩니다.

CreatePaymentSessionResponse

id

string · 필수

결제 세션 식별값입니다. 가맹점 화면과 결제 세션 조회 요청에서 sessionId로 사용합니다.

예시: pymt_sess-019f0000-0000-7000-9000-000000000000

status

string · enum · 필수

생성 직후의 공개 결제 세션 상태

허용 값:

created

clientId

string · 필수

결제 세션을 생성한 가맹점 클라이언트 식별값

예시: client-019f0000-0000-7000-9000-000000000001

amount

integer · min: 1 · 필수

VAT를 포함한 최종 결제 총액(원)

예시: 10000

currency

string · enum · 필수

결제 통화

허용 값:

KRW

supplyAmount

integer · min: 0 · 필수

point3에서 계산한 과세 공급가액 입니다. 계산 규칙은 세금 처리를 확인하세요.

예시: 9091

taxFreeAmount

integer · min: 0 · 필수

총액에 포함된 면세 금액(원)

예시: 0

vat

integer · min: 0 · 필수

확정된 부가세 금액(원)

예시: 909

productName

string · 필수

결제 상품명

예시: 아메리카노 외 1건

tradeOpt

string · enum · 필수

현금영수증 분류입니다.

허용 값:

GENERAL

BOOK_CULTURE

PUBLIC_TRANSPORT

createdAt

string · date-time · 필수

결제 세션 생성 시각

예시: 2026-08-21T00:00:00.000Z

updatedAt

string · date-time · 필수

결제 세션 최종 수정 시각

예시: 2026-08-21T00:00:00.000Z

displayMerchantName

string

결제 UI에 표시되는 가맹점 상호명

예시: 포인트쓰리 스토어

POST/payment/v3/session

curl https://api.point3.io/payment/v3/session \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "amount": 10000,
  "productName": "아메리카노 외 1건",
  "displayMerchantName": "포인트쓰리 스토어"
}'

요청 본문 예시

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

json

application/json

응답 예시

{
  "id": "pymt_sess-019f0000-0000-7000-9000-000000000000",
  "status": "created",
  "clientId": "client-019f0000-0000-7000-9000-000000000001",
  "amount": 10000,
  "currency": "KRW",
  "supplyAmount": 9091,
  "taxFreeAmount": 0,
  "vat": 909,
  "taxationType": "TAXABLE",
  "productName": "아메리카노 외 1건",
  "displayMerchantName": "포인트쓰리 스토어",
  "tradeOpt": "GENERAL",
  "createdAt": "2026-08-21T00:00:00.000Z",
  "updatedAt": "2026-08-21T00:00:00.000Z"
}

json

application/json

결제 승인

POST

https://api.point3.io

/capture/v2/{sessionId}

가맹점 화면이 successUrl로 이동한 뒤 가맹점 서버가 호출합니다. 결제가 커밋된 날의 다음 날 00:00(KST)부터는 승인할 수 없습니다.

주문의 최종 결제 결과는 응답의 status 또는 결제 세션 조회 API를 호출하여 확인하세요.

실패가 확정된 경우에도 HTTP 200을 반환합니다. status가 failed이면 outcome.code로 사유를 구분하세요. outcome.message 문구는 바뀔 수 있으므로 분기 조건으로 쓰지 마세요.

`outcome.code`	`outcome.type`	의미	처리
`PAYMENT_METHOD_DECLINED`	`declined`	결제수단 승인 거절. 잔액 부족, 출금 가능 잔액 부족 등	잔액 확인 또는 다른 계좌 선택 안내
`PAYMENT_METHOD_LIMIT_EXCEEDED`	`failed`	이체한도 초과	이체한도 확인 또는 다른 계좌 선택 안내
`PAYMENT_CAPTURE_REJECTED`	`rejected`	세부 사유가 분류되지 않은 이체 실패	주문·결제 상태 확인, 필요하면 문의
`PAYMENT_CAPTURE_ALREADY_FAILED`	`failed`	이미 실패한 결제를 다시 승인 요청함. 원래 사유는 포함되지 않음	처음 받은 실패 응답의 기록 확인

처음 받은 실패 응답의 outcome.code를 주문·sessionId와 함께 저장하고, 이후 응답으로 덮어쓰지 마세요.

HTTP 202(status: processing)는 아직 처리 중이라는 뜻이며 실패가 아닙니다. 응답을 받지 못했을 때와 같이 sessionId로 결제 세션을 조회해 결과를 확인하세요.

결제 승인 › 경로 파라미터

sessionId

string · 필수

결제 세션 생성 응답으로 받은 현재 주문의 세션 식별값

결제 승인 › 응답

승인 완료 또는 확정된 실패

결제 승인 요청이 완료된 결과입니다.

CapturePaymentResponse

id

string · 필수

결제 세션 식별값입니다.

예시: pymt_sess-019f0000-0000-7000-9000-000000000000

object

string · enum · 필수

응답 객체 종류

허용 값:

paymentCapture

예시: paymentCapture

status

string · enum · 필수

승인 요청의 결과 상태. failed는 확정된 실패입니다.

허용 값:

captured

failed

object · 필수

committedAt

string · date · 필수

결제 커밋 기준일(KST)

예시: 2026-08-21

에러 코드 결제 취소