---
title: "Prepare Checkout"
method: POST
path: "/v1/subscriptions/payup-standard/prepare"
tags: ["Billing Standard Checkout"]
---

# Prepare Checkout

`POST /v1/subscriptions/payup-standard/prepare`

## 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/payup-standard/prepare`
- 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`)

서버가 금액을 확정하고 서명한다 (DB 쓰기 0건).

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

## Request body

- StandardCheckoutPrepareRequest: 결제창을 열기 전에 서버가 값을 확정한다 (금액을 클라이언트가 정하지 못하게). 갈래를 요청 DTO 여럿으로 나누지 않는 이유: 결제창을 여는 절차와 승인 절차가 갈래마다 완전히 같고, 다른 것은 금액을 어디서 계산하느냐 하나뿐이다. `mode` 를 주면 그 갈래다. 생략하면 `subscription_id` 유무로 정한다(없으면 신규 구독, 있으면 추가 상품) — 재시도만은 생략으로 도달할 수 없다. 추측으로 열리면 안 되는 갈래이기 때문이다 (`CheckoutMode` 참고).
  - `organization_id` integer, required: 결제 주체 조직 PK.
  - `plan_id` integer, required: plans.id.
  - `addon_product_ids` integer[], nullable: 함께 구매할 추가 상품 api_products.id 목록.
  - `payer_name` string, required: 결제창에 표시할 결제자명.
  - `subscription_id` integer, nullable: 대상 구독. 추가 상품을 더하거나(기본) 실패한 결제를 다시 시도할 때 필수.
  - `mode` 'subscription' | 'addon' | 'retry', nullable: 결제 갈래를 명시한다. 생략하면 subscription_id 유무로 정한다. 'retry' 는 결제가 실패한 구독의 미결제 금액을 다시 내는 갈래.

## Response `200`

Successful Response

- StandardCheckoutPrepareResponse: 결제창을 띄우는 데 필요한 값 + 서버가 서명한 체크아웃 토큰. `checkout_token` 은 승인 단계에서 **서버가 정한 금액·상품** 을 되찾는 열쇠다. 금액을 응답에도 함께 싣는 이유는 고객에게 보여 주기 위해서이고, 승인 때 믿는 값은 토큰 안의 것뿐이다.
  - `merchant_id` string, required: 결제창이 요구하는 가맹점 식별자(시크릿 아님).
  - `sdk_url` string, required: 결제창 스크립트 주소.
  - `item_name` string, required: 결제창에 표시할 상품명.
  - `amount` integer, required: 결제 금액 (minor unit).
  - `currency` 'KRW', required: 통화 코드.
  - `order_number` string, required: 우리 주문번호.
  - `checkout_token` string, required: 서버 서명 체크아웃 토큰.
  - `return_url` string, 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)