충전 주문 생성

USD 정수 금액으로 충전 주문을 만듭니다, 원화 금액과 환율은 주문에 고정됩니다

POST /v1/organizations/{org_id}/topups

인증

방식	허용	조건
API 키 (`Authorization: Bearer xci_live_…`)	불가	콘솔 세션 전용, 키로 부르면 403 console_only
콘솔 세션 쿠키	가능	조직 역할 `owner`, `admin`, 같은 출처의 Origin 헤더 필요

가격은 부가세 포함입니다, US$N 충전은 US$N을 결제하고 US$N 크레딧을 받습니다
amount_krw = ceil(usd × fixed_krw_per_usd), 그 안에서 supply_krw = round(amount_krw / 1.1), vat_krw = amount_krw - supply_krw입니다, 고정 환율은 고시 매매기준율 × 1.02입니다
응답의 portone 객체를 그대로 브라우저 PortOne 결제창에 넘기고, 결제창에서 돌아오면 충전 결제 확인을 호출합니다
주문은 만든 뒤 60분 안에 결제하지 않으면 만료됩니다(topup_expired)

참고 서버 구현(2026-10-12 dev 기준)이 계약 초안과 다른 점
핸들러는 server/ci/runner2-topup-routes.js에 있지만 아직 앱에 마운트되지 않았습니다, 지금 호출하면 404 not_found입니다
마운트된 뒤에도 usd는 JSON 숫자여야 합니다, 문자열 "20"은 invalid_amount입니다

매개변수

이름	위치	타입	필수	설명
`org_id`	경로	string	필수	조직 ID, 형식 `^org_[A-Za-z0-9]+$`
`Idempotency-Key`	헤더	string		24시간 안에 같은 키로 다시 보내면 처음 응답을 그대로 돌려줍니다, 같은 키에 다른 본문이면 409 idempotency_conflict, 1자 이상, 255자 이하

요청 본문

필드	타입	필수	설명
`usd`	integer	필수	USD 정수, 프리셋 5, 20, 50, 100 또는 5 이상 직접 입력, 문자열과 소수와 지수 표기는 invalid_amount, 최소 5

응답

201

필드	타입	항상	설명
`topup`	object	항상	만들어진 주문
`topup.order_id`	string	항상	주문 ID, PortOne paymentId로 그대로 씁니다, 형식 `^[A-Za-z0-9_-]{6,64}$`
`topup.organization_id`	string		조직 ID
`topup.status`	`pending` \| `confirming` \| `paid` \| `failed` \| `expired` \| `cancelled`	항상	주문 상태
`topup.usd`	integer	항상	충전 USD
`topup.credit_micro_usd`	integer	항상	적립될 크레딧(µUSD), 최소 0
`topup.credit_usd`	string	항상	같은 금액의 USD 문자열(소수 6자리), 형식 `^-?[0-9]+\.[0-9]{6}$`
`topup.amount_krw`	integer	항상	결제 원화, ceil(usd × 고정 환율), 부가세 포함
`topup.supply_krw`	integer		공급가액
`topup.vat_krw`	integer	항상	부가세
`topup.fx_day`	date	항상	환율 기준일
`topup.fixed_krw_per_usd`	string	항상	주문에 고정된 환율
`topup.payment_id`	string		PortOne paymentId, null 가능
`topup.method`	string		결제 수단, null 가능
`topup.paid_at`	timestamp 또는 null		결제 시각, null 가능
`topup.receipt_url`	string		영수증 URL, null 가능
`topup.cancelled_krw`	integer		취소된 원화(철회)
`topup.withdrawable_until`	timestamp 또는 null		청약철회 기한, 결제 시각 + 7일, null 가능
`topup.failure_code`	string		실패 코드, null 가능
`topup.created_at`	timestamp	항상	만든 시각
`topup.expires_at`	timestamp		대기 주문 만료 시각, 만든 뒤 60분
`portone`	object	항상	PortOne 결제창에 넘길 값
`portone.store_id`	string	항상	PortOne 상점 ID
`portone.channel_key`	string	항상	PortOne 채널 키
`portone.payment_id`	string	항상	order_id와 같습니다
`portone.order_name`	string	항상	주문 이름
`portone.currency`	`CURRENCY_KRW`	항상	통화
`portone.total_amount`	integer	항상	결제 금액
`portone.pay_method`	`CARD` \| `EASY_PAY` \| `TRANSFER`	항상	결제 방식
`portone.test`	boolean		테스트 결제인지
`portone.customer`	object		구매자 정보
`portone.redirect_url`	string		결제 뒤 돌아올 URL

