API Request & Response General Structure

This page describes the structure that all Hyp API requests should follow, as well as the structure of the responses you receive from Hyp. This is a general overview that applies to all commands and requests, regardless of the specific command you are using.

Request

Every Hyp API call involves sending a POST request to the Hyp CreditGuard API endpoint https://your-hyp-environment-url/xpo/Relay, where your-hyp-environment-url should be replaced with the test or production base URL provided to you during registration.

Every API call includes three parameters in the body that represent your API credentials (the user and password parameters) and transaction details (the int_in parameter):

curl -X POST --location "https://your-hyp-environment-url/xpo/Relay" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d 'user=your-api-username&password=your-api-password&int_in=xml-payload'

In the int_in parameter, include transaction details in the form of a URL-encoded XML payload. The basic structure of the XML payload is always as follows:

<ashrait>
  <request>
    <version>2000</version>
    <language>{language}</language>
    <command>{commandName}</command>
    <{commandName}>
        ...
    </{commandName}>
  </request>
</ashrait>

Every request must include the ashrait root element, which contains a request element.

The request element contains several child elements that provide information about the request:

• version defines the version of the API being used. Current implementations should use 2000.

• language defines the language of text values in the response. If a request is for a payment page, it also defines the UI language in the payment page. Use HEB for Hebrew or ENG for English. Other language codes are not supported and will fall back to English.

• command is the name of the command you want to perform. The value of command must match the commandName element name.

• commandName: this is a command-specific element that contains the parameters for the specific command you are invoking. The name of this element must match the value of the command element. For the list of available commands, see the Commands section below.

Other elements that may be included as direct children of the request element in certain circumstances are:

• mayBeDuplicate: indicates that the current request could be a duplicate of a previous request, which can be useful following a server timeout after sending the previous request. If set to 1, Hyp checks whether the transaction has already been made and if all the details of the current request are identical to the previous request. If the two requests are identical, Hyp checks the completion status of the previous request. If it is complete, Hyp simply re-sends the response. If the previous request is incomplete, Hyp completes the transaction and returns the response. Using mayBeDuplicate requires the merchant to generate and include a unique requestId with every transaction (see below). This element requires explicit terminal configuration. If not used, this element can be omitted, left empty, or set to 0.

• requestId: request ID if generated by the merchant. This is optional in most cases but becomes required if the mayBeDuplicate element is used. In this case, the requestId value should be a string up to 20 characters that is explicitly included in every request.

This is an example of an XML payload that includes the doDeal command to request a payment page:

<ashrait>
      <request>
          <version>2000</version>
          <language>ENG</language>
          <command>doDeal</command>
          <doDeal>
              <terminalNumber>{terminalNumber}</terminalNumber>
              <cardNo>CGMPI</cardNo>
              <total>{totalAmount}</total>
              <transactionType>Debit</transactionType>
              <creditType>RegularCredit</creditType>
              <currency>ILS</currency>
              <transactionCode>Internet</transactionCode>
              <validation>TxnSetup</validation>
              <mid>{mid}</mid>
              <uniqueid>{uniqueId}</uniqueid>
              <mpiValidation>AutoComm</mpiValidation>
              <successUrl>{successUrl}</successUrl>
              <errorUrl>{errorUrl}</errorUrl>
          </doDeal>
      </request>
  </ashrait>

For more details on requesting a payment page, see Integrating Hyp's Payment Page and Accepting Payment.

Response

The response is returned in XML format. It's structured similarly to the XML payload in the request:

<ashrait>
    <response>
        <command>{commandName}</command>
        <dateTime/>
        <requestId/>
        <tranId/>
        <result/>
        <message/>
        <userMessage/>
        <additionalInfo/>
        <version/>
        <language/>
        <{commandName}>
        ...
        </{commandName}>
    </response>
</ashrait>

In the response:

• command, requestId, version, and language elements are exactly the same as in the request.

• dateTime contains a timestamp of the response in the format YYYY-MM-DD hh:mm.

• tranId is the transaction ID assigned by Hyp to the handled request. This ID is unique for each transaction request and can be used to track it.

