충전 주문 목록 조회 | ToAPIs Documentation

GET

/api/v1/account/billing/topups

중국 본토 사용자 안내: 중국 본토 사용자는 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 는 필요하지 않습니다.

매개변수

fromstring쿼리

시간대가 포함된 RFC 3339 시작 시각. 해당 시각을 포함하며 to 와 함께 지정합니다.

제약: date-time.

tostring쿼리

시간대가 포함된 RFC 3339 종료 시각. 해당 시각을 제외하며 from 보다 늦어야 합니다.

제약: date-time.

cursorstring쿼리

이전 next_cursor 를 그대로 전달하고 필터를 유지합니다. 조건을 변경하면 처음부터 조회합니다.

제약: maxLength=2048.

limitinteger쿼리기본값: 20

페이지당 최대 항목 수.

제약: minimum=1; maximum=100; 기본값: 20.

providerstring쿼리

결제 제공자.

제약: stripe, wechat, alipay, creem, nowpayments, offline.

statusstring쿼리

결제: pending, success, superseded, expired, failed, partially_paid.

제약: pending, success, superseded, expired, failed, partially_paid.

요청 예시

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/topups?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&provider=stripe&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/topups",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "provider": "stripe",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/billing/topups");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "provider": "stripe",
  "limit": "20"
}).toString();

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" 을 가정합니다. 실제 환산에는 응답 값을 사용하세요.

결과는 data.items 에 있습니다. has_more 와 next_cursor 로 페이지를 조회합니다. 마지막 커서는 null 이며 총 개수는 반환하지 않습니다.

codeinteger

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

messagestring

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

dataobject

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

data.itemsobject[]

현재 페이지의 기록 목록이며 빈 결과는 [] 입니다.

data.items[].idstring

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

data.items[].trade_nostring

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

data.items[].providerstring

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

data.items[].statusstring

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

data.items[].trigger_typestring | null

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

data.items[].created_atstring | null

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

data.items[].completed_atstring | null

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

data.items[].recorded_payment_amountstring | null

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

data.items[].payment_currencystring | null

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

data.items[].planned_creditsstring | null

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

data.items[].credited_creditsstring | null

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

data.items[].refunded_creditsstring | null

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

data.items[].refundobject | null

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

data.items[].refund.statusstring

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

data.items[].refund.recorded_amountstring | null

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

data.items[].refund.currencystring | null

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

data.items[].refund.recorded_atstring | null

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

data.items[].metaobject

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

data.items[].meta.sourcestring

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

data.items[].meta.refund_coveragestring

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

data.items[].meta.standalone_offline_refunds_includedboolean

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

data.items[].meta.payment_amount_basisstring

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

data.items[].meta.consistencystring

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

data.items[].meta.payment_amount_sourcestring

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

data.items[].meta.credit_amount_sourcestring

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

data.has_moreboolean

다음 페이지가 있는지 나타냅니다.

data.next_cursorstring | null

동일한 필터로 cursor 에 그대로 전달합니다. 마지막 페이지는 null 입니다.

data.metaobject

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

data.meta.sourcestring

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

data.meta.scopestring

조회 데이터의 소유 범위이며 인증된 계정 자신입니다.

data.meta.fromstring

조회 시간 범위의 시작 시각을 포함합니다.

data.meta.tostring

조회 시간 범위의 종료 시각은 제외합니다.

data.meta.consistencystring

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

data.meta.refund_coveragestring

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

data.meta.standalone_offline_refunds_includedboolean

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

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "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"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "source": "local_ledger",
      "scope": "self",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z",
      "consistency": "eventual",
      "refund_coverage": "order_snapshot_only",
      "standalone_offline_refunds_included": false
    }
  }
}