Refunds & Cancellations

Refunds and cancellations are two ways to reverse a transaction that has already been performed. Choosing one or the other depends on two factors:

1. Whether the transaction has already been transmitted to Shva, the Israeli payment processor.

2. Whether you want to credit the customer for the entire amount of the original transaction or just a part of it.

Both a refund and a cancellation return funds to the same credit card that was used in the original debit transaction.

Hyp's implementation of refunds supports fallback to cancellation when the original transaction has not yet been transmitted. This means that in most cases, performing a refund is the right choice.

What is a refund?

A refund "pays back" a transaction that has already taken place and has been transmitted to Shva.

When asked to refund a deal, Hyp creates an entirely new transaction that pays the customer back the full amount of the original debit transaction or a part of it. The customer will see both the original debit transaction and the refund transaction on their bank statement.

A refund can be full or partial. A partial refund credits the customer for part of the amount of the original debit transaction.

A partial refund can also cover part of the installments in an installment transaction. For example, if a customer has purchased a service for 12 months but requests a refund after two months, the refund should cover the remaining 10 months.

To perform a refund with Hyp, you use the refundDeal command. For details, see Performing a refund.

What is a cancellation?

A cancellation means canceling a transaction that has not yet been transmitted to Shva. Only the full amount can be canceled. Any request to cancel a transaction that has already been transmitted to Shva will be rejected.

When asked to cancel a transaction, Hyp:

1. Changes the original transaction's status from "Approved, pending transmission" to "Cancelled".

2. Creates a new transaction of type "Cancellation Transaction".

Depending on the credit card company's policy, the customer may or may not see the original debit transaction and the cancellation transaction on their bank statement.

In most cases, you should perform a refund. When you do so, Hyp automatically chooses whether to refund or cancel based on the status of the transaction.

There is one exception: when you need to cancel an approval (J5) request in a two-phase commit, you should explicitly cancel instead of refunding.

To perform a cancellation with Hyp, use the cancelDeal command. For details, see Performing a cancellation.

How do refund and cancellation work with installments?

By default, when refunding a transaction that was paid in installments, the system creates refund installments that mirror the original payment schedule.

For example, consider an initial purchase in the amount of ₪450 made on January 15, 2025, in 3 installments of ₪150 each. The customer requests a refund after having paid the first installment. By default, the entire payment schedule will be as follows:

1. January 15, 2025: the first installment (₪150) is paid.

2. February 1, 2025: refund requested.

3. February 2, 2025: refund of the first installment (₪150).

4. February 15, 2025: the second installment (₪150) is paid.

5. March 2, 2025: refund of the second installment (₪150).

6. March 15, 2025: the third installment (₪150) is paid.

7. April 2, 2025: refund of the third installment (₪150).

However, you can override this behavior by creating a different number of installments for the refund. For example, you can choose to refund the entire amount in a single installment or create a different number of refund installments than the original. This can be done for both partial and full refunds.

For example, if you choose to refund the entire amount in a single installment, the payment schedule will look like this:

1. January 15, 2025: the first installment (₪150) is paid.

2. February 1, 2025: refund requested.

3. February 2, 2025: full refund (₪450).

4. February 15, 2025: the second installment (₪150) is paid.

5. March 15, 2025: the third installment (₪150) is paid.

Performing a refund

To perform a refund with Hyp, you use the refundDeal command.

refundDeal can fall back to cancellation depending on the transaction's transmission status:

• If the transaction has not been transmitted to Shva yet, a cancellation will be performed.

• If the transaction has been transmitted, a refund will be performed by crediting the credit card used in the original debit transaction.

refundDeal can be performed for an amount equal to (in the case of a full refund) or less than (in the case of a partial refund) the amount of the original transaction.

In the case of a partial refund — even if the original debit transaction has not been transmitted to Shva yet — the original transaction will not change, and a credit transaction will be performed for the partial amount specified in the refundDeal.

To perform a refund, send a standard Hyp API request. In the int_in parameter, include an XML payload for the refundDeal command. The XML payload should look like this:

