Перейти к содержимому
Cashwell

Приём платежей (Pay-In)

Pay-In — приём фиатных средств от вашего клиента с зачислением эквивалента на баланс кабинета в USDT. Вы создаёте сделку, платформа подбирает реквизит и возвращает его в том же ответе, клиент переводит деньги, платформа подтверждает поступление и присылает webhook.

Курс и комиссия фиксируются в момент создания сделки и не меняются до её завершения.

Как проходит сделка

Заголовок раздела «Как проходит сделка»
  1. Вы вызываете POST /payment/pay-in с суммой.
  2. Платформа подбирает реквизит и возвращает сделку в статусе active — с реквизитами, курсом, комиссией и ссылкой на платёжную страницу.
  3. Вы показываете клиенту реквизиты сами либо отправляете его на paymentPageUrl.
  4. Клиент переводит деньги, платформа сверяет поступление.
  5. Вы получаете webhook с финальным статусом.

Перечень статусов и переходов — в разделе Статусы сделок.

Создание сделки

Заголовок раздела «Создание сделки»
POST /payment/pay-in HTTP/1.1
Host: https://svc.cashwell.io
Content-Type: application/json
X-Secure-Key: <ваш API-ключ>


{
  "amount": 5000,
  "method": "c2c",
  "bank": "SBER",
  "merchantTransactionId": "order-1001",
  "callbackUrl": "https://example.com/callback",
  "successUrl": "https://example.com/payment/success",
  "errorUrl": "https://example.com/payment/error",
  "payerInfo": {
    "ip": "203.0.113.45",
    "userId": "usr_847392",
    "userAgent": "Mozilla/5.0 (Linux; Android 13; SM-G991B) Chrome/121.0.0.0 Mobile Safari/537.36",
    "fingerprint": "9d1f2c8a7b6e5d4c3a2f1e0d9c8b7a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1",
    "registeredAt": "1714567890123"
  }
}

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

Заголовок раздела «Параметры запроса»
ПолеТипОбяз.Описание
amountnumberдаСумма в фиатной валюте, от 1 до 3 000 000. Допускает дробные значения
methodstringнетПлатёжный метод. Если не указан, подбирается автоматически
bankstringнетБанк реквизита. Если не указан, подбирается автоматически
payerBankstringнетБанк плательщика. Сохраняется отдельно от банка реквизита и не влияет на подбор
currencystringнетФиатная валюта сделки. По умолчанию — валюта вашего кабинета
merchantTransactionIdstringнетВаш идентификатор операции. Должен быть уникален в рамках кабинета
callbackUrlstringнетАдрес для webhook по этой сделке. Переопределяет настройку кабинета
successUrlstringнетКуда вернуть клиента с платёжной страницы после успешной оплаты
errorUrlstringнетКуда вернуть клиента после неуспешной оплаты
payerInfoobjectнетДанные плательщика — см. ниже
counteragentbooleanнетЗапросить контрагентский реквизит — см. ниже

Выбор банка и метода

Заголовок раздела «Выбор банка и метода»

Оба параметра необязательны, и логика у них одинаковая: указали — получите реквизит именно такой; не указали — платформа подберёт доступный сама.

Список банков, доступных для вашего кабинета, возвращает отдельный публичный метод:

GET /payment/bank
[
  { "bank": "SBER", "label": "Сбербанк", "code": "100000000111", "currency": "RUB" },
  { "bank": "ALFA", "label": "Альфа-Банк", "code": "100000000008", "currency": "RUB" }
]

В поле bank запроса передаётся значение из ключа bank, а не label.

Контрагентские реквизиты

Заголовок раздела «Контрагентские реквизиты»

Флаг counteragent: true переводит запрос в контрагентский канал. Канал выбирается по method:

methodКаналЧто придёт в requisite
c2cКарточныйТолько номер карты
любой другой или не указанСБПТолько номер телефона

Данные плательщика

Заголовок раздела «Данные плательщика»

Блок payerInfo необязателен, но напрямую влияет на качество обработки: по нему работают антифрод-механизмы и разбор спорных ситуаций.

ПолеОписание
ipIP-адрес плательщика
userIdИдентификатор клиента в вашей системе
userAgentUser-Agent браузера или приложения плательщика
fingerprintОтпечаток устройства или сессии по стандарту FingerprintJS
registeredAtДата регистрации клиента у вас, timestamp в миллисекундах строкой

Заполняйте payerInfo всегда, когда данные есть. Это же снижает риск попадания клиента под ограничения: платформа отличает постоянного клиента от нового по совокупности признаков, а не по одной сделке.

Ответ

Заголовок раздела «Ответ»
{
  "category": "trade",
  "id": "45450d2a-e352-439d-9886-134f27c54750",
  "merchantTransactionId": "order-1001",
  "amount": 5000,
  "crypto": "61865875",
  "rate": "80.82",
  "fee": "4330612",
  "type": "pay-in",
  "method": "c2c",
  "status": "active",
  "requisite": {
    "id": "8d920c8f-ca6d-4a69-ada0-fe7f43db286c",
    "bank": "SBER",
    "ownerName": "Иван Иванов",
    "cardNumber": "4111111111111111",
    "sbpNumber": null,
    "accountNumber": null,
    "bankBic": null,
    "currency": "RUB"
  },
  "paymentPageUrl": "https://pay.example.com/external/4b9a1a2c",
  "paymentLifetime": 15,
  "createdAt": "2026-08-23T10:00:00.000Z"
}

Ключевые поля ответа:

  • requisite — куда платить. Показывайте клиенту ownerName, bank и номер карты либо телефона.
  • paymentPageUrl — готовая страница с теми же данными, таймером и кнопкой подтверждения.
  • paymentLifetime — сколько минут у клиента на оплату.
  • crypto и fee — сумма зачисления и комиссия в минимальных единицах USDT.

Полный контракт ответа — в разделе «Создать сделку».

После создания

Заголовок раздела «После создания»

Ничего не делать. Обычный сценарий: клиент платит, платформа сама доводит сделку до success и присылает webhook.

Отменить. Если клиент передумал до оплаты:

POST /payment/pay-in/{id}/cancel

Сделка уйдёт в canceled с cancelReason: "USER_CANCELED".

Продлить таймер. Если клиент не успевает, окно оплаты можно продлить:

POST /payment/pay-in/{id}/extend-timer

Продление одноразовое: второй вызов по той же сделке вернёт ошибку.

Invoice-методы и matching

Заголовок раздела «Invoice-методы и matching»

Методы c2c_invoice и sbp_invoice — часть отдельного сценария: такие Pay-In сделки закрывают ранее созданную заявку на выплату. Если подходящей заявки нет, запрос автоматически переключается на обычный c2c или sbp.

Полный сценарий, включая шаги загрузки чека и подтверждения на платёжной странице, описан в разделе Matching.

Что дальше

Заголовок раздела «Что дальше»