Сценарий: возврат

Возврат — отдельная операция поверх уже оплаченного инвойса. Отдельного «инвойса возврата» не создаётся: у исходного меняется status, а результат приходит коллбеком.

Дождитесь оплаты. Возврат принимается только при payment_status: PAID. Попытка вернуть неоплаченный инвойс — сразу 422 INVOICE_NOT_PAID, состояние при этом не меняется, повторять запрос смысла нет.
Запросите возврат: POST /invoices/{invoice_id}/refund с пустым телом {}. Ответ — 202 с invoice_id и refund_status: processing.
Дождитесь коллбека refund.updated (в прежнем конверте — refund.completed): статус возврата придёт в data.invoice.refund_status. Дедуплицируйте его по идентификатору события, как и остальные события (см. «Коллбеки»).
Сверьтесь по инвойсу: после возврата GET /invoices/{invoice_id} отдаёт status: Refund при payment_status: PAID. Признак оплаты не сбрасывается — деньги были списаны, и факт списания остаётся в истории.

В XML-контуре возврат приходит тем же SendPaymentTransaction. Отдельного имени у него нет: уведомление о возврате отличают статус возврата в InvoiceInfo/InvoiceStatus и отсутствие блока PaymentTransactionInfo; песочница возвращает мгновенно и всегда успешно, поэтому шлёт единственный статус Refund. Подробности — в «Коллбеках».

Запрос и ответ


// POST /api/v3/projects/1001/invoices/{invoice_id}/refund
{}
 
// 202 Accepted
{
  "success": true,
  "data": {
    "invoice_id": "4c702dc3-176e-4365-ab4d-8fd22cbcfab1",
    "refund_status": "processing"
  }
}

Инвойс после возврата


// GET /api/v3/projects/1001/invoices/{invoice_id}
{
  "status": "Refund",
  "payment_status": "PAID"
}

Возврат неоплаченного


// 422 Unprocessable Entity
{
  "success": false,
  "error": { "code": "INVOICE_NOT_PAID" }
}