Refunds

환불은 주문에 대해 발행해요.
금액을 생략하면 잔액 전액을, 금액을 주면 그만큼 부분 환불해요.
환불은 PG사를 거쳐 실제 결제 취소까지 처리한 뒤 응답해요.

환불 발행

POSThttps://api.payri.kr/v1/orders/refundscope refunds:write


curl -X POST https://api.payri.kr/v1/orders/refund \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "ord_3kf9a2", "amount": 5000, "reason": "부분 환불 요청" }'

요청 본문

필드	타입	필수	설명
`orderId`	string	✅	환불할 주문 ID
`amount`	int (≥1)	—	환불 금액(KRW). 생략하면 잔액 전액 환불
`reason`	string	—	환불 사유. 환불 이력에 기록돼요

응답

갱신된 주문이 돌아와요.
부분 환불이면 status는 paid로 유지되고 refundedAmount만 누적돼요.
잔액이 0이 되면 status가 refunded로 바뀌어요.


{
  "id": "ord_3kf9a2",
  "amount": 19000,
  "currency": "KRW",
  "status": "paid",
  "refundedAmount": 5000,
  "refunds": [
    { "amount": 5000, "at": "2026-06-17T09:00:00.000Z", "reason": "부분 환불 요청" }
  ]
}

환불이 발행되면 order.refunded 웹훅이 전송돼요.
같은 이벤트가 여러 번 도착할 수 있으니 멱등 처리를 해두세요.

환불 가능 조건

다음 조건을 모두 만족해야 환불할 수 있어요.

주문 상태가 paid일 것 (미결제·실패·전액 환불된 주문은 불가)
구매 확정되지 않은 주문일 것
아직 정산 회차에 포함되지 않은 주문일 것
환불 금액이 잔여 환불 가능액 이내일 것

관련 에러

코드	HTTP	상황
`ORDER_NOT_FOUND`	404	주문이 없거나 키의 상품 범위 밖
`REFUND_NOT_PAID`	409	`paid` 상태가 아닌 주문
`REFUND_CONFIRMED`	409	구매 확정된 주문
`REFUND_SETTLED`	409	이미 정산 회차에 포함된 주문
`REFUND_NONE_LEFT`	409	남은 환불 가능 금액이 없음
`REFUND_AMOUNT_INVALID`	400	환불 금액이 0 이하
`REFUND_EXCEEDS`	400	잔여 환불 가능액 초과
`REFUND_IN_PROGRESS`	409	같은 주문에 처리 중인 환불이 있음. 잠시 후 재시도

REFUND_IN_PROGRESS는 앞선 환불 요청이 PG 처리 중이라는 뜻이에요.
같은 요청을 곧바로 다시 보내지 말고, 잠시 뒤 주문을 조회해 환불 반영 여부를 확인한 다음 재시도하세요.