충전 결제 확인

POST/v1/organizations/{org_id}/topups/{order_id}/confirm

결제창에서 돌아온 뒤 호출합니다, 서버가 PortOne에서 결제를 다시 읽어 금액을 대조하고 크레딧을 적립합니다

콘솔 세션 전용입니다, 조직 역할 owner, admin만 부를 수 있고 API 키로 부르면 403 console_only입니다

멱등입니다, 이미 결제된 주문을 다시 확인하면 같은 결과를 돌려주고 크레딧을 다시 적립하지 않습니다, PortOne 웹훅도 같은 경로로 정산됩니다

Headers

Cookie: string
콘솔 로그인 세션 쿠키, 콘솔 전용 엔드포인트라 API 키로 부르면 403 console_only입니다
Origin: string
콘솔 세션으로 상태를 바꿀 때 같은 출처(https://xenoci.com)여야 합니다, API 키 요청에는 필요 없습니다

Path Parameters

org_id: string
조직 ID
형식 ^org_[A-Za-z0-9]+$
order_id: string
충전 주문 ID
형식 ^[A-Za-z0-9_-]{6,64}$

Body

payment_id: string
결제창이 돌려준 paymentId
200자 이하

Returns

200 application/json

TopupConfirmed: object
- topup: Topup { order_id, organization_id, status, … }
  결제된 주문
  - order_id: string
    주문 ID, PortOne paymentId로 그대로 씁니다
    형식 ^[A-Za-z0-9_-]{6,64}$
  - organization_id: optional string
    조직 ID
  - status: "pending" or "confirming" or "paid" or "failed" or "expired" or "cancelled"
    주문 상태
  - usd: integer
    충전 USD
  - credit_micro_usd: integer
    적립될 크레딧(µUSD)
    최소 0
  - credit_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - amount_krw: integer
    결제 원화, ceil(usd × 고정 환율), 부가세 포함
  - supply_krw: optional integer
    공급가액
  - vat_krw: integer
    부가세
  - fx_day: string
    환율 기준일
  - fixed_krw_per_usd: string
    주문에 고정된 환율
  - payment_id: optional string or null
    PortOne paymentId
  - method: optional string or null
    결제 수단
  - paid_at: optional string or null
    결제 시각
  - receipt_url: optional string or null
    영수증 URL
  - cancelled_krw: optional integer
    취소된 원화(철회)
  - withdrawable_until: optional string or null
    청약철회 기한, 결제 시각 + 7일
  - failure_code: optional string or null
    실패 코드
  - created_at: string
    만든 시각
    RFC 3339 UTC 시각
  - expires_at: optional string
    대기 주문 만료 시각, 만든 뒤 60분
    RFC 3339 UTC 시각
- balance: Balance { organization_id, balance_micro_usd, balance_usd, … }
  적립 뒤 잔액
  - organization_id: string
    조직 ID
  - balance_micro_usd: integer
    원장 합계 잔액(µUSD)
    최소 0
  - balance_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - available_micro_usd: integer
    만료되지 않은 로트 합에서 실행 중인 잡이 이미 쓴 금액을 뺀 값
    최소 0
  - available_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - reserved_micro_usd: integer
    실행 중인 잡이 이미 쓴 금액
    최소 0
  - reserved_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - rate_micro_usd_per_min: integer
    지금 적용되는 분당 요율(µUSD)
  - low: boolean
    사용 가능 잔액이 낮은 잔액 기준 아래인지
  - low_threshold_micro_usd: optional integer
    낮은 잔액 기준
    최소 0
  - low_threshold_usd: optional string
    낮은 잔액 기준(USD)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - next_expiry: optional object { expires_at, remaining_micro_usd, remaining_usd } or null
    다음에 만료될 로트의 시각과 남은 금액, 없으면 null
    expires_at: optional string
    만료 시각
    RFC 3339 UTC 시각
    remaining_micro_usd: optional integer
    금액(µUSD 정수)
    최소 0
    remaining_usd: optional string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - topup_url: string
    콘솔 충전 페이지, 결제 토큰은 없고 로그인이 필요합니다
- tier: optional OrganizationTier { organization_id, tier, cumulative_topup_micro_usd, … }
  적립 뒤 티어
  - organization_id: string
    조직 ID
  - tier: integer
    티어
  - cumulative_topup_micro_usd: integer
    누적 충전액
    최소 0
  - cumulative_topup_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - max_concurrent_jobs: integer
    동시 실행 잡 수
  - running_jobs: integer
    지금 실행 중인 잡
  - queued_jobs: optional integer
    대기 중인 잡
  - monthly_limit_micro_usd: optional integer or null
    월 한도(µUSD)
  - monthly_limit_usd: optional string or null
    월 한도(USD 정수)
  - month_usage_micro_usd: integer
    이번 달 사용액
    최소 0
  - month_usage_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
  - month_resets_at: optional string
    월 한도가 풀리는 시각(다음 달 1일 00:00 UTC)
    RFC 3339 UTC 시각
  - next_tier: optional Tier { tier, name, min_cumulative_topup_micro_usd, … } or null
    다음 티어와 조건, 최고 티어면 null
    tier: integer
    티어 번호, 1부터
    최소 1
    name: optional string
    티어 이름
    min_cumulative_topup_micro_usd: integer
    진입 누적 충전액
    최소 0
    min_cumulative_topup_usd: string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$
    max_concurrent_jobs: integer
    동시 실행 잡 수
    최소 1
    max_queued_jobs: optional integer
    조직 대기열 상한
    monthly_limit_micro_usd: integer or null
    월 사용 한도, null이면 상한 없음(Custom)
    monthly_limit_usd: string or null
    월 한도(USD 정수)
    rate_discount_bp: optional integer
    이 티어의 러너 단가 할인(1/100 퍼센트), 지금은 0
    최소 0, 최대 9999
  - upgraded_at: optional string or null
    마지막 상향 시각

오류

invalid_request: HTTP 400
본문이나 쿼리가 검증에 실패했습니다, error.details.fields에 문제 필드가 있습니다
session_required: HTTP 401
콘솔 엔드포인트를 유효한 콘솔 세션 쿠키 없이 불렀습니다
console_only: HTTP 403
콘솔 세션 전용 엔드포인트입니다, API 키로는 결제, 키, 멤버 관리를 할 수 없습니다
insufficient_permission: HTTP 403
역할이나 키 권한(run/read)이 이 요청을 허용하지 않습니다
not_found: HTTP 404
자원이 없거나 이 호출자에게 보이지 않습니다
payment_amount_mismatch: HTTP 409
PortOne 결제의 금액, 통화, 상점이 주문과 다릅니다, 아무것도 적립되지 않았습니다
payment_not_paid: HTTP 409, 다시 시도 가능
PortOne이 아직 결제 완료(PAID)로 보고하지 않습니다, 주문 상태를 다시 조회하세요
payment_reference_reused: HTTP 409
이 PortOne paymentId는 이미 다른 주문에 묶여 있습니다
topup_expired: HTTP 409
주문이 60분 대기 기간을 넘겼습니다, 새 주문을 만드세요
rate_limited: HTTP 429, 다시 시도 가능
이 키 또는 조직의 요청이 너무 많습니다, retry_after_s만큼 기다리세요
internal_error: HTTP 500, 다시 시도 가능
예상하지 못한 오류입니다, 다시 시도하고 반복되면 request_id와 함께 알려 주세요
payments_unavailable: HTTP 503, 다시 시도 가능
이 환경에서는 충전이 꺼져 있습니다(기능 플래그 또는 결제 키 없음)

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

다음 단계

오늘 환율 GET /v1/fx-rates/today
충전 주문 생성 POST /v1/organizations/{org_id}/topups
충전 주문 목록 GET /v1/organizations/{org_id}/topups
충전 주문 조회 GET /v1/organizations/{org_id}/topups/{order_id}

충전 결제 확인cURL

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

Response 200

{
  "topup": {
    "order_id": "topup_9f3KqZ2mP1",
    "organization_id": "org_7Kq2m9ZtP3",
    "status": "paid",
    "usd": 20,
    "credit_micro_usd": 20000000,
    "credit_usd": "20.00",
    "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"
  },
  "balance": {
    "organization_id": "org_7Kq2m9ZtP3",
    "balance_micro_usd": 20000000,
    "balance_usd": "20.00",
    "available_micro_usd": 19920000,
    "available_usd": "19.92",
    "reserved_micro_usd": 80000,
    "reserved_usd": "0.08",
    "rate_micro_usd_per_min": 39600,
    "low": false,
    "low_threshold_micro_usd": 1188000,
    "low_threshold_usd": "1.19",
    "next_expiry": {
      "expires_at": "2027-10-12T03:11:05Z",
      "remaining_micro_usd": 19920000,
      "remaining_usd": "19.92"
    },
    "topup_url": "https://xenoci.com/console/topup?org=org_7Kq2m9ZtP3"
  },
  "tier": {
    "organization_id": "org_7Kq2m9ZtP3",
    "tier": 1,
    "cumulative_topup_micro_usd": 20000000,
    "cumulative_topup_usd": "20.00",
    "max_concurrent_jobs": 8,
    "running_jobs": 1,
    "queued_jobs": 0,
    "monthly_limit_micro_usd": 100000000,
    "monthly_limit_usd": "100.00",
    "month_usage_micro_usd": 480000,
    "month_usage_usd": "0.48",
    "month_resets_at": "2026-11-01T00:00:00Z",
    "next_tier": {
      "tier": 1,
      "name": "Tier 1",
      "min_cumulative_topup_micro_usd": 5000000,
      "min_cumulative_topup_usd": "5.00",
      "max_concurrent_jobs": 8,
      "max_queued_jobs": 50,
      "monthly_limit_micro_usd": 100000000,
      "monthly_limit_usd": "100.00"
    },
    "upgraded_at": "2026-10-12T03:11:05Z"
  }
}