API Эндпоинты

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

Base URL: https://papi.cryptumpay.com

Формат ответа

Все ответы используют единую структуру-конверт:

typescript

// Успех
{ "data": T, "errorObject": null }

// Ошибка
{ "data": null, "errorObject": { "httpCode": number, "appCode": number, "message"?: string } }

POST /v1/orders

Создаёт новый заказ мерчанта. В зависимости от подхода к интеграции возвращённый Order ID можно:

Передать виджету, чтобы клиент завершил оплату прямо на вашем сайте
Использовать для формирования платёжной ссылки — https://pay.cryptumpay.com/m/{orderId} — и отправки клиенту по email, в мессенджере, SMS или любым другим способом (см. Без виджета)
Использовать полностью через API, без виджета и редиректа, прямо из своего приложения — см. White-label / нативное приложение

Тело запроса

Поле	Тип	Обязательно	Описание
`title`	`string`	Да	Заголовок заказа, отображаемый клиенту
`description`	`string`	Да	Описание заказа, отображаемое клиенту
`fiatAmount`	`string`	Один из двух базисов цены	Сумма оплаты в виде десятичной строки, например `"9.99"`. Взаимоисключаемо с `cryptoAmount` — см. ниже
`fiatCurrency`	`string`	Вместе с `fiatAmount`	Код фиатной валюты, например `"usd"` или `"eur"`
`cryptoCurrency`	`string`	Один из двух базисов цены	Тикер криптовалюты, например `"usdt"`. Используется вместе с `cryptoBlockchain` и `cryptoAmount` вместо `fiatAmount`/`fiatCurrency`
`cryptoBlockchain`	`string`	Вместе с `cryptoCurrency`	Название сети, например `"tron"`, `"bsc"` (те же значения, что и в POST /v1/withdraw)
`cryptoAmount`	`string`	Вместе с `cryptoCurrency`	Цена заказа в крипте, десятичная строка. Эквивалент в `fiatAmount` считается автоматически по текущему курсу. При использовании этого базиса запрос сразу создаёт и привязывает кастомерский ордер (адрес для депозита, точная сумма) — см. Базис цены ниже
`clientEmail`	`string`	Нет	Email вашего клиента, привязывается к созданному депозиту/кастомерскому ордеру (отличается от `projectDataUserEmail` — то просто метаданные на мерчантском ордере)
`url`	`string`	Нет	Return URL для платёжного шлюза (переопределяет `successPath`/`failPath` на уровне проекта)
`projectDataUserId`	`string`	Нет	Ваш внутренний ID пользователя для привязки к заказу
`projectDataUserEmail`	`string`	Нет	Email клиента для привязки к заказу (только метаданные)
`projectDataOrderId`	`string`	Нет	Ваш внутренний ID заказа для привязки
`projectDataMeta`	`string`	Нет	Произвольная строка метаданных (например, JSON) для прикрепления к заказу

Базис цены

Заказ можно оценить в фиате или в крипте — выберите ровно один вариант:

fiatAmount + fiatCurrency — классический флоу. Создаёт только мерчантский ордер; клиенту (через виджет или ваше собственное приложение, вызывая эндпоинты ниже) всё ещё нужно выбрать сеть для оплаты.
cryptoCurrency + cryptoBlockchain + cryptoAmount — для приложений со своим пикером сети (используйте GET /v1/currencies для его построения). Создаёт мерчантский ордер и кастомерский ордер (адрес для депозита) одним вызовом, так как сеть уже известна. fiatCurrency здесь опционален — по умолчанию берётся предпочитаемая фиатная валюта проекта, используется только для учёта/отчётности, не для ценообразования.

Кто платит комиссию

Если в вашем проекте настроено, что комиссию (сервисную и/или сетевую) платит мерчант, клиент заплатит ровно cryptoAmount. Если платит клиент — комиссия добавляется сверху автоматически. GET /v1/currencies уже возвращает cryptoMinAmount с учётом этого, считать самостоятельно не нужно — достаточно не опускаться ниже этого значения.

Ответ

json

{
  "data": {
    "id": "1c555afe-77bc-ab57-ffa0-27cdacc94000",
    "project": {
      "id": "string",
      "feePercent": 1.5,
      "logoUrl": "https://...",
      "title": "My Store",
      "url": "https://mystore.com"
    },
    "expiresAt": 1745975440234,
    "customerOrderRequest": {
      "fiatTicker": "usd",
      "fiatAmount": "9.99",
      "title": "Order #1",
      "description": "My product",
      "url": null,
      "projectData": {}
    }
  },
  "errorObject": null
}

Ошибки

appCode	Описание
`6000`	Ошибка создания заказа (сервис недоступен или неверные параметры)

Node.js SDK

