# Transaction Validation

Once you've received a response that signifies a completed transaction, such as a [payment completion redirect](/creditguard/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 provides in the [payment completion redirect](/creditguard/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 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, convert it to Base64, 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](/creditguard/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](/creditguard/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 API request](/creditguard/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](/creditguard/introduction/prerequisites-and-requirements.md).
* `mid`: merchant ID assigned to you as a merchant during [registration](/creditguard/introduction/prerequisites-and-requirements.md).
* `mpiTransactionId`: the transaction ID that is returned as the `txId` parameter in the [payment completion redirect](/creditguard/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](/creditguard/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: 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/advanced-security-guidelines/transaction-validation.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.