---
title: "Register Payment Method"
method: POST
path: "/v1/payment-methods"
tags: ["Billing Payment Methods"]
---

# Register Payment Method

`POST /v1/payment-methods`

## 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/payment-methods`
- 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-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

- PaymentMethodRegisterRequest: 결제수단 등록 요청. 클라이언트는 PG SDK로 카드 토큰화를 마친 뒤 `billing_key`만 본 API로 전달한다. 평문 카드정보(PAN/CVV/유효기간)는 절대 전송되지 않으며, 위반 시 422 VALIDATION_* + 보안 사고로 분류된다. `organization_id`는 요청 주체의 `PrincipalContext.organization_id`와 일치해야 하며, 불일치 시 라우트 계층에서 `403 AUTHZ_FORBIDDEN`을 반환한다(본 DTO는 입력 형식만 검증).
  - `organization_id` integer, required: 결제수단 소유 조직 PK. 주체 조직과 일치 강제(라우트 검증).
  - `method_kind` 'CARD' | 'VBANK' | 'MOBILE' | 'SIMPLE' | 'PAYPAL' | 'OTHER', required: 결제수단 종류. v1은 CARD 우선.
  - `pg_provider` 'portone' | 'toss' | 'payup' | 'offline', required: PG 사업자. v1=portone.
  - `billing_key` string, required: PG 빌링키(토큰). PG SDK 토큰화 결과만 허용. 평문 카드정보 전송 금지. repr=False로 로그/디버그 노출 차단.
  - `label` string, nullable: 사용자 표시 라벨 (예: "신한카드 1234").
  - `last4` string, nullable: 마스킹 표시용 마지막 자리(평문 카드번호 아님).
  - `issuer_name` string, nullable: 발급사 명칭 (예: 신한카드, 국민카드).
  - `expires_at` string, date-time, nullable: 카드/수단 만료 시각 (TIMESTAMPTZ). AwareDatetime: naive 입력 시 422 VALIDATION_REQUEST_INVALID.

## Response `201`

Successful Response

- PaymentMethodResponse: 결제수단 단일 객체 응답. `billing_key` 필드 부재가 본 응답 모델의 가장 중요한 정합 강제 — 응답 직렬화 시 평문 PG 토큰이 절대 외부로 노출되지 않는다 - 전송 금지와 저장 금지를 함께 지킨다. SCHEMA → DTO 매핑: - `payment_methods.id` → `payment_method_id`. - `organization_id/method_kind/provider/label/last4/issuer_name/status/expires_at/created_at` → 직접 매핑. - `billing_key/metadata/updated_at/deleted_at`는 외부 노출 X.
  - `payment_method_id` integer, required: payment_methods.id (BIGSERIAL PK).
  - `organization_id` integer, required: 소유 조직 PK.
  - `method_kind` 'CARD' | 'VBANK' | 'MOBILE' | 'SIMPLE' | 'PAYPAL' | 'OTHER', required: 결제수단 종류.
  - `pg_provider` 'portone' | 'toss' | 'payup' | 'offline', required: PG 사업자.
  - `label` string, nullable: 사용자 표시 라벨.
  - `last4` string, nullable: 마스킹 마지막 자리.
  - `issuer_name` string, nullable: 발급사 명칭.
  - `status` 'ACTIVE' | 'REVOKED' | 'EXPIRED', required: 결제수단 상태.
  - `env_scope` 'sandbox' | 'real_test' | 'production', required: 환경 스코프.
  - `expires_at` string, date-time, nullable: 만료 시각 (aware datetime, naive 입력 시 422).
  - `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)