---
title: "Pay a PAYMENT_FAILED subscription's open invoice again with its attached card"
method: POST
path: "/v1/subscriptions/{subscription_id}/payment-retry"
tags: ["Billing Subscriptions"]
---

# Pay a PAYMENT_FAILED subscription's open invoice again with its attached card

`POST /v1/subscriptions/{subscription_id}/payment-retry`

## 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/subscriptions/{subscription_id}/payment-retry`
- 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`)

붙은 카드로 그 구독의 미결제 청구서 한 장을 청구한다 - 구독 생성과 같은 권한(OWNER · ADMIN 또는 운영자).

load -> 멱등 시작(+재생) -> T1(결제 만들기) COMMIT -> T2(PG) -> 멱등 완료 순서다. 카드 거절은 402 `PAYMENT_PG_DECLINED`, 결제대행 일시 오류 · 우리 쪽 사유 ·
보내기 전 설정 오류는 503 `PAYMENT_PG_UNAVAILABLE`(구독 생성 · 추가 상품 문과 같은 분류 · 문장), 결과를 모르는 승인은 200 + `payment_status: PENDING` 이다(오류가 아니다).

## Path parameters

- `subscription_id` integer, required

## 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-Key` string, required
- `Authorization` string, 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

- SubscriptionPaymentRetryRequest: 다시 결제 요청 - 화면이 보여 준 카드 번호 하나.
  - `payment_method_id` integer, required: 화면이 고객에게 보여 준 결제수단 id. 구독에 **지금 붙은** 결제수단과 같아야 한다 - 다르면 청구하지 않고 거절한다(고객이 본 카드로만 청구).

## Response `200`

Successful Response

- SubscriptionPaymentRetryResponse: 쓰기 응답 - 거절(FAILED)은 응답이 아니라 402 오류로 온다. `payment_status` 가 PENDING 이면 **결과를 모르는 승인**이거나 웹훅을 기다리는 청구다 - 실패로 적지 않는다(카드사에서는 승인됐을 수 있다). 그때 `subscription_status` 는 PAYMENT_FAILED 그대로이고, 읽기는 PAYMENT_IN_PROGRESS 로 닫힌다.
  - `subscription_id` integer, required
  - `organization_id` integer, required
  - `invoice_id` integer, required
  - `payment_id` integer, required
  - `payment_status` 'SUCCEEDED' | 'PENDING', required
  - `subscription_status` 'PENDING' | 'ACTIVE' | 'PAUSED' | 'CANCELED' | 'EXPIRED' | 'PAYMENT_FAILED', required: 이 응답 시점의 구독 상태. 자동결제(HUB)는 성공이 같은 요청 안에서 ACTIVE 로 돌린다.
  - `amount_minor` integer, required
  - `currency` 'KRW', required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)