<ashrait>
    <request>
        <version>2000</version>
        <language>Eng</language>
        <command>refundDeal</command>
        <refundDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <tranId>{transactionId}</tranId>
        </refundDeal>
    </request>
</ashrait>

The command element should be set to refundDeal, and the refundDeal element must contain the following child elements:

• terminalNumber: a unique number assigned to you as a merchant during registration.

• One or more "lookup elements" that help identify the original debit transaction. These elements are optional, but at least one must be present in the request. Depending on your terminal settings, some of the lookup elements can be made required. In the example above, tranID is the lookup element. Here's the full list of lookup elements you can use to search for the original transaction:

  • cgUid: the CG identifier assigned to each transaction, as returned in the original debit transaction response. All API requests related to the same "financial transaction" (for example, in a two-phase commit) will share the same cgUid value. If cgUid is used for lookup, Hyp will find the latest transaction state associated with that cgUid.

  • tranId: the unique transaction request ID that identifies a specific step of a financial transaction. For example, there will be multiple tranId values in a two-phase commit. When tranId is used, Hyp will search for the original debit transaction by this ID and ignore all other lookup elements in the request. You can retrieve a tranId by sending an inquire request.

  • orgUid: the unique transaction ID assigned by Shva. When you send an inquire request, the response contains a uid element, and you can use its value for orgUid. Unlike the other lookup elements, orgUid must be wrapped in an ashraitEmvData element:

    <ashraitEmvData>
        <orgUid/>
    </ashraitEmvData>

  • user: the user element value used in the original debit transaction.

The refundDeal command may also contain the following optional elements in case of partial refunds or refunds of installment transactions:

• total: the total amount to be refunded, in currency subunits such as cents or agorot. For example, to refund $47.30, the value passed in the total element should be 4730. This value must be less than (for a partial refund) or equal to the original debit transaction amount. If total is not provided, the full amount of the original debit transaction will be refunded.

• creditType: set to Payments or SpecialCredit if the refund is for a transaction that involved installments. Use Payments for regular installments, or SpecialCredit for credit installments.

• firstPayment: the amount of the first installment, in currency subunits such as cents or agorot. This is only used if the original transaction was an installment transaction. When refunding an installment transaction, the total refund amount must equal firstPayment plus periodicalPayment multiplied by numberOfPayments.

• periodicalPayment: the amount of each subsequent installment, in currency subunits such as cents or agorot. This is only used if the original transaction was an installment transaction.

• numberOfPayments: the number of payments in the refund transaction. This overrides the default behavior of mirroring the original transaction's payment schedule. For example, setting this to 1 allows you to issue the entire refund as a single installment, regardless of the original payment schedule.

Depending on the values in the lookup element and the set of lookup elements used, Hyp may find multiple transactions that match the search criteria. If this happens and the terminal setting "Block multiple matches" is enabled, Hyp will return an error. If that setting is disabled, Hyp will apply the refund to the most recent debit transaction that matches the search criteria.

If there are no errors, the refundDeal request results in a credit transaction issued to the credit card used in the original transaction.

Examples of refund requests

The following XML payload in a refundDeal request looks for the original transaction by the CG identifier and performs a full refund:

<ashrait>
    <request>
        <version>2000</version>
        <language>Eng</language>
        <command>refundDeal</command>
        <refundDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cgUid>118372223</cgUid>
        </refundDeal>
    </request>
</ashrait>

