# 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](/enterprise/introduction/prerequisites-and-requirements.md).

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

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

```xml
<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](/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#create-a-payment-page-request).

## Response

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

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

<details>

<summary>Show response</summary>

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

</details>

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:

<details>

<summary>Show response</summary>

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

</details>

## 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`](/enterprise/api-reference/addcginvoice.md): see [Issuing Invoices](/enterprise/documents-and-invoicing/issuing-invoices.md).
* [`cancelDeal`](/enterprise/api-reference/canceldeal.md): see [Refunds and Cancellations](/enterprise/additional-payment-scenarios/refunds-and-cancellations.md).
* [`doDeal`](/enterprise/api-reference/dodeal.md): see [Integrating Hyp's Payment Page and Accepting Payment](/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md), [Basic Integration Flow: Hello World With a Full Working Charge](/enterprise/introduction/basic-integration-flow-hello-world-with-a-full-working-charge.md), [Adding Installments to the Payment Page](/enterprise/payment-page-integration/installments.md), [Implementing Recurring Payments](/enterprise/recurring-payments-and-subscriptions/implementing-recurring-payments.md), [Two-Phase Commits](/enterprise/two-phase-commits/overview.md), [Short-Term CC Data Storage](/enterprise/additional-payment-scenarios/short-term-cc-data-storage.md), [Payouts](/enterprise/additional-payment-scenarios/payouts.md).
* [`getSessionId`](/enterprise/api-reference/getsessionid.md)
* [`inquireInvoice`](/enterprise/api-reference/inquireinvoice.md): see [Invoice Inquiries](/enterprise/documents-and-invoicing/invoice-inquiries.md).
* [`refundCgInvoice`](/enterprise/api-reference/refundcginvoice.md): see [Invoicing for Refunds](/enterprise/documents-and-invoicing/refund-invoices.md).
* [`refundDeal`](/enterprise/api-reference/refunddeal.md): see [Refunds and Cancellations](/enterprise/additional-payment-scenarios/refunds-and-cancellations.md).
* [`transmitInquire`](/enterprise/api-reference/transmitinquire.md)
* [`transmitTerminal`](/enterprise/api-reference/transmitterminal.md)


---

# 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/enterprise/introduction/request-and-response-general-structure.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.