Документация / Интеграция

Возвраты

Возврат — перевод клиенту обратно: при отмене заказа, переплате или недоплате после срока. Создаётся заявкой через API или в кабинете.

Кто отправляет деньги

Зависит от поля заявки executor:

merchant — оплата пришла на ваш кошелёк (обычный случай). Coinetic ваших средств не держит: перевод клиенту отправляете вы сами и записываете хеш транзакции.
platform — оплата пришла на кошелёк платформы. Вы только запрашиваете возврат; адрес проверяет, одобряет и отправляет оператор Coinetic.

Правила

Только в активе оплаты. Клиент платил USDT в TRON — получит USDT в TRON. Конвертации нет.
Не больше оплаченного — смотрите refundable_amount счёта. Частями можно, до 20 открытых заявок на счёт.
Адрес — в сети оплаты. Проверяется по формату сети (EVM — контрольная сумма EIP-55). Адреса самого Coinetic не принимаются.
Оплаченный счёт остаётся оплаченным. Сколько возвращено — refunded_amount.
Неоплаченный счёт возврат закрывает навсегда, даже частичный: счёт станет cancelled, доплаты заказ уже не оплатят. Проверьте статус счёта до заявки.

Создать заявку

POST/v1/refunds

HTTP

POST /v1/refunds
Idempotency-Key: refund-ORDER-1001-1
Content-Type: application/json

{"invoice_id":"inv_x7k2…","amount_minor":"10500000","address":"TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE","reason":"Отмена заказа ORDER-1001"}

Поле	Обязательно	Значение
`invoice_id`	да	Счёт вашего магазина
`amount_minor`	да	Минимальные единицы строкой (`"10500000"` = 10,5 USDT при 6 знаках) или `"full"` — вся доступная сумма
`address`	да	Адрес клиента в сети оплаты
`reason`	нет	Причина, до 500 символов

Возврат с вашего кошелька

Отправьте клиенту amount заявки в активе и сети оплаты со своего кошелька (комиссию сети платите вы).
Запишите хеш транзакции:

HTTP

POST /v1/refunds/{id}/executed
Idempotency-Key: refund-exec-ORDER-1001-1
Content-Type: application/json

{"tx_hash":"0x5c50…","ack_status_change":false}

Заявка перейдёт в reported. В EVM-сетях (Ethereum, BSC, Polygon, Base, Arbitrum) Coinetic сам найдёт подтверждённую транзакцию в блокчейне и переведёт заявку в sent с вебхуком refund.sent. В Bitcoin, Litecoin, TRON и Solana автоматической проверки пока нет — заявка остаётся reported.

Передумали — POST /v1/refunds/{id}/cancel с причиной: сумма снова доступна к возврату.

Статусы

Статус	Значение
`requested`	Заявка принята
`approved`	Одобрена оператором (только `executor: platform`)
`reported`	Вы сообщили хеш, ждём подтверждения в сети
`sent`	Деньги отправлены, `tx_hash` — транзакция в сети
`rejected`	Отклонена или отменена, причина — в `reject_reason`

Отказ вебхуком не сообщается — проверяйте открытые заявки по расписанию: GET /v1/refunds?status=requested.

В песочнице

POST /v1/refunds/{id}/simulate проводит весь путь сразу: заявка становится sent с тестовым tx_hash, приходит refund.sent. В продакшене маршрута нет.