point3
서버 연동 레퍼런스
서버 연동 레퍼런스

Schemas

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에 표시되는 가맹점 상호명

예시: 포인트쓰리 스토어

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

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

CapturePaymentProcessingResponse

현재 결제 승인 요청의 이체가 처리 중인 결과입니다.
id
​string · 필수

결제 세션 식별값

object
​string · enum · 필수
허용 값:
paymentCapture
status
​string · enum · 필수
허용 값:
processing
​object · 필수
committedAt
​string · date · 필수

결제 커밋 기준일(KST)

CaptureInvalidRequestErrorResponse

​object · 필수

CaptureAuthenticationErrorResponse

​object · 필수

CapturePermissionErrorResponse

​object · 필수

CaptureNotFoundErrorResponse

​object · 필수

CaptureExpiredErrorResponse

​object · 필수

CaptureApiErrorResponse

​object · 필수

CreatePaymentRefundRequest

취소할 금액과 세금 구성을 입력합니다.
refundAmount
​integer · min: 1 · max: 9007199254740991 · 필수

취소할 총 금액

예시: 10000
refundTaxFreeAmount
​integer · min: 0 · max: 9007199254740991 · 필수

취소 금액에 포함된 면세 금액

예시: 0
refundVat
​integer · min: 0 · max: 9007199254740991 · 필수

취소 금액에 포함된 부가세

예시: 909
reason
​string · maxLength: 200 · 필수

취소 사유

예시: 고객 요청

PaymentRefundResponse

id
​string · 필수

생성된 환불 항목 식별값

paymentSessionId
​string · 필수

원 결제 세션 식별값

clientId
​string · 필수

가맹점 클라이언트 식별값

productName
​string | null · 필수

원 결제 상품명

status
​string · enum · 필수
허용 값:
completed
amount
​integer · 필수

완료된 취소 금액

currency
​string · enum · 필수
허용 값:
KRW
taxFreeAmount
​integer · 필수

완료된 취소의 면세 금액

vat
​integer · 필수

완료된 취소의 부가세 금액

fee
​integer · 필수

취소 처리 수수료

reason
​string | null · 필수

취소 사유

createdAt
​string · date-time · 필수
updatedAt
​string · date-time · 필수

PaymentRefundFailure

code
​string · enum · 필수

취소 실패 코드

허용 값:
refundMethodDeclined
refundMethodUnavailable
refundServiceUnavailable
refundRejected
refundFailed
message
​string · 필수

취소 실패 설명

PaymentRefundEntry

id
​string · 필수

개별 취소 항목 식별값

status
​string · enum · 필수
허용 값:
processing
completed
failed
amount
​integer · 필수

개별 취소 총액

currency
​string · enum · 필수
허용 값:
KRW
taxFreeAmount
​integer · 필수

개별 취소의 면세 금액

vat
​integer · 필수

개별 취소의 부가세 금액

fee
​integer · 필수

개별 취소 처리 수수료

reason
​string | null · 필수

취소 사유

failure
​PaymentRefundFailure · 필수
createdAt
​string · date-time · 필수
updatedAt
​string · date-time · 필수

PaymentRefundStatusResponse

paymentSessionId
​string · 필수

원 결제 세션 식별값

clientId
​string · 필수

가맹점 클라이언트 식별값

status
​string · enum · 필수

결제 세션 단위의 전체 취소 상태

허용 값:
refundable
processing
partiallyRefunded
fullyRefunded
originalAmount
​integer · 필수

원 결제 총액

currency
​string · enum · 필수
허용 값:
KRW
refundableAmount
​integer · 필수

현재 추가로 취소할 수 있는 금액

productName
​string | null · 필수

원 결제 상품명

canCreateRefund
​boolean · 필수

새 취소 요청 가능 여부

​PaymentRefundEntry[] · 필수

개별 취소 이력

PaymentSessionErrorResponse

​object · 필수

CreateDelegationRequest

payer_id
​string · maxLength: 128 · pattern: ^payer: · 필수

로그인한 회원의 payerId입니다. 호출한 가맹점 소속의 활성 구매자여야 합니다.

예시: payer:00000000000000000000000000

CreateDelegationResponse

delegation_id
​string · 필수

위임 인증 식별값입니다.

예시: dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw
expires_in
​integer · 필수

위임 인증의 유효 시간(초)입니다.

예시: 300
authorization_url
​string · uri · 필수

결제창에 전달할 URL입니다. 값을 바꾸지 말고 widgets()의 brandpay.redirectUrl로 그대로 전달하세요.

예시: https://auth.point3.io/delegated?delegation_id=dlg_3q2-7wE9bXk1Lr0Zt8pVnYc4uJmHs6aQfGdOiKe5NBw

ErrorResponse

status
​integer · 필수
timestamp
​string · date-time · 필수
​object · 필수