Overview of Transaction Inquiries

Sometimes, you as a merchant may want to get a fuller picture of a particular transaction or a set of transactions. For example, you may want to:

• Reconcile the transactions registered in your cashier software with those registered by Hyp.

• Understand the state of a transaction in case of a technical error or timeout.

• Clarify the financial status of a transaction: whether it is approved for transmission, transmitted, rejected, etc.

• Obtain a list of transactions included in a daily transmission to Shva, the Israeli payment processor.

• Determine the type of credit card used in the transaction and the credit card provider.

• Know whether the transaction was a digital wallet payment, such as Apple Pay or Google Pay.

For these and similar cases, Hyp provides a transaction inquiry API. This API allows you to query the terminal for specific transactions or sets of transactions and get a detailed response about them.

Transaction inquiries are not meant to be performed on a continuous basis. Use them sparingly — only when there's a good reason to retrieve more information about a specific transaction or set of transactions. For requests that may return large amounts of data, such as date range inquiries, it is recommended to use pagination.

How to perform transaction inquiries?

Transaction inquiries are essentially search queries performed using one of several criteria, such as the transaction's unique identifier (tranId) or the user field.

The API response includes all relevant transactions matched by the search criteria, as well as the number of matching transactions found.

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

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>inquireTransactions</command>
        <inquireTransactions>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <cgUid>{cgUid}</cgUid>
        </inquireTransactions>
    </request>
</ashrait>

The command element should be set to inquireTransactions, and the inquireTransactions 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 act as search criteria. These elements are optional, but at least one must be present in the request. In the example above, cgUid is the lookup element. Below is a list of some of the lookup elements you can use to inquire about transactions:

  • cgUid: the CG identifier assigned to each transaction, which is returned as a parameter in the payment completion redirect. All API requests related to the same "financial transaction", including payment page requests and both steps of the two-phase commit, will share the same cgUid value.

  • 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. tranId is not returned in the payment completion redirect, so if you want to make inquiries using it, you'll need to first inquire with a different lookup element.

  • user: the user element value that you, as a merchant, may pass to Hyp when requesting payment pages. This is typically a unique identifier from your customer database, such as a user ID, order ID, or transaction ID.

  • Date ranges:

    • fromDealDate and toDealDate: search for transactions by the date they were performed by Hyp.

    • fromTransmitDate and toTransmitDate: search for transactions by the date they were transmitted to Shva.

    • fromShiftTxnDate and toShiftTxnDate: search for transactions by the ShiftTxnDate field from the original transaction request.

