Быстрый старт

Эта страница проводит через минимальную рабочую интеграцию: создать Pay-In сделку, показать клиенту реквизиты и обработать webhook. Подробности каждого шага — в разделах по ссылкам.

Что понадобится

Что	Где взять
API-ключ	Раздел «Настройки» в кабинете — Кабинет и API-ключ
IP-адреса ваших серверов	Передаются менеджеру до начала работы — IP Whitelist
HTTPS-endpoint для webhook	На вашей стороне — Webhook

Базовый адрес API:

https://svc.cashwell.io

Шаг 1. Проверьте ключ

Самый дешёвый способ убедиться, что ключ рабочий и ваш IP пропускают, — запросить баланс кабинета.

curl -X GET 'https://svc.cashwell.io/merchant' \
  -H 'X-Secure-Key: <ваш API-ключ>'

{ "balance": "1000000" }

Баланс приходит в минимальных единицах USDT: делите на 1 000 000, чтобы получить сумму в USDT. В примере выше — 1 USDT.

Если вместо баланса вернулось 401 INVALID_API_KEY — ключ неверный. Если 403 IP_NOT_IN_WHITELIST — запрос пришёл с адреса, которого нет в списке разрешённых.

Шаг 2. Укажите адрес для webhook

Без него вы не узнаете, что сделка оплачена.

curl -X PATCH 'https://svc.cashwell.io/merchant' \
  -H 'X-Secure-Key: <ваш API-ключ>' \
  -H 'Content-Type: application/json' \
  -d '{ "callbackUrl": "https://example.com/callback" }'

Адрес можно задать и в кабинете, и отдельно для каждой сделки — полем callbackUrl в теле запроса на создание.

Шаг 3. Создайте Pay-In сделку

curl -X POST 'https://svc.cashwell.io/payment/pay-in' \
  -H 'X-Secure-Key: <ваш API-ключ>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "method": "c2c",
    "merchantTransactionId": "order-1001",
    "payerInfo": {
      "ip": "203.0.113.45",
      "userId": "usr_847392"
    }
  }'

Обязательна только amount. Всё остальное опционально, но merchantTransactionId стоит передавать всегда: по нему вы потом найдёте сделку и отличите повторную доставку webhook от новой операции.

Шаг 4. Покажите клиенту реквизиты

В ответе придёт сделка в статусе active. Дальше есть два пути.

Свой интерфейс — возьмите реквизиты из поля requisite и покажите их сами:

{
  "id": "9ee42dff-83ec-4a90-8dfb-1fc74d3afbe4",
  "status": "active",
  "amount": 5000,
  "method": "c2c",
  "requisite": {
    "bank": "SBER",
    "cardNumber": "4111111111111111",
    "ownerName": "Иван Иванов",
    "currency": "RUB"
  },
  "paymentPageUrl": "https://pay.example.com/external/4b9a1a2c",
  "paymentLifetime": 15,
  "createdAt": "2026-08-23T10:00:00.000Z"
}

Готовая платёжная страница — отправьте клиента на paymentPageUrl.

paymentLifetime — время в минутах, за которое клиент должен оплатить. Когда оно истечёт, сделка перейдёт в canceled с cancelReason: "TIMEOUT".

Шаг 5. Примите webhook

Как только сделка меняет состояние, на ваш callbackUrl приходит POST с телом сделки и заголовком x-signature.

POST /callback HTTP/1.1
Content-Type: application/json
x-signature: 7d3a1f...

Порядок обработки:

Прочитайте тело запроса как есть, без пересборки JSON.
Посчитайте HMAC-SHA256(тело, ваш API-ключ) в hex и сравните с x-signature.
Если подписи не совпали — верните 401 и не обрабатывайте запрос.
Если совпали — верните 200 и обработайте событие.

Готовые примеры проверки на шести языках — в разделе Подпись запросов.

Шаг 6. Отреагируйте на финальный статус

Отгружайте товар или зачисляйте средства только на финальных статусах.

Статус	Что произошло
`success`	Оплата прошла на ожидаемую сумму
`success_changed`	Оплата прошла, но сумма пересчитана по факту платежа — сверяйтесь с `amount` из уведомления
`canceled`	Оплата не состоялась, причина — в `dispute.cancelReason`

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

Что дальше

Как работает Pay-In — все параметры создания сделки и выбор банка
Как работает Pay-Out — выплаты на реквизиты получателей
Коды ошибок — что означает каждый ответ с ошибкой
Надёжность интеграции — ретраи, идемпотентность и тайм-ауты