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]"
}