---
title: "Get Payment"
method: GET
path: "/v1/payments/{payment_id}"
tags: ["Billing Payments"]
---

# Get Payment

`GET /v1/payments/{payment_id}`

## 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/payments/{payment_id}`
- 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`)

결제 단건 조회.

## Path parameters

- `payment_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

- `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 입니다.

## Response `200`

Successful Response

- PaymentResponse: 결제 단일 객체 응답. SCHEMA → DTO 매핑: - `payments.id` → `payment_id`. - `organization_id/invoice_id/subscription_id/payment_method_id/env_scope/ provider/provider_payment_id/amount_minor/currency/status/failure_code/ failure_reason/requested_at/confirmed_at/created_at` → 직접 매핑. - `metadata`/`updated_at`는 외부 노출 X. - `invoice_number` 는 payments 행의 칸이 아니다 - 결제 조회 서비스(`PaymentQueryService`)가 `invoices.invoice_number` 를 일괄 조회로 읽어 얹는다(청구서가 없으면 null). 정책 위험 강제 잠금: - **`failure_reason`은 서비스 계층이 PG 원문을 사용자 안전 문자열로 정규화하여 set한 값만 들어와야 한다**. PG raw 응답을 그대로 전달하면 시크릿/내부 IP/스택트레이스 누설 사고로 분류된다. - `provider_payment_id`는 PG 트랜잭션 식별자. BFF/관리자/환불 입력용으로 노출하되 외부 사용자 UI 표시 권장 X.
  - `payment_id` integer, required: payments.id.
  - `organization_id` integer, required: 소유 조직 PK.
  - `invoice_id` integer, nullable: 연결된 인보이스 ID (선택).
  - `invoice_number` string, nullable: 연결된 청구서의 번호 'INV-YYYYMM-XXXXXX' - 청구서 목록의 번호와 같은 값이라 고객이 문의할 때 한 이름으로 부른다. 청구서가 없으면 null. 결제 조회(GET /v1/payments · /v1/payments/{id})가 읽어서 채운다 - 결제 행에는 없는 값이라 그 밖의 경로가 돌려주는 결제 객체에서는 비어 있을 수 있다.
  - `subscription_id` integer, nullable: 연결된 구독 ID (선택).
  - `payment_method_id` integer, nullable: 사용된 결제수단 ID (선택).
  - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
  - `pg_provider` 'portone' | 'toss' | 'payup' | 'offline', required: PG 사업자.
  - `provider_payment_id` string, nullable: PG 발급 결제 식별자 (imp_uid 등). BFF/관리자/환불 입력용. INITIATED 시점에는 NULL일 수 있다.
  - `amount_minor` integer, required: 결제 금액 (minor unit). 0 과 음수는 받지 않는다.
  - `currency` 'KRW', required: 통화 코드. v1=KRW.
  - `status` 'INITIATED' | 'PENDING' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' | 'EXPIRED', required: 결제 상태 (6값 enum).
  - `failure_code` string, nullable: 결제 실패 코드 (FAILED 상태에서 채워짐). SCHEMA는 PG 원문 허용하나 서비스 계층이 정규화된 안전 문자열로 set 책임.
  - `failure_reason` string, nullable: 결제 실패 사유. **서비스 계층이 PG 원문을 사용자 안전 문자열로 정규화한 값만 set 가능**. raw 원문 직접 노출 금지.
  - `requested_at` string, date-time, required: 결제 요청 시각 (aware datetime, naive 입력 시 422).
  - `confirmed_at` string, date-time, nullable: 결제 확정 시각 (SUCCEEDED 진입 시 채워짐).
  - `created_at` string, date-time, required: 결제 행 생성 시각 (aware datetime, naive 입력 시 422).

## 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)