결제 취소

승인 완료된 결제를 가맹점 서버에서 전부 또는 일부 취소합니다.

결제 취소 상태 조회

GET

https://api.point3.io

/refunds/v1/{sessionId}

결제 세션의 취소 상태, 취소 이력과 취소 가능 금액을 조회합니다. 취소 요청의 응답을 받지 못했거나 결과가 확실하지 않을 때 사용하세요.

결제 취소 상태 조회 › 경로 파라미터

sessionId

string · 필수

승인 완료된 원 결제의 세션 식별값

결제 취소 상태 조회 › 응답

결제 취소 상태 조회 성공

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[] · 필수

개별 취소 이력

GET/refunds/v1/{sessionId}

curl https://api.point3.io/refunds/v1/:sessionId \
  --header 'Authorization: Bearer <token>'

응답 예시

{
  "paymentSessionId": "pymt_sess-019f0000-0000-7000-9000-000000000000",
  "clientId": "client-019f0000-0000-7000-9000-000000000001",
  "status": "partiallyRefunded",
  "originalAmount": 10000,
  "currency": "KRW",
  "refundableAmount": 5000,
  "productName": "아메리카노 외 1건",
  "canCreateRefund": true,
  "refunds": [
    {
      "id": "ref-019f0000-0000-7000-9000-000000000000",
      "status": "completed",
      "amount": 5000,
      "currency": "KRW",
      "taxFreeAmount": 0,
      "vat": 455,
      "fee": 100,
      "reason": "고객 요청",
      "failure": null,
      "createdAt": "2026-08-21T00:00:00.000Z",
      "updatedAt": "2026-08-21T00:00:01.000Z"
    }
  ]
}

json

application/json

결제 취소

POST

https://api.point3.io

/refunds/v1/{sessionId}

승인 완료된 결제를 전부 또는 일부 취소합니다. 세금을 자동으로 계산하지 않으므로 refundAmount, refundTaxFreeAmount, refundVat를 모두 지정해야 합니다. 취소 결과가 확실하지 않으면 취소 상태 조회 API로 확인하세요.

결제 취소 › 경로 파라미터

sessionId

string · 필수

승인 완료된 원 결제의 세션 식별값

결제 취소 › 헤더

Idempotency-Key

string · maxLength: 300

24시간 동안 같은 취소 요청의 중복 처리를 막는 선택 값입니다.

결제 취소 › 요청 본문

취소할 금액과 세금 구성을 입력합니다.

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 · 필수

POST/refunds/v1/{sessionId}

curl https://api.point3.io/refunds/v1/:sessionId \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "refundAmount": 10000,
  "refundTaxFreeAmount": 0,
  "refundVat": 909,
  "reason": "고객 요청"
}'

요청 본문 예시

{
  "refundAmount": 10000,
  "refundTaxFreeAmount": 0,
  "refundVat": 909,
  "reason": "고객 요청"
}

json

application/json

응답 예시

{
  "id": "ref-019f0000-0000-7000-9000-000000000000",
  "paymentSessionId": "pymt_sess-019f0000-0000-7000-9000-000000000000",
  "clientId": "client-019f0000-0000-7000-9000-000000000001",
  "productName": "아메리카노 외 1건",
  "status": "completed",
  "amount": 10000,
  "currency": "KRW",
  "taxFreeAmount": 0,
  "vat": 909,
  "fee": 100,
  "reason": "고객 요청",
  "createdAt": "2026-08-21T00:00:00.000Z",
  "updatedAt": "2026-08-21T00:00:01.000Z"
}

json

application/json

결제 취소 처리 재개

POST

https://api.point3.io

/refunds/v1/{sessionId}/resume

processing 상태인 취소 처리를 재개합니다. 먼저 취소 상태를 조회하고 처리 중인 취소가 있을 때만 호출하세요.

결제 취소 처리 재개 › 경로 파라미터

sessionId

string · 필수

원 결제의 세션 식별값

결제 취소 처리 재개 › 응답

결제 취소 처리 재개 성공

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[] · 필수

개별 취소 이력

POST/refunds/v1/{sessionId}/resume

curl https://api.point3.io/refunds/v1/:sessionId/resume \
  --request POST \
  --header 'Authorization: Bearer <token>'

응답 예시

{
  "paymentSessionId": "paymentSessionId",
  "clientId": "clientId",
  "status": "refundable",
  "originalAmount": 0,
  "currency": "KRW",
  "refundableAmount": 0,
  "productName": "productName",
  "canCreateRefund": true,
  "refunds": [
    {
      "id": "id",
      "status": "processing",
      "amount": 0,
      "currency": "KRW",
      "taxFreeAmount": 0,
      "vat": 0,
      "fee": 0,
      "reason": "reason",
      "failure": {
        "code": "refundMethodDeclined",
        "message": "message"
      },
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z"
    }
  ]
}

json

application/json

결제 위임 인증