# 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](https://www.shva.co.il/about-us/), 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](/creditguard/payment-page-integration/installments.md) 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](#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](/creditguard/two-phase-commits/overview.md), you should explicitly cancel instead of refunding.

To perform a cancellation with Hyp, use the `cancelDeal` command. For details, see [Performing a cancellation](#performing-a-cancellation).

## How do refund and cancellation work with installments?

By default, when refunding a transaction that was paid in [installments](/creditguard/payment-page-integration/installments.md), 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](/creditguard/introduction/request-and-response-general-structure.md). In the `int_in` parameter, include an XML payload for the `refundDeal` command. The XML payload should look like this:

```xml
<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](/creditguard/introduction/prerequisites-and-requirements.md).
* 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](#terminal-configuration), 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](/creditguard/two-phase-commits/overview.md)) 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](/creditguard/inquiring-transactions/overview.md).
  * `orgUid`: the unique transaction ID assigned by Shva. When you send an [inquire request](/creditguard/inquiring-transactions/overview.md), 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:

    ```xml
    <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](/creditguard/payment-page-integration/installments.md). 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](#terminal-configuration) "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:

```xml
<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.

<details>

<summary>Show response</summary>

```xml
<?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>
```

</details>

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:

```xml
<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](/creditguard/introduction/request-and-response-general-structure.md). In the `int_in` parameter, include an XML payload with the `cancelDeal` command. The XML payload should look like this:

```xml
<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](#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:

```xml
<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.

<details>

<summary>Show response</summary>

```xml
<?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>
```

</details>

## 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                                                          |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.hyp.co.il/creditguard/additional-payment-scenarios/refunds-and-cancellations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.