typescript

const response = await client.createOrder({
  title: 'Заказ #12345',
  description: 'Оформление заказа',
  fiatAmount: '49.99',
  fiatCurrency: 'usd',
  projectDataUserId: 'user_42',
  projectDataOrderId: 'internal-order-123',
});

if (response.errorObject) {
  console.error('Ошибка создания заказа:', response.errorObject);
} else {
  const orderId = response.data.id;
  // Передайте orderId виджету через колбэк onCreateOrder
}

GET /v1/currencies

Возвращает криптовалюты и сети, доступные для оплаты прямо сейчас, с лимитами и комиссиями, актуальными для вашего проекта. Используйте это, чтобы построить собственный пикер валюты/сети для базиса цены cryptoAmount в POST /v1/orders (см. White-label / нативное приложение) — курсы и расчёт комиссий считать самостоятельно не нужно.

Эндпоинт отдаёт только крипто-часть. Он не возвращает фиатные курсы или лимиты в фиате — если вам нужно показать цену в фиате, считайте её сами; сами заказы всегда оцениваются либо в фиате, либо в крипте, на ваш выбор, независимо от этого эндпоинта.

Ответ

json

{
  "data": [
    {
      "cryptoCurrency": "trx",
      "cryptoBlockchain": "tron",
      "cryptoMinAmount": "7.5",
      "cryptoMaxAmount": "99998.9",
      "transferFee": "1.1"
    },
    {
      "cryptoCurrency": "usdt",
      "cryptoBlockchain": "bsc",
      "cryptoMinAmount": "5.000000",
      "cryptoMaxAmount": "49999.5"
    }
  ],
  "errorObject": null
}

cryptoMinAmount — уже безопасный минимум для cryptoAmount в POST /v1/orders: если комиссию в вашем проекте платит мерч, это значение уже её учитывает, и любая сумма не ниже этого значения гарантированно пройдёт.
cryptoMaxAmount уже оставляет запас на сетевую комиссию.
transferFee (сетевая комиссия) присутствует, только если её платит клиент (настройка стороны комиссии в вашем проекте). Если её платит проект — поле отсутствует, на сумму для клиента она не влияет.
serviceFeePercent (сервисная комиссия CryptumPay, в процентах) присутствует, только если её платит клиент. Если её платит проект — поле отсутствует.
Сети на обслуживании или с отключённым депозитом в список не попадают вообще.

Node.js SDK

typescript

const response = await client.getCurrencies();

if (!response.errorObject) {
  for (const entry of response.data) {
    console.log(`${entry.cryptoCurrency} в сети ${entry.cryptoBlockchain}: минимум ${entry.cryptoMinAmount}`);
  }
}

GET /v1/orders/:orderId

Возвращает текущее состояние заказа мерчанта, включая информацию о том, начал ли клиент оплату (customerOrderId).

Параметры пути

Параметр	Описание
`orderId`	Order ID мерчанта, возвращённый `POST /v1/orders`

Ответ

json

{
  "data": {
    "id": "1c555afe-77bc-ab57-ffa0-27cdacc94000",
    "project": { ... },
    "expiresAt": 1745975440234,
    "customerOrderRequest": { ... },
    "customerOrderId": "4fc1ae7b-c7f9-4dc7-2222-8d37f993e28f",
    "customerOrder": {
      "status": "created",
      "cryptoTicker": "trx",
      "cryptoBlockchainId": 12,
      "cryptoAmount": "150.5",
      "depositAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
      "expiresAt": 1745977240234,
      "depositsList": [],
      "summary": { ... }
    },
    "financeSummary": {
      "status": 3,
      "accrued": true,
      "income": {
        "amount": "49.10",
        "currency": "usd"
      }
    }
  },
  "errorObject": null
}

customerOrder равен null, пока клиент не выбрал сеть и не был назначен адрес для депозита — через виджет или через вызов POST /v1/orders с базисом cryptoAmount из вашего приложения. Используйте это поле, чтобы в любой момент перечитать адрес/сумму для депозита (например, если приложение было закрыто и открыто заново) — отдельный эндпоинт для этого не нужен.

financeSummary присутствует только после того, как заказ клиента достигнет финального статуса. income отражает сумму, фактически зачисленную после вычета комиссий.

Статусы financeSummary

status	Описание
`0`	В процессе — заказ клиента обрабатывается
`1`	На проверке — заказ ожидает ручной проверки
`2`	Отменён — заказ был отменён
`3`	Оплачен — платёж получен, средства зачислены
`4`	Зачисление — средства находятся в процессе зачисления на баланс

Поле accrued становится true после зачисления средств на баланс проекта.

Подтверждение успешного платежа

Для подтверждения получения средств проверьте, что financeSummary.status равен 3 или 4:

