Refunds Bank Transfer API

These HTTP endpoints are used by an external bank-transfer system to read and update outgoing refund / withdrawal requests.
These endpoints are intended for trusted internal integrations only! you need to enable 'Unprotected Accounting API' inside
[Domain Enabled Modules]
field.

Call Query_Refunds_API_Queue_json to get refund payment rows that should be handled by the external bank-transfer system.
The endpoint first selects non-cancelled refund documents, then returns their payment rows. By default, it selects documents whose authorization status is:
2 = Ready to execute

Queue Selection and Recipient Name

Only refund documents whose
[Cancellation Time]
is empty are included.
The returned payment rows are sorted by
[Refund Number]
and then by
[Row Index]
.
For every returned row, the bank-transfer recipient is supplied in RegAccountOwnerAsContactPerson. If this value is empty, Hyper copies the document's
[Client Full Name]
into that response field. The bank-transfer system can therefore use RegAccountOwnerAsContactPerson as the recipient name without a separate fallback.

Request

The request may include an optional Status parameter. This endpoint support both Get and Post (json or urlencoded).
Parameter Required Description
Status (string) No Optional queue filter.
Use "execution failed" to query failed refunds.
Use "sent awaiting result" to query refunds already sent to the bank and waiting for final result.
Any other value, or an empty value, returns refunds ready to execute.

Successful Response

The response contains a Queue array with refund item rows. It is returned only when at least one matching payment row exists. 
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Queue":[
    {
      "RefundNumber":67393,
      "RowIndex":1,
      "RefundMethod":2,
      "PaymentDate":"2026-04-01",
      "TotalAmount":150.00,
      "Currency":"ILS",
      "BankCode":"",
      "BranchSwift":"TCCLGB3L",
      "Account":"GB31TCCL04140459442098",
      "BankTransferPaymentFormat":1,
      "RegRefundToCountry":"הממלכה המאוחדת (בריטניה)",
      "RegBankName":"",
      "RegBankAddress":"",
      "RegAccountOwnerAsContactPerson":"אריאל שמואל הקר",
      "FromInternalAccount":95,
      "FromInternalAccountName":"קראנסיי קלאוד"
    }
  ]
}

No Results

{
  "ResponseCode":2,
  "ResponseMsgEng":"No Results \/ Data"
}

Update Refund Queue

Call Update_Refunds_API_Queue_json to update the bank-transfer authorization status of refund documents after the external system processes them.
The endpoint accepts a non-empty array named docs. It first loads only the requested refund documents that currently have status 2, 3, or 5.
For each submitted array item, Hyper updates the document only when its RefundNumber was found in that protected selection and its new status is in the range 2 through 5. Every other submitted item is returned in Skipped.

Request Fields

JSON Field Required Description
docs Yes Array of refund documents to update.
RefundNumber Yes Refund document number in Hyper.
AuthorizationStatus Yes New status to write back.
2 = Ready to execute
3 = Sent - awaiting result
4 = Executed successfully
5 = Execution failed
AuthorizationTextDesc No Free text returned by the bank-transfer system, such as external request ID, bank reference, or error message.
For an eligible document, this field is written exactly as received. If it is omitted, its existing text is cleared.

Example Request

{
  "docs": [
    {
      "RefundNumber": 23451,
      "AuthorizationStatus": 3,
      "AuthorizationTextDesc": "Sent to bank API. External request id: BNK-778899"
    },
    {
      "RefundNumber": 23452,
      "AuthorizationStatus": 4,
      "AuthorizationTextDesc": "Executed successfully. Bank reference: TRX-445566"
    },
    {
      "RefundNumber": 23453,
      "AuthorizationStatus": 5,
      "AuthorizationTextDesc": "Execution failed: beneficiary account rejected"
    }
  ]
}

Successful Response

Skipped contains refund numbers that were not updated: for example, an invalid number, a document not found in an updatable current status, or a new status outside the range 2 through 5.
The endpoint saves changes only when at least one document was updated. 
{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Skipped": [23453]
}

Error Example

{
  "ResponseCode": 14,
  "ResponseMsgEng": "docs array does not contain valid refund numbers"
}