• result contains the 3-digit result code of the command execution. Successful commands return 000, while errors return a specific code.

• message contains a technical description of the result, which can be used for debugging or logging purposes. In responses with result code 000, this element reads "Permitted transaction".

• userMessage contains a user-friendly message that can be displayed to the end user. In responses with result code 000, this element reads "Permitted transaction".

• additionalInfo may contain additional details about the command execution.

• {commandName} contains a mix of parameters you specified for the command in the request and the result of its execution.

Here's an example of a response for an inquireTransactions command. This is a successful response, as evidenced by the 000 value of the result element:

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>inquireTransactions</command>
        <dateTime>2025-07-28 12:49</dateTime>
        <requestId/>
        <tranId>119101579</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="51">RegularCredit</transactionType>
                    <creditType code="1">RegularCredit</creditType>
                    <currency code="1">ILS</currency>
                    <baseCurrency/>
                    <baseAmount/>
                    <transactionCode code="52">Internet</transactionCode>
                    <total>11400</total>
                    <firstPayment/>
                    <periodicalPayment/>
                    <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>118664947</cgUid>
                    <cardHash/>
                    <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>f6c9683f-9faf-4e5d-bf48-7a193bd88b0c</mpiTransactionId>
                    <financialStatus>Other</financialStatus>
                    <tranId>118664947</tranId>
                    <shovar/>
                    <transactionDate>2025-07-10 13:08:05</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>0228</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="53">AuthCredit</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>4397830</authNumber>
                    <fileNumber>70</fileNumber>
                    <slaveTerminalNumber>085</slaveTerminalNumber>
                    <slaveTerminalSequence>013</slaveTerminalSequence>
                    <eci>7</eci>
                    <clientIp/>
                    <email/>
                    <cavv code=""/>
                    <user/>
                    <addonData/>
                    <supplierNumber>300012</supplierNumber>
                    <id/>
                    <shiftId1/>
                    <shiftId2/>
                    <shiftId3/>
                    <shiftTxnDate/>
                    <cgUid>118664947</cgUid>
                    <cardHash/>
                    <acquirerData>
                        <acquirerResponseId>770774801258</acquirerResponseId>
                        <walletSupplierId/>
                        <mcc>4121</mcc>
                    </acquirerData>
                    <ashraitEmvData>
                        <uid>25071013082408828199589</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>f6c9683f-9faf-4e5d-bf48-7a193bd88b0c</mpiTransactionId>
                    <financialStatus>Transmitted</financialStatus>
                    <tranId>118664958</tranId>
                    <shovar>085013</shovar>
                    <transactionDate>2025-07-10 13:08:24</transactionDate>
                    <transmitDateTime>2025-07-10 23:06:03</transmitDateTime>
                    <shvaReferanceNo>04139459</shvaReferanceNo>
                    <transmitId>1575324</transmitId>
                </transaction>
                <transaction>
                    <status>310</status>
                    <statusText>There is no debit deal that matches the credit deal</statusText>
                    <extendedStatus/>
                    <extendedStatusText/>
                    <extendedUserMessage/>
                    <terminalNumber>0882819014</terminalNumber>
                    <cardBin/>
                    <cardMask/>
                    <cardLength>0</cardLength>
                    <cardNo/>
                    <cardName/>
                    <cardExpiration/>
                    <cardType code=""/>
                    <extendedCardType code="">Credit</extendedCardType>
                    <creditCompany code=""/>
                    <cardBrand code=""/>
                    <cardAcquirer code=""/>
                    <serviceCode/>
                    <transactionType code="00">Blocked</transactionType>
                    <creditType code=""/>
                    <currency code=""/>
                    <baseCurrency/>
                    <baseAmount/>
                    <transactionCode code=""/>
                    <total/>
                    <firstPayment/>
                    <periodicalPayment/>
                    <numberOfPayments/>
                    <clubId/>
                    <validation code=""/>
                    <idStatus code=""/>
                    <cvvStatus code=""/>
                    <authSource code=""/>
                    <authNumber/>
                    <fileNumber/>
                    <slaveTerminalNumber/>
                    <slaveTerminalSequence/>
                    <eci/>
                    <clientIp/>
                    <email/>
                    <cavv code=""/>
                    <user/>
                    <addonData/>
                    <supplierNumber/>
                    <id/>
                    <shiftId1/>
                    <shiftId2/>
                    <shiftId3/>
                    <shiftTxnDate/>
                    <cgUid>118664947</cgUid>
                    <cardHash/>
                    <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>There is no debit deal that matches the credit deal</message>
                    <userMessage>Please contact System Administration</userMessage>
                    <financialStatus>Rejected</financialStatus>
                    <tranId>118683662</tranId>
                    <shovar/>
                    <transactionDate>2025-07-11 16:47:37</transactionDate>
                </transaction>
            </transactions>
            <totals>
                <pageNumber/>
                <pagesAmount/>
                <queryResultId/>
                <total>3</total>
                <totalMatch>3</totalMatch>
            </totals>
        </inquireTransactions>
    </response>