{
  "topup": {
    "order_id": "topup_9f3KqZ2mP1",
    "organization_id": "org_7Kq2m9ZtP3",
    "status": "paid",
    "usd": 20,
    "credit_micro_usd": 20000000,
    "credit_usd": "20.000000",
    "amount_krw": 28775,
    "supply_krw": 26159,
    "vat_krw": 2616,
    "fx_day": "2026-10-12",
    "fixed_krw_per_usd": "1438.71",
    "payment_id": "topup_9f3KqZ2mP1",
    "method": "card",
    "paid_at": "2026-10-12T03:11:05Z",
    "receipt_url": "https://…",
    "cancelled_krw": 0,
    "withdrawable_until": "2026-10-19T03:11:05Z",
    "failure_code": null,
    "created_at": "2026-10-12T03:11:05Z",
    "expires_at": "2026-10-12T04:11:05Z"
  },
  "portone": {
    "store_id": "store-…",
    "channel_key": "channel-key-…",
    "payment_id": "topup_9f3KqZ2mP1",
    "order_name": "XenoCI 크레딧 US$20",
    "currency": "KRW",
    "total_amount": 28775,
    "pay_method": "CARD",
    "test": false,
    "customer": {
      "email": "owner@example.com"
    },
    "redirect_url": "https://xenoci.com/console/topup?order=topup_9f3KqZ2mP1"
  }
}

오류

HTTP	코드	다시 시도	뜻
400	`invalid_amount`	아니오	충전 usd는 정수여야 합니다, 프리셋 5, 20, 50, 100 또는 5 이상(직접 입력 최대 이하)
400	`invalid_request`	아니오	본문이나 쿼리가 검증에 실패했습니다, error.details.fields에 문제 필드가 있습니다
401	`session_required`	아니오	콘솔 엔드포인트를 유효한 콘솔 세션 쿠키 없이 불렀습니다
403	`console_only`	아니오	콘솔 세션 전용 엔드포인트입니다, API 키로는 결제, 키, 멤버 관리를 할 수 없습니다
403	`insufficient_permission`	아니오	역할이나 키 권한(run/read)이 이 요청을 허용하지 않습니다
404	`not_found`	아니오	자원이 없거나 이 호출자에게 보이지 않습니다
409	`idempotency_conflict`	아니오	같은 Idempotency-Key를 다른 본문으로 다시 썼습니다
429	`rate_limited`	가능	이 키 또는 조직의 요청이 너무 많습니다, retryafters만큼 기다리세요
500	`internal_error`	가능	예상하지 못한 오류입니다, 다시 시도하고 반복되면 request_id와 함께 알려 주세요
503	`fx_rate_unavailable`	가능	오늘의 고정 원화 환율이 아직 없습니다, 환율이 올라올 때까지 충전이 닫힙니다
503	`payments_unavailable`	가능	이 환경에서는 충전이 꺼져 있습니다(기능 플래그 또는 결제 키 없음)

오류 봉투 모양과 전체 코드 표는 오류 코드에 있습니다

예시

curl -X POST "https://xenoci.com/api/runner/v1/organizations/org_7Kq2m9ZtP3/topups" \
  --cookie "xci_console=$SESSION" \
  -H "Origin: https://xenoci.com" \
  -H "Content-Type: application/json" \
  -d '{"usd":20}'

다음 단계

오늘 환율 GET /v1/fx-rates/today
충전 주문 목록 GET /v1/organizations/{org_id}/topups
충전 주문 조회 GET /v1/organizations/{orgid}/topups/{orderid}
충전 결제 확인 POST /v1/organizations/{orgid}/topups/{orderid}/confirm