Документація / Інтеграція

Повернення

Повернення — це переказ коштів назад клієнту: у разі скасування замовлення, переплати чи недоплати після терміну. Створюється заявкою через 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. У продакшні цього маршруту немає.