Here's a sample response for a transaction inquiry request that returns two transactions:

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireTransactions</command>
        <dateTime>2025-07-31 22:25</dateTime>
        <requestId/>
        <tranId>119187116</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo/>
        <version>2000</version>
        <language>Eng</language>
        <inquireTransactions>
            <transactions>
                <transaction>
                    <status>000</status>
                    <statusText>Permitted transaction</statusText>
                    <extendedStatus/>
                    <extendedStatusText/>
                    <extendedUserMessage/>
                    <terminalNumber>0882819014</terminalNumber>
                    <cardBin>CG</cardBin>
                    <cardMask>CGGMPI</cardMask>
                    <cardLength>5</cardLength>
                    <cardNo>xGMPI</cardNo>
                    <cardName/>
                    <cardExpiration/>
                    <cardType code=""/>
                    <extendedCardType code="0">Credit</extendedCardType>
                    <creditCompany code=""/>
                    <cardBrand code=""/>
                    <cardAcquirer code=""/>
                    <serviceCode/>
                    <transactionType code="01">RegularDebit</transactionType>
                    <creditType code="8">Payments</creditType>
                    <currency code="1">ILS</currency>
                    <baseCurrency/>
                    <baseAmount/>
                    <transactionCode code="52">Internet</transactionCode>
                    <total>35000</total>
                    <firstPayment/>
                    <periodicalPayment/>
                    <numberOfPayments>10</numberOfPayments>
                    <paymentsInterest/>
                    <mid/>
                    <uniqueid/>
                    <mpiValidation/>
                    <token/>
                    <mpiHostedPageUrl/>
                    <returnUrl/>
                    <successUrl/>
                    <errorUrl/>
                    <cancelUrl/>
                    <clubId/>
                    <validation code="106">TxnSetup</validation>
                    <idStatus code=""/>
                    <cvvStatus code=""/>
                    <authSource code="6">MPIServer</authSource>
                    <authNumber/>
                    <fileNumber/>
                    <slaveTerminalNumber/>
                    <slaveTerminalSequence/>
                    <eci/>
                    <clientIp/>
                    <email/>
                    <cavv code=""/>
                    <user/>
                    <addonData/>
                    <supplierNumber/>
                    <id/>
                    <shiftId1/>
                    <shiftId2/>
                    <shiftId3/>
                    <shiftTxnDate/>
                    <cgUid>119187087</cgUid>
                    <cardHash/>
                    <customerData>
                        <userData1>Jenny Parkington</userData1>
                    </customerData>
                    <acquirerData>
                        <acquirerResponseId/>
                        <walletSupplierId/>
                        <mcc/>
                    </acquirerData>
                    <ashraitEmvData>
                        <uid/>
                        <cardSeqNumber/>
                        <authCodeAcquirer code=""/>
                        <authNoAcquirer/>
                        <authCodeCreditCompany code=""/>
                        <dspBalance/>
                        <authValidationType code=""/>
                        <specialProjectCode/>
                        <specialProjectInfo1/>
                        <informativeTranCode code=""/>
                        <cashbackAmount/>
                        <tipAmount/>
                        <commisionAmount/>
                        <conversionProvider/>
                        <conversionCurrency/>
                        <conversionAmount/>
                        <conversionRate/>
                        <paymentIndexType/>
                        <recurringNo/>
                        <recurringTotalNo/>
                        <recurringTotalSum/>
                        <recurringUniqueRef/>
                        <recurringFrequency/>
                        <deferMonths/>
                        <ipayAmount/>
                        <ipayNumber/>
                        <ipayOfferCode/>
                        <dueDate/>
                        <ipayCode/>
                        <ipayPrecent/>
                        <ipayProductCode/>
                        <ashReasonCredit/>
                        <isSelfService/>
                        <orgUid/>
                        <orgTranDate/>
                        <orgAmount/>
                        <orgAuthNo/>
                        <orgAuthCodeCreditCompany/>
                        <orgAuthCodeAcquirer/>
                        <orgLinkIncrAuth/>
                        <orgAuthNoAcquirer/>
                        <posJcode/>
                        <pinpadSerialNumber/>
                        <termSerialnumber/>
                        <ashTermType/>
                        <jsonData/>
                        <addendum1/>
                        <addendum2/>
                        <requestMti/>
                        <mti>100</mti>
                        <posDateTime/>
                    </ashraitEmvData>
                    <extendedTranCode/>
                    <sendNotification/>
                    <message>Permitted transaction</message>
                    <userMessage>Permitted transaction</userMessage>
                    <mpiTransactionId>4da3e4c4-c594-4362-baf7-fa2286f8655e</mpiTransactionId>
                    <financialStatus>Other</financialStatus>
                    <tranId>119187087</tranId>
                    <shovar/>
                    <transactionDate>2025-07-31 22:21:18</transactionDate>
                </transaction>
                <transaction>
                    <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>0328</cardExpiration>
                    <cardType code="99">Foreign</cardType>
                    <extendedCardType code="0">Credit</extendedCardType>
                    <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>35000</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>4760370</authNumber>
                    <fileNumber>95</fileNumber>
                    <slaveTerminalNumber>085</slaveTerminalNumber>
                    <slaveTerminalSequence>760</slaveTerminalSequence>
                    <eci>7</eci>
                    <clientIp/>
                    <email/>
                    <cavv code=""/>
                    <user/>
                    <addonData/>
                    <supplierNumber>300012</supplierNumber>
                    <id/>
                    <shiftId1/>
                    <shiftId2/>
                    <shiftId3/>
                    <shiftTxnDate/>
                    <cgUid>119187087</cgUid>
                    <cardHash/>
                    <customerData>
                        <userData1>Jenny Parkington</userData1>
                    </customerData>
                    <acquirerData>
                        <acquirerResponseId>350521607519</acquirerResponseId>
                        <walletSupplierId/>
                        <mcc>4121</mcc>
                    </acquirerData>
                    <ashraitEmvData>
                        <uid>25073122213808828190927</uid>
                        <cardSeqNumber/>
                        <authCodeAcquirer code="0">NoAuthNumber</authCodeAcquirer>
                        <authNoAcquirer/>
                        <authCodeCreditCompany code="1">CreditCompanyAuthorized</authCodeCreditCompany>
                        <dspBalance/>
                        <authValidationType code=""/>
                        <specialProjectCode/>
                        <specialProjectInfo1/>
                        <informativeTranCode code=""/>
                        <cashbackAmount/>
                        <tipAmount/>
                        <commisionAmount/>
                        <conversionProvider/>
                        <conversionCurrency/>
                        <conversionAmount/>
                        <conversionRate/>
                        <paymentIndexType/>
                        <recurringNo/>
                        <recurringTotalNo/>
                        <recurringTotalSum/>
                        <recurringUniqueRef/>
                        <recurringFrequency/>
                        <deferMonths/>
                        <ipayAmount/>
                        <ipayNumber/>
                        <ipayOfferCode/>
                        <dueDate/>
                        <ipayCode/>
                        <ipayPrecent/>
                        <ipayProductCode/>
                        <ashReasonCredit/>
                        <isSelfService/>
                        <orgUid/>
                        <orgTranDate/>
                        <orgAmount/>
                        <orgAuthNo/>
                        <orgAuthCodeCreditCompany/>
                        <orgAuthCodeAcquirer/>
                        <orgLinkIncrAuth/>
                        <orgAuthNoAcquirer/>
                        <posJcode/>
                        <pinpadSerialNumber/>
                        <termSerialnumber/>
                        <ashTermType>0</ashTermType>
                        <jsonData/>
                        <addendum1/>
                        <addendum2/>
                        <requestMti>100</requestMti>
                        <mti>100</mti>
                        <posDateTime/>
                    </ashraitEmvData>
                    <extendedTranCode/>
                    <sendNotification/>
                    <message>Permitted transaction</message>
                    <userMessage>Permitted transaction</userMessage>
                    <mpiTransactionId>4da3e4c4-c594-4362-baf7-fa2286f8655e</mpiTransactionId>
                    <financialStatus>Captured</financialStatus>
                    <tranId>119187092</tranId>
                    <shovar>085760</shovar>
                    <transactionDate>2025-07-31 22:21:38</transactionDate>
                </transaction>
            </transactions>
            <totals>
                <pageNumber/>
                <pagesAmount/>
                <queryResultId/>
                <total>2</total>
                <totalMatch>2</totalMatch>
            </totals>
        </inquireTransactions>
    </response>