</ashrait>

In case of an error response, the error code is provided in the result element, the message element contains a technical description of the error, userMessage contains a user-friendly message that can be displayed to the end user, and the command-specific element is not returned.

Here's an example of an error response for a refundDeal command:

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>refundDeal</command>
        <dateTime>2025-07-28 12:54</dateTime>
        <requestId/>
        <tranId>119101676</tranId>
        <result>310</result>
        <message>There is no debit deal that matches the credit deal</message>
        <userMessage>Please contact System Administration</userMessage>
        <additionalInfo>No matching transactions found.</additionalInfo>
        <version>2000</version>
        <language>Eng</language>
        <refundDeal>
            <status>310</status>
            <statusText>There is no debit deal that matches the credit deal</statusText>
            <extendedStatus/>
            <extendedStatusText/>
            <extendedUserMessage/>
            <terminalNumber>0882819014</terminalNumber>
            <cardBin/>
            <cardMask/>
            <cardLength>0</cardLength>
            <cardNo/>
            <cardName/>
            <cardExpiration/>
            <cardType code=""/>
            <extendedCardType code=""/>
            <creditCompany code=""/>
            <cardBrand code=""/>
            <cardAcquirer code=""/>
            <serviceCode/>
            <transactionType code=""/>
            <creditType code=""/>
            <currency code=""/>
            <baseCurrency/>
            <baseAmount/>
            <transactionCode code=""/>
            <total/>
            <firstPayment/>
            <periodicalPayment/>
            <numberOfPayments/>
            <clubId/>
            <validation code=""/>
            <idStatus code=""/>
            <cvvStatus code=""/>
            <authSource code=""/>
            <authNumber/>
            <fileNumber/>
            <slaveTerminalNumber/>
            <slaveTerminalSequence/>
            <eci/>
            <clientIp/>
            <email/>
            <cavv code=""/>
            <user/>
            <addonData/>
            <supplierNumber/>
            <id/>
            <shiftId1/>
            <shiftId2/>
            <shiftId3/>
            <shiftTxnDate/>
            <cgUid>118664947</cgUid>
            <cardHash/>
            <ashraitEmvData>
                <mti>100</mti>
            </ashraitEmvData>
            <extendedTranCode/>
            <sendNotification/>
        </refundDeal>
    </response>
</ashrait>

Commands

Below is a list of commands supported by the Hyp API, along with links to their respective API reference pages and general documentation covering their usage.

• addCgInvoice: see Issuing Invoices.

• cancelDeal: see Refunds and Cancellations.

• doDeal: see Integrating Hyp's Payment Page and Accepting Payment, Basic Integration Flow: Hello World With a Full Working Charge, Adding Installments to the Payment Page, Implementing Recurring Payments, Two-Phase Commits, Short-Term CC Data Storage, Payouts.

• getSessionId

• inquireInvoice: see Invoice Inquiries.

• refundCgInvoice: see Invoicing for Refunds.

• refundDeal: see Refunds and Cancellations.

• transmitInquire

• transmitTerminal