Integrating Hyp’s Payment Page and Accepting Payment

This page is a detailed explanation of the Hyp payment page lifecycle, as well as the steps you, as a developer, need to take to request a payment page and handle the outcome of the resulting transaction.

If you prefer a more compact and hands-on format, see Basic Integration Flow: Hello World With a Full Working Charge.

Payment flow overview

The following is a high-level overview of the payment flow when using Hyp's payment page. It includes both the customer's actions on the merchant website and the API requests and responses between the merchant website and Hyp.

1. The customer browses the merchant website, adding items to the shopping cart.

2. When the customer clicks a checkout link, the merchant website sends an API request to Hyp requesting a payment page to be generated. The API request specifies the total amount to be charged, currency, the language of the payment page UI, URLs for success, failure, and cancel redirects, and additional parameters as necessary.

3. Hyp validates the request and returns a unique one-time payment page URL to the merchant website. The payment page URL is valid for 10 minutes and can only be used to perform a single payment.

4. Once it receives a payment page URL, the merchant website redirects the user to the payment page or opens it in an iframe.

5. The payment page always supports paying with a credit card. Depending on the merchant's terminal settings, the payment page may support additional payment methods: Apple Pay, Google Pay, bit, etc. In such cases, the payment page displays buttons for each available payment method. Clicking one of these buttons displays a payment UI specific to the selected method.

6. If the customer chooses to pay with a credit card, they enter their card number, expiration date, and CVC. Depending on terminal settings and the payment page API request details, the customer may also need to enter other information, such as an Israeli ID number, or may want to split the payment into installments.

7. After entering payment details, the customer clicks the Pay button.

8. Hyp performs the transaction, determines its status, and redirects the user to one of the URLs provided by the merchant website, depending on the status of the transaction.

9. The redirect page (success, failure, or cancel) that the customer lands on contains URL parameters that include several transaction IDs, the card token and mask, and other details about the transaction.

10. Optionally, the merchant website verifies the validity of the transaction. It can also use various URL parameters from the redirect page to save transaction information to an internal customer database and display contextual messages to the customer.

The above describes a "one-phase commit": the most common transaction flow for accepting payments on a merchant website.

As a merchant, you can also choose to perform a two-phase commit, where the first phase is authorization only and the second phase is capture.

Payment page integration overview

Based on the above payment flow overview, your payment page integration efforts will consist of the following steps:

1. Create a payment page request

2. Extract and handle the payment page URL from the response

3. Handle payment completion redirect

4. (Optional) Validate the transaction

Create a payment page request

A payment page request is a standard POST request to the Hyp API. Inside the int_in parameter, the request contains an XML payload with the doDeal command. Here's an example:

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

The child elements inside the doDeal element represent various parameters of the doDeal command. Here's a breakdown of these elements:

• terminalNumber: a unique number assigned to you as a merchant during registration.

• cardNo: this element normally indicates the card number, but when making a payment page request, it should be set to CGMPI since the card number is not known yet.

• total: the total payment due in currency subunits, such as cents or agorot. For example, if the total in the user's payment cart is $47.30, the number that you pass in the total element should be 4730.

• transactionType: set to Debit since the payment page will be used to remove funds from the customer's account.

• creditType: set to RegularCredit to allow only a one-time payment. If you decide to allow installments, the value of this element will be different.

• currency: the currency code according to ISO-4217. For example, ILS for Israeli new shekels, USD for US dollar, etc.

• transactionCode: this element describes the card entry mode. Since this is an e-commerce transaction, it should be set to Internet.

• validation: should be set to TxnSetup to indicate that this is a payment page request.

• mid: merchant ID assigned to you as a merchant during registration.

• uniqueid: a string ID of up to 64 characters that you generate for each transaction and that should be unique for at least the last 24 hours.

• mpiValidation: set to AutoComm to indicate the payment page will be used for a one-phase sale.

• successUrl: the URL on the merchant website that Hyp CreditGuard should redirect to upon successful payment.

• errorUrl: the URL on the merchant website that Hyp CreditGuard should redirect to in case of a payment error.

• cancelUrl: the URL on the merchant website that Hyp CreditGuard should redirect to when the customer clicks Cancel on the payment page. The cancel button may or may not be available on the payment page depending on terminal settings.

These are the basic parameters required to create a payment page request. You may also want to include additional parameters to customize the payment page or enable installments.

