---
title: "Start a card registration"
method: POST
path: "/v1/payment-methods/payup-hub/registrations"
tags: ["Billing Payment Methods", "Billing Payment Methods"]
---

# Start a card registration

`POST /v1/payment-methods/payup-hub/registrations`

## 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/payup-hub/registrations`
- 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`)

자동결제 카드 등록을 시작한다 - 고객이 동의하면 카드등록창을 여는 값을 돌려준다.

카드 정보는 이 API 를 지나지 않는다. 고객은 결제대행사의 창에서 직접 입력하고, 결과는 서버가 받아 결제수단을 만든다.
같은 `Idempotency-Key` 로 다시 부르면 같은 등록을 돌려준다. 결과는 등록 상태 조회로 안다.

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

- PayupHubCardRegistrationStartRequest: 카드 등록 시작 요청. 카드 칸이 없다.
  - `organization_id` integer, required: 결제수단 소유 조직 PK. 주체 조직과 일치해야 한다.
  - `label` string, nullable: 사용자 표시 라벨.
  - `consent` RegistrationConsent, required: 매달 자동 청구 · 해지 방법 고지에 동의했다는 표시.
    - `accepted` true, required: 첫 결제 뒤에는 고객이 인지하지 못한 채 결제되므로 반드시 고지해야 한다 - 동의했을 때만 시작할 수 있다. 동의 시각은 서버가 잰다.
    - `text_version` string, required: 고객이 본 고지 · 동의 문안의 판. 어떤 문장에 동의했는지 나중에 대조하려고 남긴다.
  - `user_agent` 'PC' | 'MW', required: 카드등록창을 여는 환경(PC 웹 · 모바일 웹).

## Response `201`

Successful Response

- PayupHubCardRegistrationStartResponse: 카드 등록 시작 응답 - 호스팅창을 여는 데 필요한 값.
  - `registration_id` string, required: 등록의 불투명 식별자. 상태 조회에 쓴다.
  - `status` 'PENDING', required: 시작 직후는 항상 PENDING.
  - `sdk_url` string, required: 카드등록창 스크립트 주소. 서버가 준다(시험과 운영이 다르다).
  - `form` object, required: 창을 여는 폼의 숨은 입력 값. **그대로** 폼에 넣는다(키 이름 포함). `ReturnURL` 은 서버가 만든 복귀 주소다.
  - `expires_at` string, date-time, required: 이 시각이 지나면 등록은 EXPIRED 가 된다.

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