Приём платежей

Создание платежа

Платёж — основной объект API. Вы создаёте его на сервере, покупатель оплачивает на странице NordPay, а результат приходит вебхуком.

POST/v1/payments

POST /v1/payments

curl -X POST https://api.nordpay.pro/v1/payments \
  -H "Authorization: Bearer $NORDPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 499000,
    "currency": "RUB",
    "method": "sbp",
    "description": "Заказ №1042",
    "order_id": "1042",
    "customer": {
      "email": "buyer@example.com"
    },
    "return_url": "https://shop.example/orders/1042",
    "metadata": {
      "cart_id": "c_77"
    }
  }'

Запрос

Создайте платёж, когда покупатель нажал «Оплатить» в вашем магазине. В ответе — объект платежа в статусе pending и ссылка confirmation.url на страницу оплаты.

Комиссия fee и сумма к зачислению net считаются сразу по вашей ставке для выбранного метода. Ставки зафиксированы в договоре и видны в кабинете.

Отправляйте заголовок Idempotency-Key со случайным UUID: повтор того же запроса не создаст второй платёж. Подробнее

Ответ · 201

{
  "id": "pay_2Kq8sD1fVxJ7mN4p",
  "object": "payment",
  "status": "pending",
  "amount": 499000,
  "amount_refunded": 0,
  "currency": "RUB",
  "fee": 17465,
  "net": 481535,
  "method": "sbp",
  "description": "Заказ №1042",
  "order_id": "1042",
  "metadata": {
    "cart_id": "c_77"
  },
  "customer": {
    "email": "buyer@example.com"
  },
  "confirmation": {
    "type": "redirect",
    "url": "https://api.nordpay.pro/checkout/pay_2Kq8sD1fVxJ7mN4p"
  },
  "sbp": {
    "qr_payload": "https://api.nordpay.pro/checkout/pay_2Kq8sD1fVxJ7mN4p",
    "expires_at": "2026-11-08T12:30:00Z"
  },
  "crypto": null,
  "crypto_network": null,
  "card": null,
  "failure": null,
  "livemode": false,
  "created_at": "2026-11-08T12:00:00Z",
  "paid_at": null,
  "expires_at": "2026-11-08T12:30:00Z"
}

Параметры

Параметры
Параметр	Тип	Описание
`amount`обязательный	integer	Сумма в копейках: 499000 = 4 990 ₽. От 1000 до 60000000.
`currency`обязательный	string	Валюта платежа. Сейчас поддерживается RUB.
`method`	string \| null	sbp, card или crypto. null или отсутствие поля — покупатель выбирает метод на странице оплаты.
`crypto_network`	string	Сеть USDT: trc20, ton, bep20, erc20 или sol. Только для method: "crypto" или без method. Не передан — покупатель выберет сеть сам.
`description`обязательный	string	Назначение платежа, видно покупателю на странице оплаты и в кабинете.
`order_id`	string	Номер заказа в вашей системе. Возвращается в платеже и вебхуках.
`customer`	object	Данные покупателя для чека и уведомлений.
`customer.email`	string	Электронная почта покупателя.
`customer.phone`	string	Телефон в формате +79991234567.
`return_url`	string	Куда вернуть покупателя после оплаты или отказа.
`metadata`	object	Ваши данные в формате «ключ: строка». Возвращаются в платеже и вебхуках как есть.
`save_method`	boolean	Сохранить способ оплаты для повторных списаний. Используется в рекуррентных платежах.

Покупатель выбирает метод сам

curl -X POST https://api.nordpay.pro/v1/payments \
  -H "Authorization: Bearer $NORDPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 129000,
    "currency": "RUB",
    "description": "Подписка Pro, ноябрь",
    "order_id": "A-2207"
  }'

Объект платежа

Поля объекта платежа
Параметр	Тип	Описание
`id`	string	Идентификатор платежа с префиксом pay_.
`status`	string	Текущий статус, см. ниже.
`amount`	integer	Сумма платежа в копейках.
`amount_refunded`	integer	Сколько уже возвращено.
`fee`	integer	Комиссия по вашей ставке для метода.
`net`	integer	Сумма к зачислению: amount − fee.
`method`	string \| null	Метод оплаты; null, пока покупатель не выбрал.
`confirmation.url`	string	Страница оплаты для покупателя.
`sbp`	object \| null	Для СБП: qr_payload — содержимое QR-кода, expires_at — срок действия.
`crypto`	object \| null	Для USDT: asset, network, chain, standard, address, amount_crypto, rate, confirmations, confirmations_required, tx_hash, explorer_url, expires_at. До выбора сети network и address — null.
`crypto_network`	string \| null	Сеть, зафиксированная при создании; null — сеть выбирает покупатель.
`card`	object \| null	Для карт после оплаты: brand (mir, visa, mastercard) и last4.
`failure`	object \| null	Причина отказа: code и message.
`livemode`	boolean	false — тестовый платёж.
`created_at`	string	Время создания.
`paid_at`	string \| null	Время успешной оплаты.
`expires_at`	string	Срок, после которого неоплаченный платёж перейдёт в expired.

Платёж в USDT, сеть TON

