# 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](/introduction/basic-integration-flow-hello-world-with-a-full-working-charge.md).

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

{% @mermaid/diagram content="sequenceDiagram
participant C as Customer (in browser)
participant M as Merchant website
participant H as Hyp

```
C->>M: Browses site, adds items to cart
C->>M: Clicks "Checkout"
M->>H: API request: Create payment page
H-->>M: Response: One-time payment page URL (10 min, single-use)

M-->>C: Redirect / iframe to payment page
C->>H: Enters card details or uses a different payment method, clicks Pay
H->>H: Process transaction & determine status

H-->>C: Redirect to merchant’s success / failure / cancel URL
C->>M: Lands on redirect page with URL parameters (transaction IDs, card token/mask, etc.)

opt If success page
    M->>M: Verify transaction validity
end
M-->>M: Save transaction info, update internal DB

M-->>C: Show confirmation / error / cancel message
```

" %}

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](/two-phase-commits/overview.md), 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](#create-a-payment-page-request)
2. [Extract and handle the payment page URL from the response](#extract-and-handle-the-payment-page-url-from-the-response)
3. [Handle payment completion redirect](#handle-payment-completion-redirect)
4. (Optional) [Validate the transaction](#validate-the-transaction-optional)

### Create a payment page request

A payment page request is a [standard POST request to the Hyp API](/introduction/request-and-response-general-structure.md). Inside the `int_in` parameter, the request contains an XML payload with the `doDeal` command. Here's an example:

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

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](/introduction/prerequisites-and-requirements.md).
* `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](/payment-page-integration/installments.md), the value of this element will be different.
* `currency`: the currency code according to [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217). For example, *ILS* for Israeli new shekels, *USD* for US dollars, 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](/introduction/prerequisites-and-requirements.md).
* `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](/changing-the-default-payment-page-appearance/overview.md) or [enable installments](/payment-page-integration/installments.md).

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](/payment-page-integration/full-page-redirect-vs-iframe-based-integration.md).

For all supported parameters of the `doDeal` command and their possible values, refer to the [API reference](/api-reference/index.md).

### Extract and handle the payment page URL from the response

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

<details>

<summary>Show response</summary>

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

</details>

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](/changing-the-default-payment-page-appearance/configuring-the-transition-page.md).

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](#validate-the-transaction-optional), or [inquire](/inquiring-transactions/overview.md) 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](/advanced-security-guidelines/transaction-validation.md).

For a walkthrough on validating a transaction using the `responseMac` parameter, see [Basic Integration Flow: Hello World With a Full Working Charge](/introduction/basic-integration-flow-hello-world-with-a-full-working-charge.md#step-4-validate-the-transaction).

## Interactive playground

You can use the [Hyp playground](https://hyp-playground.netlify.app/) 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.


---

# 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/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.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.