> ## Documentation Index > Fetch the complete documentation index at: https://docs.headlesscommerce.io/llms.txt > Use this file to discover all available pages before exploring further. # 결제 (장바구니 → 주문 + 결제) ## OpenAPI ````yaml openapi.ko.yaml post /storefront/carts/{id}/checkout openapi: 3.1.0 info: title: Headless Commerce API description: > Headless Commerce as a Service — REST API 명세서. ## 인증 모든 요청에 API 키를 Bearer 토큰으로 전달하세요. - **Secret Key** (`sk_live_*`, `sk_test_*`): 서버 사이드. Admin + Storefront API 전체 접근 가능. - **Publishable Key** (`pk_live_*`, `pk_test_*`): 클라이언트 사이드. Storefront API만 접근 가능. ## 고객 인증 (Storefront) 고객 식별이 필요한 Storefront 엔드포인트 (/storefront/customers/*, /storefront/orders/*)는 `X-Customer-Token` 헤더가 필요합니다. 1. 백엔드에서 `sk_*` 키로 `POST /admin/customers/{id}/token`을 호출하여 토큰 발급 2. 프론트엔드에서 `pk_*` 키 + `X-Customer-Token` 헤더와 함께 요청 전송 ## 페이지네이션 커서 기반 페이지네이션을 사용합니다. - `limit`: 페이지 크기 (기본 20, 최대 100) - `starting_after`: 이 ID 이후의 결과 반환 - 응답에 `has_more`와 `next_cursor` 포함 ## 금액 모든 금액은 최소 통화 단위의 정수입니다 (KRW=원, USD=센트). ## 속도 제한 모든 응답에 다음 헤더가 포함됩니다: - `X-RateLimit-Limit`: 분당 최대 요청 수 (플랜별: Free 100, Starter 500, Pro 2000, Enterprise 10000) - `X-RateLimit-Remaining`: 현재 윈도우의 남은 요청 수 - 초과 시 `429 Too Many Requests` 반환 ## 멱등성 결제/주문 관련 POST 요청에 `Idempotency-Key` 헤더를 포함하면 동일한 키의 중복 요청에 대해 원래 응답을 반환합니다. 권장 대상: checkout, refund, payment 생성 version: 1.0.0 contact: name: Headless Commerce Support url: https://headlesscommerce.io servers: - url: https://api.headlesscommerce.io/v1 description: 프로덕션 - url: https://api.headlesscommerce.io/v1 description: 테스트 (동일 URL, 테스트 API 키) security: - BearerAuth: [] tags: - name: Storefront - Products description: 구매자를 위한 상품 조회 - name: Storefront - Cart description: 장바구니 관리 및 결제 - name: Storefront - Orders description: 주문 조회 (본인 주문) - name: Storefront - Customers description: 고객 프로필 (본인 프로필) - name: Storefront - Shipping description: 배송 방법 조회 - name: Admin - Products description: 상품 관리 - name: Admin - Variants description: 변형(Variant) 관리 - name: Admin - Categories description: 카테고리 관리 - name: Admin - Collections description: 컬렉션 관리 - name: Admin - Inventory description: 재고 관리 - name: Admin - Orders description: 주문 관리 - name: Admin - Fulfillments description: 출고 관리 - name: Admin - Customers description: 고객 관리 - name: Admin - Discounts description: 할인 관리 - name: Admin - Shipping Methods description: 배송 방법 관리 - name: Admin - Webhooks description: 웹훅 관리 - name: Admin - Store description: 스토어 설정 - name: Admin - Settings description: API 키, 조직 및 팀 관리 - name: Admin - Returns description: 반품 관리 - name: Admin - Regions description: 리전, 다국어 및 환율 관리 - name: Admin - Dashboard description: 대시보드 통계 - name: Admin - Logs description: API 로그 조회 - name: Admin - Uploads description: 파일 업로드 - name: Storefront - Returns description: 고객 반품 요청 및 조회 - name: Storefront - Customer Auth description: 고객 회원가입 및 로그인 - name: Storefront - Payments description: 결제 확인 - name: OAuth description: OAuth 2.1 인가 코드 플로우 (PKCE 지원) - name: Auth description: 대시보드 사용자 비밀번호 재설정 - name: Admin - CSV description: 대량 CSV 가져오기 및 내보내기 paths: /storefront/carts/{id}/checkout: post: tags: - Storefront - Cart summary: 결제 (장바구니 → 주문 + 결제) parameters: - $ref: '#/components/parameters/ResourceId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CheckoutInput' responses: '201': description: 생성됨 content: application/json: schema: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/ValidationError' description: 잘못된 요청 '409': $ref: '#/components/responses/ConflictError' description: 상태 충돌 components: parameters: ResourceId: name: id in: path required: true schema: type: string description: Resource ID schemas: CheckoutInput: type: object properties: email: type: string format: email description: | Buyer email. Required for Guest Checkout (no customer_id). For logged-in customers, the customer email is used if omitted. payment_provider: type: string description: '''stripe'' or ''manual''' payment_method_id: type: string description: Stripe 결제 수단 ID Order: type: object properties: id: type: string number: type: integer status: type: string enum: - draft - pending - confirmed - processing - completed - cancelled payment_status: type: string enum: - unpaid - partially_paid - paid - partially_refunded - refunded fulfillment_status: type: string enum: - unfulfilled - partially_fulfilled - fulfilled - returned customer_id: type: string nullable: true email: type: string shipping_address: $ref: '#/components/schemas/Address' billing_address: $ref: '#/components/schemas/Address' lines: type: array items: $ref: '#/components/schemas/OrderLine' subtotal: $ref: '#/components/schemas/Money' discount_total: $ref: '#/components/schemas/Money' shipping_total: $ref: '#/components/schemas/Money' tax_total: $ref: '#/components/schemas/Money' total: $ref: '#/components/schemas/Money' refunded_total: $ref: '#/components/schemas/Money' applied_discounts: type: array items: $ref: '#/components/schemas/AppliedDiscount' shipping_method_name: type: string note: type: string payments: type: array items: $ref: '#/components/schemas/Payment' fulfillments: type: array items: $ref: '#/components/schemas/Fulfillment' refunds: type: array items: $ref: '#/components/schemas/Refund' metadata: type: object created_at: type: string format: date-time cancelled_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true Address: type: object properties: name: type: string company: type: string line1: type: string line2: type: string city: type: string state: type: string postal_code: type: string country: type: string description: ISO 3166-1 alpha-2 phone: type: string OrderLine: type: object properties: id: type: string variant_id: type: string product_id: type: string product_name: type: string variant_name: type: string sku: type: string image_url: type: string quantity: type: integer unit_price: $ref: '#/components/schemas/Money' line_discount: $ref: '#/components/schemas/Money' line_total: $ref: '#/components/schemas/Money' tax_amount: $ref: '#/components/schemas/Money' fulfilled_quantity: type: integer refunded_quantity: type: integer Money: type: object required: - amount - currency properties: amount: type: integer description: Smallest currency unit (KRW=won, USD=cents) currency: type: string minLength: 3 maxLength: 3 AppliedDiscount: type: object properties: discount_id: type: string code: type: string nullable: true name: type: string value_type: type: string enum: - fixed - percentage - free_shipping value: type: number saved: $ref: '#/components/schemas/Money' Payment: type: object properties: id: type: string order_id: type: string provider: type: string provider_id: type: string amount: $ref: '#/components/schemas/Money' status: type: string enum: - pending - completed - failed - cancelled - refunded created_at: type: string format: date-time Fulfillment: type: object properties: id: type: string order_id: type: string status: type: string enum: - pending - shipped - delivered - cancelled tracking_number: type: string tracking_url: type: string carrier: type: string lines: type: array items: type: object properties: order_line_id: type: string quantity: type: integer created_at: type: string format: date-time shipped_at: type: string format: date-time nullable: true delivered_at: type: string format: date-time nullable: true Refund: type: object properties: id: type: string order_id: type: string amount: $ref: '#/components/schemas/Money' reason: type: string restock: type: boolean status: type: string enum: - pending - completed - failed lines: type: array items: type: object properties: order_line_id: type: string quantity: type: integer created_at: type: string format: date-time ErrorResponse: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string details: type: object responses: ValidationError: description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ConflictError: description: Status conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: 'API Key. Example: sk_live_xxxxx or pk_live_xxxxx' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.