{
  "id": "pay_7Tn4cVq2LsW9xK1d",
  "object": "payment",
  "status": "pending",
  "amount": 499000,
  "amount_refunded": 0,
  "currency": "RUB",
  "fee": 8982,
  "net": 490018,
  "method": "crypto",
  "description": "Заказ №1043",
  "order_id": "1043",
  "metadata": {},
  "customer": {
    "email": "buyer@example.com"
  },
  "confirmation": {
    "type": "redirect",
    "url": "https://api.nordpay.pro/checkout/pay_7Tn4cVq2LsW9xK1d"
  },
  "sbp": null,
  "crypto": {
    "asset": "USDT",
    "network": "ton",
    "chain": "TON",
    "standard": "Jetton",
    "address": "UQBaLWowuu0AfLvpXwr6Mjk6JJ1VaKLD5hKD32DDzC9eRtyn",
    "amount_crypto": "51.70",
    "rate": "96.52",
    "confirmations": 0,
    "confirmations_required": 1,
    "tx_hash": null,
    "explorer_url": null,
    "expires_at": "2026-11-08T13:00:00Z"
  },
  "crypto_network": "ton",
  "card": null,
  "failure": null,
  "livemode": false,
  "created_at": "2026-11-08T12:00:00Z",
  "paid_at": null,
  "expires_at": "2026-11-08T13:00:00Z"
}

Статусы

Статус	Что значит
`pending`	Создан и ждёт оплаты. Покупатель на странице оплаты.
`processing`	Покупатель оплатил, ждём подтверждения банка или сети.
`succeeded`	Оплачен. Финальный статус для выдачи заказа.
`failed`	Отклонён банком или сетью. Причина — в failure.
`canceled`	Отменён до оплаты.
`expired`	Истёк срок оплаты.
`partially_refunded`	Часть суммы возвращена.
`refunded`	Сумма возвращена полностью.

Выдавайте заказ только по статусу succeeded — из вебхука payment.succeeded или запроса статуса.

Отклонённый платёж

{
  "id": "pay_2Kq8sD1fVxJ7mN4p",
  "object": "payment",
  "status": "failed",
  "method": "card",
  "card": {
    "brand": "visa",
    "last4": "0002"
  },
  "failure": {
    "code": "payment_declined",
    "message": "Банк отклонил операцию"
  }
}

Методы оплаты

СБП (sbp) — покупатель сканирует QR-код или открывает ссылку в приложении своего банка. Если хотите показать QR на своей странице, используйте sbp.qr_payload.
Карты (card) — МИР, Visa, Mastercard. Данные карты вводятся только на странице оплаты NordPay, на ваш сервер они не попадают.
Криптовалюта (crypto) — USDT в сетях TRC20, TON, BEP20, ERC20 и Solana. Сумма в USDT и курс фиксируются в платеже до crypto.expires_at, сеть — параметром crypto_network или выбором покупателя. Подробнее о сетях

Набор методов зависит от подключения вашего магазина. Метод, который не подключён, вернёт ошибку method_unavailable.

СБП: данные для QR

{
  "method": "sbp",
  "sbp": {
    "qr_payload": "https://api.nordpay.pro/checkout/pay_2Kq8sD1fVxJ7mN4p",
    "expires_at": "2026-11-08T12:30:00Z"
  }
}

USDT: сети и подтверждения

Ставка по криптовалюте одна для всех сетей. Сеть можно зафиксировать при создании платежа параметром crypto_network — тогда покупатель сразу увидит адрес. Без него на странице оплаты появится выбор сети, а crypto.network и crypto.address останутся null, пока покупатель не выберет.

Сети USDT
Сеть	Зачисление	Формат адреса
TRON TRC20`trc20`	19 подтверждений около минуты	T…, 34 символа (base58)
TON Jetton`ton`	1 подтверждение несколько секунд	EQ… или UQ…, 48 символов
BNB Smart Chain BEP20`bep20`	15 подтверждений около минуты	0x…, 42 символа
Ethereum ERC20`erc20`	12 подтверждений 3–5 минут	0x…, 42 символа
Solana SPL`sol`	32 подтверждения до 30 секунд	base58, 32–44 символа

Платёж переходит в processing, когда перевод найден в сети; в объекте появляются tx_hash и explorer_url.
crypto.confirmations растёт до confirmations_required; после этого платёж становится succeeded и уходит вебхук payment.succeeded.
Комиссию сети оплачивает отправитель. В ERC20 она заметно выше, чем в остальных сетях, — учитывайте это, если покупатели платят небольшие суммы.

Перевод в другой сети или другой монетой не зачисляется автоматически. Поэтому на странице оплаты покупатель видит сеть рядом с адресом и предупреждение.

USDT в сети TON

curl -X POST https://api.nordpay.pro/v1/payments \
  -H "Authorization: Bearer $NORDPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 499000,
    "currency": "RUB",
    "method": "crypto",
    "crypto_network": "ton",
    "description": "Заказ №1043",
    "order_id": "1043",
    "return_url": "https://shop.example/orders/1043"
  }'

Подтверждения в процессе

{
  "id": "pay_7Tn4cVq2LsW9xK1d",
  "status": "processing",
  "crypto": {
    "network": "ton",
    "confirmations": 0,
    "confirmations_required": 1,
    "tx_hash": "9f3c1b7a…e04d",
    "explorer_url": "https://tonviewer.com/transaction/9f3c1b7a…e04d"
  }
}