This request searches for the original transaction using the CG identifier 118372223, locates it, and performs a refund for the full amount of the original transaction. A successful outcome is indicated by the 000 result code in the response.

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>refundDeal</command>
        <dateTime>2025-06-26 17:37</dateTime>
        <requestId />
        <tranId>118372255</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo>Host Result Remote 00-SUCCESS </additionalInfo>
        <version>2000</version>
        <language>Eng</language>
        <refundDeal>
            <status>000</status>
            <statusText>Permitted transaction</statusText>
            <extendedStatus />
            <extendedStatusText />
            <extendedUserMessage />
            <terminalNumber>0882819014</terminalNumber>
            <cardId>1092880571131111</cardId>
            <cardBin>411111</cardBin>
            <cardMask>411111******1111</cardMask>
            <cardLength>16</cardLength>
            <cardNo>xxxxxxxxxxxx1111</cardNo>
            <cardName />
            <cardExpiration>0629</cardExpiration>
            <cardType code="99">Foreign</cardType>
            <extendedCardType code="0" />
            <creditCompany code="0">Foreign</creditCompany>
            <cardBrand code="2">Visa</cardBrand>
            <cardAcquirer code="6">Alphacard</cardAcquirer>
            <serviceCode />
            <transactionType code="52">Cancel</transactionType>
            <creditType code="1">RegularCredit</creditType>
            <currency code="1">ILS</currency>
            <baseCurrency />
            <baseAmount />
            <transactionCode code="50">Phone</transactionCode>
            <total>11400</total>
            <firstPayment />
            <periodicalPayment />
            <numberOfPayments>0</numberOfPayments>
            <clubId />
            <validation code="4">AutoComm</validation>
            <idStatus code="0">Absent</idStatus>
            <cvvStatus code="3">NotValidated</cvvStatus>
            <authSource code="2">CreditCompany</authSource>
            <authNumber>7823673</authNumber>
            <fileNumber>39</fileNumber>
            <slaveTerminalNumber>084</slaveTerminalNumber>
            <slaveTerminalSequence>536</slaveTerminalSequence>
            <eci>7</eci>
            <clientIp>172.16.100.7</clientIp>
            <email />
            <cavv code="" />
            <user />
            <addonData />
            <supplierNumber>300012</supplierNumber>
            <id />
            <shiftId1 />
            <shiftId2 />
            <shiftId3 />
            <shiftTxnDate />
            <cgUid>118372223</cgUid>
            <cardHash />
            <acquirerData>
                <gateway>AshraitEmv</gateway>
                <acquirerResponseId>793570913929</acquirerResponseId>
                <mcc>4121</mcc>
                <mpi3dsSupport>0</mpi3dsSupport>
                <avsResponse code="0">Absent</avsResponse>
                <acquirerTranType>53</acquirerTranType>
                <acquirerTranCode>50</acquirerTranCode>
            </acquirerData>
            <ashraitEmvData>
                <orgUid>25062617340908828192261</orgUid>
                <orgAuthCodeCreditCompany>1</orgAuthCodeCreditCompany>
                <orgAuthCodeAcquirer>0</orgAuthCodeAcquirer>
                <orgAuthNo>7842608</orgAuthNo>
                <orgAmount>11400</orgAmount>
                <orgTranDate>0626</orgTranDate>
                <orgCvvFlag>1</orgCvvFlag>
                <orgTranTime>173409</orgTranTime>
                <authCodeCreditCompany code="1">CreditCompanyAuthorized</authCodeCreditCompany>
                <uid>25062617340908828192261</uid>
                <manufId>CGD</manufId>
                <catLevel>0</catLevel>
                <manufUse>001101</manufUse>
                <ashVersion>x</ashVersion>
                <ashTermType>0</ashTermType>
                <emvResponseCode>00</emvResponseCode>
                <deviceStatus>1111000000</deviceStatus>
                <ashReasonText>SUG_ISKA</ashReasonText>
                <authCodeAcquirer code="0">NoAuthNumber</authCodeAcquirer>
                <isDoReverseDeal>0</isDoReverseDeal>
                <mti>400</mti>
            </ashraitEmvData>
            <extendedTranCode />
            <sendNotification />
        </refundDeal>
    </response>
</ashrait>

The following XML payload in a refundDeal request also locates the original transaction using the CG identifier, but performs a partial refund of ₪200 from the original ₪464 installment transaction, issuing the refund in a single installment:

<ashrait>
    <request>
        <version>2000</version>
        <language>Eng</language>
        <command>refundDeal</command>
        <refundDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cgUid>119042011</cgUid>
            <creditType>Payments</creditType>
            <firstPayment>10000</firstPayment>
            <periodicalPayment>10000</periodicalPayment>
            <numberOfPayments>1</numberOfPayments>
            <total>20000</total>
        </refundDeal>
    </request>
</ashrait>

Performing a cancellation

To cancel a transaction using Hyp, send a standard Hyp API request. In the int_in parameter, include an XML payload with the cancelDeal command. The XML payload should look like this:

<ashrait>
    <request>
        <version>2000</version>
        <language>Eng</language>
        <command>cancelDeal</command>
        <cancelDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <tranId>{transactionId}</tranId>
        </cancelDeal>
    </request>
</ashrait>

The child elements of cancelDeal are similar to those used in refundDeal — see Performing a refund for details. The key differences are:

1. cancelDeal does not support partial cancellations.

2. Optional elements like total and installment-related elements are not used.

Example of a cancellation request

The following XML payload in a cancelDeal request locates the original transaction using the CG identifier:

<ashrait>
    <request>
        <version>2000</version>
        <language>Eng</language>
        <command>cancelDeal</command>
        <cancelDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cgUid>118374610</cgUid>
        </cancelDeal>
    </request>
</ashrait>

This request searches for the original transaction using the CG identifier 118374610, finds it, and cancels the transaction. A successful outcome is indicated by the 000 result code in the response.

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>cancelDeal</command>
        <dateTime>2025-06-26 20:20</dateTime>
        <requestId />
        <tranId>118374656</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo>Host Result Remote 00-SUCCESS </additionalInfo>
        <version>2000</version>
        <language>Eng</language>
        <cancelDeal>
            <status>000</status>
            <statusText>Permitted transaction</statusText>
            <extendedStatus />
            <extendedStatusText />
            <extendedUserMessage />
            <terminalNumber>0882819014</terminalNumber>
            <cardId>1092880571131111</cardId>
            <cardBin>411111</cardBin>
            <cardMask>411111******1111</cardMask>
            <cardLength>16</cardLength>
            <cardNo>xxxxxxxxxxxx1111</cardNo>
            <cardName />
            <cardExpiration>0327</cardExpiration>
            <cardType code="99">Foreign</cardType>
            <extendedCardType code="0" />
            <creditCompany code="0">Foreign</creditCompany>
            <cardBrand code="2">Visa</cardBrand>
            <cardAcquirer code="6">Alphacard</cardAcquirer>
            <serviceCode />
            <transactionType code="52">Cancel</transactionType>
            <creditType code="1">RegularCredit</creditType>
            <currency code="1">ILS</currency>
            <baseCurrency />
            <baseAmount />
            <transactionCode code="50">Phone</transactionCode>
            <total>36500</total>
            <firstPayment />
            <periodicalPayment />
            <numberOfPayments>0</numberOfPayments>
            <clubId />
            <validation code="4">AutoComm</validation>
            <idStatus code="0">Absent</idStatus>
            <cvvStatus code="3">NotValidated</cvvStatus>
            <authSource code="2">CreditCompany</authSource>
            <authNumber>3264853</authNumber>
            <fileNumber>39</fileNumber>
            <slaveTerminalNumber>084</slaveTerminalNumber>
            <slaveTerminalSequence>544</slaveTerminalSequence>
            <eci>7</eci>
            <clientIp>172.16.100.7</clientIp>
            <email />
            <cavv code="" />
            <user />
            <addonData />
            <supplierNumber>300012</supplierNumber>
            <id />
            <shiftId1 />
            <shiftId2 />
            <shiftId3 />
            <shiftTxnDate />
            <cgUid>118374610</cgUid>
            <cardHash />
            <acquirerData>
                <gateway>AshraitEmv</gateway>
                <acquirerResponseId>336808321140</acquirerResponseId>
                <mcc>4121</mcc>
                <mpi3dsSupport>0</mpi3dsSupport>
                <avsResponse code="0">Absent</avsResponse>
                <acquirerTranType>53</acquirerTranType>
                <acquirerTranCode>50</acquirerTranCode>
            </acquirerData>
            <ashraitEmvData>
                <orgUid>25062620132408828196133</orgUid>
                <orgAuthCodeCreditCompany>1</orgAuthCodeCreditCompany>
                <orgAuthCodeAcquirer>0</orgAuthCodeAcquirer>
                <orgAuthNo>3337593</orgAuthNo>
                <orgAmount>36500</orgAmount>
                <orgTranDate>0626</orgTranDate>
                <orgCvvFlag>1</orgCvvFlag>
                <orgTranTime>201324</orgTranTime>
                <authCodeCreditCompany code="1">CreditCompanyAuthorized</authCodeCreditCompany>
                <uid>25062620132408828196133</uid>
                <manufId>CGD</manufId>
                <catLevel>0</catLevel>
                <manufUse>001101</manufUse>
                <ashVersion>x</ashVersion>
                <ashTermType>0</ashTermType>
                <emvResponseCode>00</emvResponseCode>
                <deviceStatus>1111000000</deviceStatus>
                <ashReasonText>SUG_ISKA</ashReasonText>
                <authCodeAcquirer code="0">NoAuthNumber</authCodeAcquirer>
                <isDoReverseDeal>0</isDoReverseDeal>
                <mti>400</mti>
            </ashraitEmvData>
            <extendedTranCode />
            <sendNotification />
        </cancelDeal>
    </response>
