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

organization_idinteger required

결제수단 소유 조직 PK. 주체 조직과 일치 강제(라우트 검증).

method_kind'CARD' | 'VBANK' | 'MOBILE' | 'SIMPLE' | 'PAYPAL' | 'OTHER' required

결제수단 종류. v1은 CARD 우선.

pg_provider'portone' | 'toss' | 'payup' | 'offline' required

PG 사업자. v1=portone.

billing_keystring required

PG 빌링키(토큰). PG SDK 토큰화 결과만 허용. 평문 카드정보 전송 금지. repr=False로 로그/디버그 노출 차단.

labelstring nullable

사용자 표시 라벨 (예: "신한카드 1234").

last4string nullable

마스킹 표시용 마지막 자리(평문 카드번호 아님).

issuer_namestring nullable

발급사 명칭 (예: 신한카드, 국민카드).

expires_atstring date-time nullable

카드/수단 만료 시각 (TIMESTAMPTZ). AwareDatetime: naive 입력 시 422 VALIDATION_REQUEST_INVALID.

Response

Successful Response

payment_method_idinteger required

payment_methods.id (BIGSERIAL PK).

organization_idinteger required

소유 조직 PK.

method_kind'CARD' | 'VBANK' | 'MOBILE' | 'SIMPLE' | 'PAYPAL' | 'OTHER' required

결제수단 종류.

pg_provider'portone' | 'toss' | 'payup' | 'offline' required

PG 사업자.

labelstring nullable

사용자 표시 라벨.

last4string nullable

마스킹 마지막 자리.

issuer_namestring nullable

발급사 명칭.

status'ACTIVE' | 'REVOKED' | 'EXPIRED' required

결제수단 상태.

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

환경 스코프.

expires_atstring date-time nullable

만료 시각 (aware datetime, naive 입력 시 422).

created_atstring date-time required

등록 시각 (aware datetime, naive 입력 시 422).

Changes

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