충전 주문 상세 조회 | ToAPIs Documentation

GET

/api/v1/account/billing/topups/%7Btrade_no%7D

중국 본토 사용자 안내: 중국 본토 사용자는 https://toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://toapis.com 을 https://toapis.cn 로 바꿔 주세요.

인증, 페이지 처리 및 오류는 시작하기를 참조하세요.

동작

주 계정만 자신의 결제 정보를 조회할 수 있습니다. 하위 계정은 HTTP 403 을 받으며, 주 계정도 구성원 결제 정보를 조회할 수 없습니다.

기본 31 일, 최대 366 일이며 생성 시각과 주문 ID 내림차순입니다. recorded_payment_amount/payment_currency 는 원래 통화이며 credits 계산에 사용하지 않습니다. planned_credits 는 예정, credited_credits 는 확정이며 refunded_credits 는 원래 입금에서 빼지 않고 별도로 기록합니다. 성공 전 주문은 credited_credits="0" 입니다. 과거 금액을 확인할 수 없으면 null 이며 이유는 meta 에 있습니다. 수동 증정과 독립 오프라인 환불은 제외합니다. refund=null 은 다른 환불이 없음을 보장하지 않으며 로컬 기록은 카드 입금을 증명하지 않습니다. 외부 결제 주문 조회나 보정은 하지 않습니다.

인증

Authorizationstring헤더필수

Bearer YOUR_SYSTEM_ACCESS_TOKEN 을 사용합니다. 모델 API 키는 사용할 수 없습니다. X-User-Id 는 필요하지 않습니다.

매개변수

trade_nostring경로필수

플랫폼 충전 주문 번호. 외부 결제 제공자의 주문 ID 로 대체할 수 없습니다.

제약: minLength=1; maxLength=255.

요청 예시

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/topups/trade_example_01' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/topups/trade_example_01",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/billing/topups/trade_example_01");

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

응답 필드

예시는 가상 데이터이며 credits_per_usd="100" 을 가정합니다. 실제 환산에는 응답 값을 사용하세요.

codeinteger

결과 코드. 0 은 성공입니다.

messagestring

성공 시 빈 문자열이며 오류 메시지는 현지화됩니다.

dataobject

현재 조회의 결과 객체입니다.

data.idstring

충전 주문의 내부 ID. 상세 조회에는 trade_no 를 사용합니다. 10 진수 ID 문자열로 반환합니다.

data.trade_nostring

상세 조회용 플랫폼 충전 주문 번호이며 외부 결제 주문 ID 가 아닙니다.

data.providerstring

결제 서비스 제공자입니다.

data.statusstring

충전 주문 상태. 성공한 주문만 확정 입금을 나타냅니다.

data.trigger_typestring | null

수동 또는 자동 등의 충전 시작 방식. 과거 값은 null 일 수 있습니다.

data.created_atstring | null

생성 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.completed_atstring | null

주문 완료 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.recorded_payment_amountstring | null

로컬 주문의 원래 통화 결제 금액. 통화는 payment_currency 이며 credits 계산에 사용하지 않습니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다. 불명확하거나 해당하지 않으면 null 입니다.

data.payment_currencystring | null

주문에 기록된 원래 결제 통화입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.planned_creditsstring | null

예정된 credits 이며 확정 입금액과 다릅니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다. 불명확하거나 해당하지 않으면 null 입니다.

data.credited_creditsstring | null

확정 입금 credits. 성공 전 주문은 "0", 과거 금액 미확인 시 null 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.

data.refunded_creditsstring | null

주문에 기록된 환불 credits 를 원래 입금에서 빼지 않고 별도로 표시합니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다. 불명확하거나 해당하지 않으면 null 입니다.

data.refundobject | null

주문의 로컬 환불 정보. null 은 독립 오프라인 환불 부재나 카드 입금을 보장하지 않습니다.

data.refund.statusstring

주문에 기록된 환불 상태입니다.

data.refund.recorded_amountstring | null

로컬 환불 기록의 원래 통화 금액. 통화는 currency 입니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다. 불명확하거나 해당하지 않으면 null 입니다.

data.refund.currencystring | null

금액에 사용되는 원래 통화입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.refund.recorded_atstring | null

로컬 환불 기록 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.metaobject

데이터 출처, 조회 범위 및 집계 기준 등의 메타데이터입니다.

data.meta.sourcestring

데이터 출처입니다. 로컬 설정이나 원장 스냅샷은 실시간 Stripe 상태를 뜻하지 않습니다. 고정 값: "local_ledger".

data.meta.refund_coveragestring

환불 정보의 범위이며 주문 환불 스냅샷만 포함합니다. 고정 값: "order_snapshot_only".

data.meta.standalone_offline_refunds_includedboolean

독립 오프라인 환불 포함 여부이며 현재 false 입니다.

data.meta.payment_amount_basisstring

결제 금액의 기준이며 로컬 주문 스냅샷을 사용합니다. 고정 값: "local_order_snapshot".

data.meta.consistencystring

eventual 은 최종 일관성으로 기록이 나중에 갱신될 수 있습니다.

data.meta.payment_amount_sourcestring

결제 금액 확인에 사용한 기록 출처입니다.

data.meta.credit_amount_sourcestring

입금 credits 확인에 사용한 기록 출처입니다.

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "id": "501",
    "trade_no": "trade_example_01",
    "provider": "stripe",
    "status": "success",
    "trigger_type": "manual",
    "created_at": "2026-11-01T08:00:00Z",
    "completed_at": "2026-11-01T08:01:00Z",
    "recorded_payment_amount": "10",
    "payment_currency": "USD",
    "planned_credits": "1000",
    "credited_credits": "1000",
    "refunded_credits": "0",
    "refund": null,
    "meta": {
      "source": "local_ledger",
      "consistency": "eventual",
      "payment_amount_basis": "local_order_snapshot",
      "refund_coverage": "order_snapshot_only",
      "standalone_offline_refunds_included": false,
      "payment_amount_source": "paid_amount",
      "credit_amount_source": "credited_credits"
    }
  }
}