</ashrait>

See Examples of Transaction Inquiries for more examples.

Navigating the inquiry response

The response to a transaction inquiry contains several elements, including the transactions element, which holds the details of each transaction that matched the search criteria, and the totals element, which contains metadata about the inquiry results.

The totals element includes the total number of transactions returned in the response, as well as the total number of transactions that matched the search criteria. When using pagination, totals becomes especially useful, as it also includes the current page number and an ID that can be used to retrieve other response pages.

Each transaction element includes detailed information about one of the matched transactions. Notable fields include:

• creditCompany: the credit card company that issued the card. Possible values are: Foreign (code 0), Isracard (1), Visa (2), Diners (3), Amex (4), JCB (5), Alphacard (6), MultiPass (11).

• cardAcquirer: the acquiring company that processed the payment. Possible values are: Isracard (code 1), Visa (2), Alphacard (6), MultiPass (11).

• transactionType: the nature of the financial transaction. Possible values are: Blocked (code 00), RegularDebit (01), ForcedDebit (03), Cashback (06), Cash (07), RecurringDebit (11), BalanceEnquiry (30), Cancel (52), AuthCredit (53), Load (55), Reversal (58), Discharge (82).

• creditType: the type of credit arrangement used for the transaction, as defined by Israeli credit standards. Possible values are: RegularCredit (code 1), IsraCredit (2), AdHock (3), ClubDeal (4), SpecialAlpha (5), SpecialCredit (6), Payments (8), PaymentsClub (9).

• cardType: the category of card used. Possible values are: Local (code 00), Debit (01), Fuel (03), Dualy (04), Rechargeable (06), Dalkan (08), Club (70), FuelClub (73), DualyClub (74), RechargeClub (76), Foreign (99).

• transactionCode: the channel through which the transaction was initiated. Possible values are: Regular (code 00), SelfService (01), FuelSelfService (02), ContactlessMagnetic (04), CellphoneNum (10), EMVContact (40), Phone (50), Signature (51), Internet (52), Fallback (80), ContactlessEmv (85), ContactlessMobile (86), ContactlessMobileEMV (87).

• financialStatus: the current processing status of the transaction in the financial pipeline. Possible values are: Authorized, Rejected, Captured, Transmitted, Pending, Cancelled, Transferred, Error, Other.

• shovar: a transaction identifier from the acquirer's system that combines the slaveTerminalSequence and slaveTerminalNumber element values, which are both also provided in the transaction inquiry response.

• shvaReferanceNo: a reference number assigned by Shva for all transactions in the same transmission.

• status: the Hyp transaction status code. A value of 000 indicates a successful transaction. For other codes, see Response Codes in the doDeal API reference.

• transactionDate: the timestamp when the transaction was performed by Hyp, in the IDT timezone. Format: YYYY-MM-DD hh:mm:ss.