Статус 3 (Оплачен) — средства уже зачислены на баланс проекта.
Статус 4 (Зачисление) — зачисление ещё в процессе, но система точно получила платёж и завершит перевод в ближайшее время.

Не подтверждайте заказы по статусу 0 (В процессе) или 1 (На проверке) — это не финальные статусы.

Ошибки

appCode	Описание
`6001`	Заказ не найден или не принадлежит вашему проекту

Node.js SDK

typescript

const response = await client.getOrder('1c555afe-77bc-ab57-ffa0-27cdacc94000');

if (response.errorObject) {
  console.error('Заказ не найден:', response.errorObject);
} else {
  console.log('Customer Order ID:', response.data.customerOrderId);
  console.log('Finance Summary:', response.data.financeSummary);
}

POST /v1/withdraw

Необходим IP Whitelist

Этот эндпоинт проверяет IP-адрес запроса. Необходимо настроить IP-whitelist для вашего API-ключа в консоли. Запросы с неразрешённых IP будут отклонены с ошибкой 8002. См. Аутентификация → IP Whitelist.

Инициирует вывод криптовалюты на внешний адрес.

Тело запроса

Поле	Тип	Обязательно	Описание
`currency`	`string`	Да	Тикер криптовалюты, например `"usdt"`
`blockchain`	`string`	Да	Идентификатор блокчейна, например `"bsc"`, `"tron"`
`address`	`string`	Да	Адрес кошелька назначения
`amount`	`string`	Да	Сумма вывода в виде десятичной строки, например `"100.00"`
`extra`	`string \| null`	Нет	Memo/тег для блокчейнов, где это требуется (например, XRP, TON)

Ответ

json

{
  "data": {
    "id": "b44ac754-b67a-4d79-8c78-61e01b9c1196"
  },
  "errorObject": null
}

Ошибки

appCode	Описание
`8000`	Ошибка создания вывода (недостаточно средств, неверный адрес или сервис недоступен)
`8002`	IP-whitelist не настроен для этого API-ключа
`7003`	IP запроса не в whitelist

Node.js SDK

typescript

const response = await client.withdraw({
  currency: 'usdt',
  blockchain: 'bsc',
  address: '0xВАШ_АДРЕС_КОШЕЛЬКА',
  amount: '100.00',
});

if (response.errorObject) {
  console.error('Ошибка вывода:', response.errorObject);
} else {
  console.log('Withdrawal ID:', response.data.id);
}

GET /v1/withdraw/:id

Необходим IP Whitelist

То же требование, что и для POST /v1/withdraw — IP-whitelist должен быть настроен. См. Аутентификация → IP Whitelist.

Возвращает текущий статус вывода средств.

Параметры пути

Параметр	Описание
`id`	ID вывода, возвращённый `POST /v1/withdraw`

Ответ

json

{
  "data": {
    "status": "finished",
    "hash": "0xabc123..."
  },
  "errorObject": null
}

hash — хеш транзакции в блокчейне, доступен после отправки транзакции в сеть.

Статусы вывода

Статус	Описание
`created`	Вывод поставлен в очередь, ещё не обработан
`pending`	Транзакция отправлена в блокчейн
`finished`	Транзакция подтверждена в блокчейне
`failed`	Вывод не удалось завершить

Ошибки

appCode	Описание
`8001`	Вывод не найден или не принадлежит вашему проекту

Смотрите также

Аутентификация — подпись запросов и справочник ошибок
Webhooks & Redirects — получение уведомлений о статусе платежей

API Эндпоинты ​

Формат ответа ​

POST /v1/orders ​

Тело запроса ​

Базис цены ​

Ответ ​

Ошибки ​

Node.js SDK ​

GET /v1/currencies ​

Ответ ​

Node.js SDK ​

GET /v1/orders/:orderId ​

Параметры пути ​

Ответ ​

Статусы financeSummary ​

Ошибки ​

Node.js SDK ​

POST /v1/withdraw ​

Тело запроса ​

Ответ ​

Ошибки ​

Node.js SDK ​

GET /v1/withdraw/:id ​

Параметры пути ​

Ответ ​

Статусы вывода ​

Ошибки ​

Смотрите также ​

API Эндпоинты

Формат ответа

POST /v1/orders

Тело запроса

Базис цены

Ответ

Ошибки

Node.js SDK

GET /v1/currencies

Ответ

Node.js SDK

GET /v1/orders/:orderId

Параметры пути

Ответ

Статусы financeSummary

Ошибки

Node.js SDK

POST /v1/withdraw

Тело запроса

Ответ

Ошибки

Node.js SDK

GET /v1/withdraw/:id

Параметры пути

Ответ

Статусы вывода

Ошибки

Смотрите также