Refund (Withdrawal) Doc API

This guide explains how to generate a new refund document by calling the Create_Refund_Json function.
The function receives a JSON data structure with document header fields and an [Items] array that contains the refund / withdrawal method lines.
After validation, the system produces the original refund document, creates journal entries and cash-management rows when relevant, and returns the generated refund header record in the Doc object.

JSON Structure Example for Refund Creation

{
  "ClientNumber": 500608,
  "Ticket_ID": "WD-998877",
  "InternalDoc_Dont_Send": true,
  "SalesAgent": "Dani",
  "Notes": "Client portal withdrawal request 1234",
  "IPAddress": "203.0.113.25",
  "RefundFormPurpose": 1,
  "MoneyLaundering": 0,
  "Items": [
    {
      "RefundMethod": 2,
      "PaymentDate": "2026-04-26",
      "TotalAmount": 1500.0,
      "Currency": "ILS",
      "BankCode": "12",
      "BranchSwift": "001",
      "Account": "123456",
      "FromInternalAccount": 1100
    }
  ]
}

Refund Document Header Fields

These fields are passed at the root level of the JSON object.
Fields defined as mandatory are marked accordingly.
JSON Field Name Data Type Description
ClientNumber Integer Client number in Hyper. In the client portal endpoint, the server uses the authenticated client session as the actual account.
Ticket_ID String Service ticket number or internal reference used to prevent duplicate refund creation.
InternalDoc_Dont_Send Boolean Whether to prevent sending a signed digital document to the client. Setting to true marks the refund as "Do not distribute".
PersonalIdVerificationMadeBy String Client identity verified by. Must be a valid enabled Hyper username. If not supplied, the Web API sets Online SelfService.
SalesAgent String Sales agent associated with the refund document. Must be a valid enabled Hyper username.
Notes String General notes that will appear on the refund / withdrawal document.
IPAddress String IP address from which the action was performed.
OriginProductionTime DateTime Original production time. If omitted, the server uses the current server time.
ContactPerson String Name of a contact person from the client contact list. When found, address fields are imported from that contact.
Agency Status (Integer) Branch / agency associated with the refund document.
RefundFormPurpose Enum (Integer) Purpose of the refund form.
0 = Retail Refund
1 = Withdrawal from Account
2 = Withdrawal from Loan Account
3 = Property Exchange Service
MoneyLaundering Enum (Integer) AML control level definition for the document.
0 = Normal
1 = Report Anyway
2 = DO NOT Report
MoneyLaunderingBundle Integer AML document bundle number.

Refund Items Array

These rows must be passed within the [Items] array at the root level.
Field Name (in Items array) Data Type Description
RefundMethod Enum (Integer) Refund / withdrawal method (Mandatory Field).
0 = Cash
1 = Credit Card
2 = Bank Transfer
3 = Return Client Cheque
4 = Cheque
5 = Return Assignment of Rights
6 = Return Security Bill
7 = Bill of Exchange
8 = Traveller Check
9 = E. Wallet
PaymentDate Date Refund payment date (Mandatory Field). Must be within the last 366 days.
TotalAmount Double Line refund amount (Mandatory Field). Must be greater than 0.1.
Currency String Refund currency (Mandatory Field). Must exist in the Hyper currency table and must be fiat currency.
ExchangeRate Double Exchange rate. If missing or zero, the system completes it from the live feed using ASK rate logic for refunds.
MonthlyPayments Integer Number of monthly payments. Relevant for credit card refunds.
FirstPaymentAmount Double First payment amount in a credit card refund plan.
NextPaymentsAmount Double Subsequent payment amount in a credit card refund plan.
AdvancedPaymentSys Enum (Integer) Credit transaction definition.
0 = No
1 = External Credit
2 = +30 Days
BankCode String Bank code for bank transfers, cheques, and bank-related refund methods.
BranchSwift String Bank branch or Swift code.
Account String Target bank account number for the refund / withdrawal.
BankTransferPaymentFormat Enum (Integer) Bank transfer format.
0 = unknown (local)
1 = Swift + IBAN
2 = SEPA + IBAN
3 = Swift + BSB
4 = ABA (US)
5 = Swift + CNAPS
6 = Swift Hong Kong
7 = Swift + IBAN + UK sort
ChequeCcNumber String Cheque number, returned cheque reference, bill reference, or last 4 digits of the credit card.
ClearingCompany String Clearing company through which the refund transaction is handled.
CcEwBrand String Credit card or e-wallet brand.
ClearingVoucher String Official clearing voucher / confirmation number.
RegRefundToCountry String Country to which the money is refunded / sent for AML and regulation.
RegBankName String Registered bank name of the recipient account.
RegBankAddress String Registered bank address of the recipient account.
RegAccountOwnerAsContactPerson String Recipient / beneficiary as contact person, when the money is not sent directly to the client.
FromInternalAccount Integer Internal account number from which the money will be withdrawn. If the value is invalid, the system resets it.

Function output

When it succeeds, the function returns the generated refund header record: 
// Function output
{
  "ResponseCode": 0,
  "ResponseMsgEng": "Success",
  "Doc": {
    "RefundNumber": 23451,
    "Agency": 0,
    "DrawerStationId": 0,
    "SalesAgent": "Dani",
    "ClientNumber": 500608,
    "ClientFullName": "Example Client Ltd.",
    "ContactPerson": "",
    "Address": "24 sesame st. Tel aviv",
    "Phone": "03-1234567",
    "Email": "client@example.com",
    "IdNumber": "987654321",
    "ClientCountryCode": "IL",
    "Language": 1,
    "InternationalDocument": 0,
    "TotalRefundLc": 1500.00,
    "PurchaserCurrency": "ILS",
    "TotalRefundInPc": 1500.00,
    "OriginProductionTime": "2026-05-25 10:07:41",
    "CreatedOnUtc": "2026-05-25 07:07:41",
    "ProducedBy": "Dev4_website",
    "ElectronicSignedPdf": 3,
    "Notes": "Client portal withdrawal request 1234",
    "InternalNotes": "WD-998877",
    "RefundFormPurpose": 1,
    "MoneyLaundering": 0,
    "MoneyLaunderingBundle": 0,
    "PersonalIdVerificationMadeBy": "Online SelfService",
    "IpAddress": "203.0.113.25",
    "ResponsibleManager": "",
    "OldDocReference": "",
    "OldSoftwareName": "",
    "CancellationTime": "",
    "CancelledBy": "",
    "CancellationReason": "",
    "AccountBalanceAtProductionTime": 0.00,
    "CreditLineUsageRiskLc": 0,
    "AuthorizationStatus": 0,
    "AuthorizationTextDesc": ""
  }
}

// Function output on error, custom text messages to the same codes list
{
  "ResponseCode": 14,
  "ResponseMsgEng": "Wrong [Refund Method] enum value; Items[0]"
}
Refunds Bank Transfer API

These HTTP endpoints 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 (doc) payment rows that should be handled by the external bank-transfer system.
By default, this endpoint returns rows from refund documents whose authorization status is:
2 = Ready to execute

Request

The request may include an optional Status parameter.
Parameter Required Description
Status 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. 
{
  "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"
}

Feedback Hyper

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 an array named docs. Only refund documents currently in status 2, 3, or 5 can be updated.

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.

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

{
  "ResponseCode":0,
  "ResponseMsgEng":"Success",
  "Skipped": [23453]
}

Error Example

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