</ashrait>

API error codes

The table below lists possible error codes returned by the refundDeal and cancelDeal commands, along with their corresponding messages.

Error code	Message
310	There is no debit deal that matches the credit deal.
312	There is no transaction found for canceling.
313	The transaction for canceling has already been transmitted.
314	The transaction has already been canceled.
317	Some parameters are missing for the required transaction.
319	The terminal is not permitted to accept a canceling command.
320	A credit transaction has already been performed.
321	The credit amount is different than the charge deal amount.
324	The terminal is not permitted to perform refund transactions.
332	More than one transaction was found for cancel/conditional refund commands.
339	Refund credit type is different from original transaction.
340	Refund number of payments is different from original transaction.
341	Refund amount is different from original transaction.

Terminal configuration

Each terminal has settings that control how the refundDeal and cancelDeal commands operate, including the search criteria allowed for locating the original transaction. All these settings are listed in the following table.

Terminal setting	Description	Default
Allow cancel deal	Allows the terminal to receive cancelDeal requests.	Enabled
Allow refund deal	Allows the terminal to receive refundDeal requests.	Enabled
In refund deal request, cancel non-transmitted transaction	Determines whether the refundDeal command should fall back to performing a cancellation if the transaction has not been transmitted to Shva.	Enabled
Must search by card number	Requires the cardNumber or cardId element in the request.	Disabled
Search by (and must send) X field (user field)	Requires the user element in the request. Assumes the original transaction included this element.	Disabled
Must search by Transaction ID field	Requires the tranId element in the request.	Disabled
Search by (and must send) Authorization Number field	Requires the authNumber element in the request.	Disabled
Allow different amount	Allows partial refunds.	Enabled
Block multiple matches	If enabled, the system returns an error when multiple matching transactions are found. If disabled, the most recent matching transaction is used.	Enabled
Terminal numbers for searching the original transaction	By default, the terminal used for refund or cancellation must match the original transaction's terminal. This setting allows specifying a different terminal number for searching the original transaction.	Not set; original transactions are looked up in the same terminal
Search credit that is made via do deal	When enabled, this setting allows searching for the original debit transaction when performing a credit with the doDeal command or via the manual transaction screen in Hyp Console. This makes credit transactions performed with doDeal behave similarly to refundDeal transactions.	Disabled
Overwrite expiration date	If the original card has expired, sends an updated expiration date. Transaction approval is not guaranteed.	Disabled