Billing Refunds

Create Refund

환불 요청.

post/v1/refunds

Request

  • Base URL: https://api.xdata.kr (the document declares no server; this is the origin it was published from)
  • URL: https://api.xdata.kr/v1/refunds
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://api.xdata.kr/oauth/authorize, token URL https://api.xdata.kr/oauth/token)

Query parameters

env_scope'production' | 'real_test' | 'sandbox' nullable

환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

Headers

Idempotency-Keystring required
Authorizationstring nullable
X-Env-Scope'production' | 'real_test' | 'sandbox' nullable

환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

Request body

payment_idinteger required

환불 대상 결제 ID (payments.id). status='SUCCEEDED'만 허용하고 무통장 입금 결제는 받지 않는다(422).

amount_minorinteger required

환불 금액 (minor unit 정수). 0 과 음수는 받지 않는다. 전액/부분 모두 허용. 환불 합산 ≤ 원 결제 amount_minor는 서비스 계층 검증.

reason'USER_REQUEST' | 'OPS_DISPUTE_RESOLUTION' | 'DUPLICATE_PAYMENT' | 'PAYMENT_FAILED_REVERSAL' | 'FRAUDULENT_PAYMENT' | 'OTHER' nullable

환불 사유 enum. 미지정이면 기본값 없이 저장하고 응답 reason 은 null (note 만 있으면 그 글만 저장).

notestring nullable

운영 메모(자유 텍스트). SCHEMA refunds.reason VARCHAR(255) 컬럼에 reason enum과 함께 합성 저장(서비스 계층 책임). PII/secret 금지.

cancel_subscriptionboolean

동일 트랜잭션에서 구독 CANCELED 전이 여부. True 시 subscriptions.status='CANCELED'로 전이 + audit_logs.billing.subscription.transition 적재.

metadataobject nullable

운영 메타데이터 (예: source, dispute_id, support_ticket_id). PII/secret 적재 금지. 키 화이트리스트는 별도 결정.

Response

Successful Response

refund_idinteger required

refunds.id (BIGSERIAL PK).

payment_idinteger required

원 결제 ID (payments.id).

amount_minorinteger required

환불 금액 (minor unit). 0 과 음수는 받지 않는다.

status'PENDING' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' required

환불 상태. 본 응답은 보통 PENDING(202 Accepted).

env_scope'sandbox' | 'real_test' | 'production' required

환경 스코프. 모든 응답에 일관되게 노출한다(환경 식별 + 감사 일관성).

requested_atstring date-time required

환불 요청 시각 (aware datetime, naive 입력 시 422).

Changes

No recorded changes to this operation across all 1 revision of this API.