ToAPIsToAPIs
Платежи

Получить заказ пополнения

Чтение заказа пополнения по номеру заказа

GET
/api/v1/billing/topups/{trade_no}

Для пользователей из материкового Китая: используйте https://api.toapis.cn в качестве эндпоинта (Base URL). Замените https://api.toapis.com на https://api.toapis.cn во всех примерах этого документа.

Аутентификация, пагинация и ошибки описаны в разделе Подключение.

Поведение

Возвращает детали одного пополнения по trade_no. Только основной аккаунт может запрашивать свои счета: суб-аккаунт получает HTTP 403, а основной аккаунт не может запрашивать счета участников через этот эндпоинт.

Находит ваш заказ по trade_no. Номера заказов внешних платёжных платформ не принимаются. Чужие и несуществующие заказы, а также отдельные офлайн-возвраты дают 404. Эндпоинт не запрашивает платёжную платформу и не сверяет заказы.

planned_credits — планируемое зачисление, credited_credits — подтверждённое, refunded_credits — возвраты отдельно, без вычитания из зачисления. У неуспешных заказов credited_credits="0".

refund=null не гарантирует отсутствие других возвратов, а локальный снимок возврата не означает поступление на карту.

Аутентификация

Authorizationstringзаголовокобязательно

Используйте Bearer YOUR_SYSTEM_ACCESS_TOKEN. API-ключ модели не подходит. Заголовок X-User-Id не требуется.

Параметры запроса

trade_nostringпутьобязательно

Номер заказа пополнения платформы, а не ID заказа внешней платежной системы.

Ограничения: minLength=1; maxLength=255.

Примеры запросов

Пример запроса

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

response = requests.get(
    "https://api.toapis.com/api/v1/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://api.toapis.com/api/v1/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". Используйте коэффициент из ответа API.

codeinteger

Числовой код результата; 0 означает успех.

messagestring

Сообщение ответа; пустое при успехе. Сообщения об ошибках локализуются.

dataobject

Объект результата текущего запроса.

data.idstring

Внутренний ID заказа пополнения. Для деталей используйте trade_no. Возвращается как десятичная строка 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

Источник записи для подтверждения зачисленных средств.

Примеры ответов

Пример ответа

{
  "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"
    }
  }
}