> For the complete documentation index, see [llms.txt](https://developers.hyp.co.il/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.hyp.co.il/enterprise/advanced-security-guidelines/transaction-validation.md).

# Transaction Validation

Once you've received a response that signifies a completed transaction, such as a [payment completion redirect](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#handle-payment-completion-redirect), you may want to validate the transaction. Validation is not required, but if you're bound by regulatory requirements or simply want to double-check that the transaction has not been altered in transit, you can validate it.

There are two ways to validate a transaction:

1. By comparing the MAC (message authentication code) received from Hyp with the MAC that you calculate yourself.
2. By making an additional API call, providing the transaction ID and receiving a response that confirms the outcome of the transaction.

## Validating a transaction using the MAC

The preferred way of validating a transaction is by comparing the MAC (message authentication code) that Hyp Enterprise provides in the [payment completion redirect](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#handle-payment-completion-redirect) with the MAC that you calculate yourself. This method does not introduce any network latency and can be safely used to validate all transactions.

In the query string that Hyp Enterprise passes in the payment completion redirect, one of the parameters, `responseMac`, is the transaction MAC that Hyp calculates. You should use several of the other parameters, along with your merchant password, to calculate the MAC on your end, and then compare it to `responseMac`. If they're identical, the transaction is valid.

First, concatenate the following values in this exact order:

1. Your merchant password.
2. `txId` (transaction ID) from the payment completion redirect.
3. `errorCode` (if received; `000` otherwise).
4. `cardToken` (if received; an empty string otherwise).
5. `cardExp` (if received; an empty string otherwise).
6. `personalId` (if received; an empty string otherwise).
7. `uniqueId` (your unique merchant ID).

If any parameters are empty, use an empty string instead. One notable exception is `errorCode`: if it's empty, use the value `000`.

Hash the resulting string using SHA-256, encode it as a hexadecimal string, and compare the resulting value with `responseMac`.

For a hands-on example of validating a transaction using the MAC in a sample Express.js application, see [Basic Integration Flow: Hello World With a Full Working Charge](https://developers.hyp.co.il/enterprise/introduction/basic-integration-flow-hello-world-with-a-full-working-charge.md).

## Validating a transaction using an API call

You can also validate a transaction by making an additional API call, which is a variation of a [transaction inquiry](https://developers.hyp.co.il/enterprise/inquiring-transactions/overview.md). This call adds network latency compared to the MAC validation method, but the upside is that it provides more information about the transaction (card type, issuer, etc.) if that's what you're looking for.

To validate a transaction, send a [standard Hyp Enterprise API request](https://developers.hyp.co.il/enterprise/introduction/request-and-response-general-structure.md). In the `int_in` parameter, include an XML payload with the `inquireTransactions` command. The XML payload should look like this:

```xml
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>inquireTransactions</command>
        <inquireTransactions>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <queryName>mpiTransaction</queryName>
            <mid>{mid}</mid>
            <mpiTransactionId>{txId}</mpiTransactionId>
        </inquireTransactions>
    </request>
</ashrait>
```

The `command` element should be set to `inquireTransactions`, and the `inquireTransactions` element must include the following child elements:

* `terminalNumber`: a unique number assigned to you as a merchant during [registration](https://developers.hyp.co.il/enterprise/introduction/prerequisites-and-requirements.md).
* `mid`: merchant ID assigned to you as a merchant during [registration](https://developers.hyp.co.il/enterprise/introduction/prerequisites-and-requirements.md).
* `mpiTransactionId`: the transaction ID that is returned as the `txId` parameter in the [payment completion redirect](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#handle-payment-completion-redirect).
* `queryName`: must be set to `mpiTransaction`.

If the transaction is found, the response will look like this:

<details>

<summary>Show response</summary>

```xml
<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireTransactions</command>
        <dateTime>2025-08-18 18:40</dateTime>
        <requestId/>
        <tranId>119536912</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo/>
        <version>2000</version>
        <language>Eng</language>
        <inquireTransactions>
            <row>
                <mpiTransactionId>f1504d81-c564-4f93-a13d-c904789e8597</mpiTransactionId>
                <uniqueid>b84e39d4-2697-43f8-a268-ce4e54e2c7ca</uniqueid>
                <amount>11400</amount>
                <currency>ILS</currency>
                <authNumber>8062977</authNumber>
                <cardId>1092880571131111</cardId>
                <languageCode>EN</languageCode>
                <statusCode>0</statusCode>
                <statusText>SUCCEEDED</statusText>
                <errorCode>00</errorCode>
                <errorText>SUCCESS</errorText>
                <cgGatewayResponseCode>000</cgGatewayResponseCode>
                <cgGatewayResponseText>Permitted transaction</cgGatewayResponseText>
                <cgGatewayResponseXML>
                    <ashrait>
                        <response>
                            <command>doDeal</command>
                            <dateTime>2025-08-18 18:40</dateTime>
                            <requestId/>
                            <tranId>119536911</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>
                            <doDeal>
                                <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">Credit</extendedCardType>
                                <blockedCard/>
                                <lifeStyle/>
                                <customCardType/>
                                <creditCompany code="0">Foreign</creditCompany>
                                <cardBrand code="2">Visa</cardBrand>
                                <cardAcquirer code="6">Alphacard</cardAcquirer>
                                <serviceCode/>
                                <transactionType code="01">RegularDebit</transactionType>
                                <creditType code="1">RegularCredit</creditType>
                                <currency code="1">ILS</currency>
                                <baseCurrency/>
                                <baseAmount/>
                                <transactionCode code="52">Internet</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>8062977</authNumber>
                                <fileNumber>40</fileNumber>
                                <slaveTerminalNumber>086</slaveTerminalNumber>
                                <slaveTerminalSequence>318</slaveTerminalSequence>
                                <eci>7</eci>
                                <clientIp>169.150.226.170</clientIp>
                                <email/>
                                <cavv code=""/>
                                <user>1eee7e8a-b1f2-4b5c</user>
                                <addonData/>
                                <supplierNumber>300012</supplierNumber>
                                <id/>
                                <shiftId1/>
                                <shiftId2/>
                                <shiftId3/>
                                <shiftTxnDate/>
                                <cgUid>119536889</cgUid>
                                <cardHash/>
                                <customerData>
                                    <userData1>Jenny Parkington</userData1>
                                </customerData>
                                <acquirerData>
                                    <gateway>AshraitEmv</gateway>
                                    <acquirerTranType>01</acquirerTranType>
                                    <mcc>4121</mcc>
                                    <acquirerResponseId>599434237938</acquirerResponseId>
                                    <avsResponse code="0">Absent</avsResponse>
                                    <acquirerTranCode>52</acquirerTranCode>
                                </acquirerData>
                                <ashraitEmvData>
                                    <uid>25081818401308828199114</uid>
                                    <authCodeCreditCompany code="1">CreditCompanyAuthorized</authCodeCreditCompany>
                                    <idFlag>0</idFlag>
                                    <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>100</mti>
                                </ashraitEmvData>
                                <extendedTranCode/>
                                <sendNotification/>
                            </doDeal>
                        </response>
                    </ashrait>
                </cgGatewayResponseXML>
                <cgGatewayInvoiceResponseXML/>
                <queryErrorCode>00</queryErrorCode>
                <queryErrorText>SUCCESS</queryErrorText>
                <xRem>1eee7e8a-b1f2-4b5c</xRem>
                <personalId/>
                <cardExpiration>0327</cardExpiration>
            </row>
            <totals>
                <pageNumber/>
                <pagesAmount/>
                <queryResultId/>
                <total/>
                <totalMatch/>
            </totals>
        </inquireTransactions>
    </response>
</ashrait>
```

</details>

In the success response, the `row` element inside `inquireTransactions` contains values you can compare with those from the [payment completion redirect](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#handle-payment-completion-redirect). The table below shows how the redirect parameters map to response elements:

| Payment completion redirect | Response         |
| --------------------------- | ---------------- |
| `uniqueID`                  | `uniqueid`       |
| `cardExp`                   | `cardExpiration` |
| `cardToken`                 | `cardId`         |
| `cardMask`                  | `cardMask`       |
| `authNumber`                | `authNumber`     |
| `cgUid`                     | `cgUid`          |

If all the values match, the transaction is valid.

If the API call does not find a transaction with the given `mpiTransactionId`, the transaction is invalid and the response looks like this:

<details>

<summary>Show response</summary>

```xml
<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireTransactions</command>
        <dateTime>2025-08-18 15:09</dateTime>
        <requestId/>
        <tranId>119533238</tranId>
        <result>689</result>
        <message>MPI Transaction not found (used for reports)</message>
        <userMessage>MPI Transaction not found (used for reports)</userMessage>
        <additionalInfo>MPI Transaction not found (used for reports)</additionalInfo>
        <version>2000</version>
        <language>Eng</language>
        <inquireTransactions/>
    </response>
</ashrait>
```

</details>

Note that, like other transaction inquiries, this API call is not intended for every transaction. Use it only when you need to verify specific transactions and retrieve extended details about them. If you need to validate all transactions, use the MAC validation method instead.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.hyp.co.il/enterprise/advanced-security-guidelines/transaction-validation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