If you intend to display the resulting payment page in an iframe, you need to perform several additional steps, including setting a content security policy (CSP) and defining your merchant website as the only eligible ancestor for the iframe. For more details, see Full-Page Redirect vs Iframe-Based Integration.

For all supported parameters of the doDeal command and their possible values, refer to the API reference.

Extract and handle the payment page URL from the response

The response to the payment page request will look like this:

Show response

<?xml version='1.0'?>
<ashrait>
    <response>
        <command>doDeal</command>
        <dateTime>2025-07-25 15:17</dateTime>
        <requestId/>
        <tranId>119037543</tranId>
        <result>000</result>
        <message>Permitted transaction</message>
        <userMessage>Permitted transaction</userMessage>
        <additionalInfo/>
        <version>2000</version>
        <language>Eng</language>
        <doDeal>
            <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>
            <blockedCard/>
            <lifeStyle/>
            <customCardType/>
            <creditCompany code=""/>
            <cardBrand code=""/>
            <cardAcquirer code=""/>
            <serviceCode/>
            <transactionType code="01">RegularDebit</transactionType>
            <creditType code="1">RegularCredit</creditType>
            <currency code="1">ILS</currency>
            <baseCurrency/>
            <baseAmount/>
            <transactionCode code="52">Internet</transactionCode>
            <total>10000</total>
            <firstPayment/>
            <periodicalPayment/>
            <numberOfPayments/>
            <paymentsInterest/>
            <mid>13092</mid>
            <uniqueid>5a81506e-8807-43d4-93a5-d128ff6cef0d</uniqueid>
            <mpiValidation>AutoComm</mpiValidation>
            <token>67777f64-a940-488a-9fb6-65f343abce7e</token>
            <mpiHostedPageUrl>https://ppsuat.creditguard.co.il?txId=67777f64-a940-488a-9fb6-65f343abce7e
            </mpiHostedPageUrl>
            <returnUrl/>
            <successUrl>https://mymerchantwebsite.com/success/</successUrl>
            <errorUrl>https://mymerchantwebsite.com/error/</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>119037543</cgUid>
            <cardHash/>
            <ashraitEmvData>
                <mti>100</mti>
            </ashraitEmvData>
            <extendedTranCode/>
            <sendNotification/>
        </doDeal>
    </response>
</ashrait>

The result element indicates the status code of the request. A value of 000 means the request was successful and Hyp has generated a payment page for you to redirect the customer to.

If the request was successful, you now need to extract the payment page URL that Hyp has generated for you from the mpiHostedPageUrl element in the response.

Once you have extracted the payment page URL, you can either redirect the customer to it or, if you have performed the iframe setup, display it in an iframe on your merchant website.

Handle payment completion redirect

If the customer clicks Cancel while interacting with the payment page, they will be redirected to the URL specified in the cancelUrl element of your payment page request.

Otherwise, if the customer enters payment details and clicks Pay, they will be redirected to either the successUrl or errorUrl, depending on whether the transaction was successful. For various options for handling redirects, see Configuring the Transition Page.

When redirecting to your success or error page, Hyp passes a query string with several parameters. Here's an example of a success page URL with parameters:

https://your-merchant-website/success.html?uniqueID=5c8cf9b0-1be1-4cdc-857e-3b3b102b19aa
&lang=EN
&authNumber=
&cgUid=115607512
&responseMac=6741715227eb0f60e14c6da7e26d1edbd0139784b8be94b664b6aba7b5f99380
&cardToken=1092880571131111
&cardExp=0731
&personalId=
&cardMask=411111******1111
&txId=d08ba620-df0d-4b3b-8be0-c0e3e6f603f2
&numberOfPayments=0
&firstPayment=
&periodicalPayment=

You can use these parameters to save transaction information to your internal customer database, validate the transaction, or inquire about transaction details.

Validate the transaction (optional)

Once the customer has been redirected to the success page, the transaction is technically complete. However, you may want to perform an additional step: validate the transaction.

You can validate a transaction in two ways: either by making a separate API call or by using the responseMac parameter included in the payment completion redirect. For details on both methods, see Transaction Validation.

For a walkthrough on validating a transaction using the responseMac parameter, see Basic Integration Flow: Hello World With a Full Working Charge.

Interactive playground

You can use the Hyp playground to experiment with various payment page settings and quickly see how they affect the page's look and behavior.

The playground allows you to define the payment page configuration with a UI builder, preview the resulting payment page, and use the API request view to copy the specific XML payload that generates the payment page you've constructed.