API Эндпоинты

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

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

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

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

// Успех
{ "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 или любым другим способом (см. Без виджета)

Тело запроса

Поле	Тип	Обязательно	Описание
title	string	Да	Заголовок заказа, отображаемый клиенту
description	string	Да	Описание заказа, отображаемое клиенту
fiatAmount	string	Да	Сумма оплаты в виде десятичной строки, например "9.99"
fiatCurrency	string	Да	Код фиатной валюты, например "usd" или "eur"
url	string	Нет	Return URL для платёжного шлюза (переопределяет successPath/failPath на уровне проекта)
projectDataUserId	string	Нет	Ваш внутренний ID пользователя для привязки к заказу
projectDataUserEmail	string	Нет	Email клиента для привязки к заказу
projectDataOrderId	string	Нет	Ваш внутренний ID заказа для привязки
projectDataMeta	string	Нет	Произвольная строка метаданных (например, JSON) для прикрепления к заказу

Ответ

{
  "data": {
    "id": "1c885afe-369f-4b38-92fa-983660c2452d",
    "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

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/orders/:orderId

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

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

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

Ответ

{
  "data": {
    "id": "1c885afe-369f-4b38-92fa-983660c2452d",
    "project": { ... },
    "expiresAt": 1745975440234,
    "customerOrderRequest": { ... },
    "customerOrderId": "4fc1ae7b-c7f9-4dc7-2222-8d37f993e28f",
    "financeSummary": {
      "status": 3,
      "accrued": true,
      "income": {
        "amount": "49.10",
        "currency": "usd"
      }
    }
  },
  "errorObject": null
}

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

Статусы financeSummary

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

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

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

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

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

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

Ошибки

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

Node.js SDK

const response = await client.getOrder('1c885afe-369f-4b38-92fa-983660c2452d');

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)

Ответ

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

Ошибки

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

Node.js SDK

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

Ответ

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

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

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

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

Ошибки

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

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

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