> For the complete documentation index, see [llms.txt](https://developers.hyp.co.il/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.hyp.co.il/enterprise/available-payment-options/payment-request.md).

# Payment Request

Payment request is an advanced version of [Pay By Link](https://developers.hyp.co.il/enterprise/available-payment-options/pay-by-link.md) that allows you to generate secure, authenticated payment links via API. Unlike Pay By Link, which is manually triggered from the payment page, payment requests are generated with a server-to-server API call. This is perfect for use cases like **remote service billing** and **debt collection**.

Payment requests require customers to verify their identity using a **one-time password (OTP)** sent to their mobile phone before they can access the payment page.

You have a choice between two ways of distributing payment requests:

1. Use Hyp's infrastructure to send payment requests via SMS.
2. Distribute payment requests through your own channels (email, customer portal, etc.).

## Comparison with Pay By Link

While both methods allow you to send payment links to customers, they differ in their security requirements and how they are initiated:

* **Interaction**: [Pay By Link](https://developers.hyp.co.il/enterprise/available-payment-options/pay-by-link.md) involves two people interacting with a payment page: first, the requester generates the link, then the recipient uses it to pay. Payment requests are generated via a server-side API call, and interaction with a payment page only occurs on the recipient's end.
* **Verification**: Payment links generated with Pay By Link are ready to use immediately without additional verification. In contrast, payment requests require the recipient to verify their identity with a one-time password (OTP).

## Prerequisites

Before you can start generating payment requests, you need to:

1. **Contact Hyp support**: Have the payment request service enabled and configured on your terminal. This includes setting the merchant name and branding that will appear in SMS messages.
2. **Set up a webhook endpoint**: Hyp sends transaction status updates to your server via [webhooks](https://developers.hyp.co.il/enterprise/payment-page-integration/webhooks.md).

## Payment experience

First, the customer receives an **SMS notification** containing a secure payment link and a short description of the charge. (Alternatively, if you have chosen to use your own channels for distributing the link, you can send the link to the customer directly.)

![SMS](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-814bd13835094cdd1b3963615df7b03c3075472e%2Fsms.jpg?alt=media)

When the customer clicks the link, they see the message sent by the merchant in the payment request and are prompted to **request a verification code**. When they do, Hyp sends a 6-digit OTP to the customer's mobile number.

![OTP request page](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-d8698b4c2798a51fc61bd676576230baa687d9e5%2Fotp.png?alt=media)

After entering the correct OTP, the customer is granted access to the **payment page**, where they can complete the transaction using any supported payment method:

![Payment Page](https://3255314327-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQDmIAW4sQ20lCItJGzcS%2Fuploads%2Fgit-blob-af2cc836a3c5afab4adbc61347b231d70b65011f%2Fpayment-page.png?alt=media)

When the payment is successful, the customer is redirected to a success page, and your system is notified via a webhook.

## Integration

To create a payment request, send a `doDeal` request with the `validation` parameter set to `apiPaymentLinkSetup`.

The following are the mandatory parameters that you should include in the request:

* `cardHolderPhoneNo`: the customer's mobile number for SMS delivery and OTP authentication.
* `linkExpiration` (inside `apiLinkData`): sets the generated payment link to expire anywhere from 1 to 240 hours (10 days). After this period, the customer will no longer be able to access the OTP or payment page.
* `sendLinkByHyp` (inside `apiLinkData`): `1` delegates delivery of the payment link via SMS to Hyp. If set to `0`, you, as the merchant, are responsible for delivering the payment link through your own channels (e.g., via WhatsApp or your own email system).
* `linkMerchantText` (inside `apiLinkData`): the text explaining the reason for the payment request that the customer sees during the OTP verification step.

The `mpiValidation` parameter in a payment request can only be set to `Verify`, `AutoComm`, or `AutoCommHold`.

For a full list of available parameters and their formats, see the [doDeal API reference](https://developers.hyp.co.il/enterprise/api-reference/dodeal.md#payment-request-parameters).

### Example request

Here's a sample API request to create a payment request:

<details>

<summary>View sample request</summary>

```xml
<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>doDeal</command>
        <doDeal>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <total>{totalAmount}</total>
            <cardHolderPhoneNo>0521234567</cardHolderPhoneNo>
            <email>jennyp@example.co.il</email>
            <transactionType>Debit</transactionType>
            <creditType>RegularCredit</creditType>
            <currency>ILS</currency>
            <transactionCode>Internet</transactionCode>
            <validation>apiPaymentLinkSetup</validation>
            <mid>{mid}</mid>
            <uniqueid>{uniqueId}</uniqueid>
            <mpiValidation>AutoComm</mpiValidation>
            <apiLinkData>
                <linkExpiration>48</linkExpiration>
                <sendLinkByHyp>1</sendLinkByHyp>
                <linkMerchantText>Payment for Invoice 1002</linkMerchantText>
            </apiLinkData>
        </doDeal>
    </request>
</ashrait>
```

</details>

### Example response

If the request is successful, Hyp returns a response with status `000` that contains an `apiLinkData` section wrapping payment link information, including:

* `linkUrl`: The payment link that the customer will use. This link is sent to the customer if you've chosen SMS delivery. Otherwise, you're responsible for distributing it through your own channels.
* `linkId`: An alphanumeric identifier that you should store for reconciliation and cross-referencing with webhook responses.
* `linkStatus`: Set to `Created`; during the lifecycle of a payment request, the status may change to either `Success` or `Rejected`.

<details>

<summary>View sample response</summary>

```xml
<ashrait>
    <response>
        <command>doDeal</command>
        <dateTime>2026-06-28 16:45</dateTime>
        <requestId/>
        <tranId>127861125</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>0882818012</terminalNumber>
            <cardBin/>
            <cardMask/>
            <cardLength>0</cardLength>
            <cardNo/>
            <cardHolderPhoneNo>0521234567</cardHolderPhoneNo>
            <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>9000</total>
            <firstPayment/>
            <periodicalPayment/>
            <numberOfPayments/>
            <paymentsInterest/>
            <mid>14769</mid>
            <uniqueid>5c23852c-d805-4e94-af60-01370fd10934</uniqueid>
            <mpiValidation>AutoComm</mpiValidation>
            <token/>
            <mpiHostedPageUrl/>
            <returnUrl/>
            <successUrl/>
            <errorUrl/>
            <cancelUrl/>
            <clubId/>
            <validation code="306"/>
            <idStatus code=""/>
            <cvvStatus code=""/>
            <authSource code="6">MPIServer</authSource>
            <authNumber/>
            <fileNumber/>
            <slaveTerminalNumber/>
            <slaveTerminalSequence/>
            <eci/>
            <clientIp/>
            <email>jennyp@example.co.il</email>
            <cavv code=""/>
            <user/>
            <addonData/>
            <supplierNumber/>
            <id/>
            <shiftId1/>
            <shiftId2/>
            <shiftId3/>
            <shiftTxnDate/>
            <cgUid>127861125</cgUid>
            <cardHash/>
            <ashraitEmvData>
                <mti>100</mti>
            </ashraitEmvData>
            <apiLinkData>
                <linkExpiration>48</linkExpiration>
                <linkMerchantText>Payment for Invoice 1002</linkMerchantText>
                <sendLinkByHyp>1</sendLinkByHyp>
                <linkId>fpAmhk1yaf</linkId>
                <linkUrl>https://link-uat.hyp.co.il/fpAmhk1yaf</linkUrl>
                <linkStatus>Created</linkStatus>
                <linkExpirationDate>2026-06-30 16:45</linkExpirationDate>
            </apiLinkData>
            <extendedTranCode>apiLink</extendedTranCode>
            <sendNotification/>
        </doDeal>
    </response>
</ashrait>
```

</details>

Make sure to save the `tranId` supplied in the response in case you want to cancel the payment request later.

## Handling results and reconciliation

Once the customer completes a payment, you can handle the [payment completion redirect](https://developers.hyp.co.il/enterprise/payment-page-integration/integrating-hyps-payment-page-and-accepting-payment.md#handle-payment-completion-redirect) as usual, including saving `cgUid` for future reference and reconciliation.

In addition, Hyp sends two types of notifications to your webhook endpoint:

1. **Link status notification (J112)**: This notification (transaction type `TxnNotification`) tells you that the link status has changed (e.g., from `Created` to `Success`). Inside the notification, look for the `apiLinkData` section that conveys the new status of the payment request.
2. **Transaction notification (J4)**: This is the standard transaction completion notification containing the payment processing outcome, payment details, authorization codes, and card information.

<details>

<summary>View sample J112 notification</summary>

```xml
<transaction>
    <status>000</status>
    <statusText>Permitted transaction</statusText>
    <extendedStatus/>
    <extendedStatusText/>
    <extendedUserMessage/>
    <terminalNumber>0883673015</terminalNumber>
    <cardBin>CG</cardBin>
    <cardMask>CG***LINK</cardMask>
    <cardLength>9</cardLength>
    <cardNo>xxxxxLINK</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="50">Phone</transactionCode>
    <total>10000</total>
    <firstPayment/>
    <periodicalPayment/>
    <numberOfPayments/>
    <clubId/>
    <validation code="112">TxnNotification</validation>
    <idStatus code=""/>
    <cvvStatus code=""/>
    <authSource code=""/>
    <authNumber/>
    <fileNumber/>
    <slaveTerminalNumber/>
    <slaveTerminalSequence/>
    <eci/>
    <clientIp/>
    <email/>
    <cavv code=""/>
    <user>5555 Test123456789</user>
    <addonData/>
    <supplierNumber/>
    <id/>
    <shiftId1/>
    <shiftId2/>
    <shiftId3/>
    <shiftTxnDate/>
    <cgUid>121984305</cgUid>
    <cardHash/>
    <acquirerData>
        <acquirerResponseId/>
        <walletSupplierId/>
        <mcc/>
    </acquirerData>
    <ashraitEmvData>
        <mti>100</mti>
    </ashraitEmvData>
    <apiLinkData>
        <linkId>rjztB1P8bA</linkId>
        <linkStatus>Success</linkStatus>
        <linkErrorCode>000</linkErrorCode>
    </apiLinkData>
    <extendedTranCode>apiLInk</extendedTranCode>
    <sendNotification/>
    <message>Permitted transaction</message>
    <userMessage>Permitted transaction</userMessage>
    <financialStatus>Other</financialStatus>
    <tranId>121984658</tranId>
    <shovar/>
    <transactionDate>2025-12-09 15:12:25</transactionDate>
</transaction>
```

</details>

## Cancelling an unpaid payment request

Since you can't change the parameters of an existing request, you need to create a new one if you want to update the total due, phone number, or the text accompanying the payment link. When you create a new corrected request, you should cancel the previous one.

If a payment link hasn't been used yet, you can cancel it using the `cancelPaymentLink` command and the `tranId` returned when you created the link:

```xml
<ashrait>
    <request>
        <command>cancelPaymentLink</command>
        <language>ENG</language>
        <version>2000</version>
        <cancelPaymentLink>
            <terminalNumber>0883673015</terminalNumber>
            <mid>14776</mid>
            <tranId>48217926</tranId>
        </cancelPaymentLink>
    </request>
</ashrait>
```

## Error handling

If there's an issue with generating a payment request, Hyp will return an error code. Here are the most common validation errors:

| Error text                             | Status code | Description                                                                                                                                  |
| -------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing mandatory field in XML         | 322         | One or more of the following mandatory parameters are not set: `cardHolderPhoneNo`, `linkMerchantText`, `linkExpiration`, or `sendLinkByHyp` |
| MPI Invalid request or post parameters | 683         | The `mpiValidation` parameter is set to an unsupported value. Supported values are `Verify`, `AutoComm`, and `AutoCommHold`                  |

A payment request can be successfully created but still end up unpaid for several reasons, as detailed in the following table. The status code will be returned in the link status notification (`TxnNotification`, J112) with the `linkStatus` property set to `Rejected`.

| Error text                   | Status code                        | Description                                                                   |
| ---------------------------- | ---------------------------------- | ----------------------------------------------------------------------------- |
| OTP check failed             | 382                                | The customer exhausted the number of attempts to enter a valid OTP code       |
| Maximum OTP request exceeded | 384                                | The customer exhausted the allowed number of OTP SMS resend attempts          |
| Payment request has expired  | 487                                | The customer did not open the payment request or did not complete the payment |
|                              | Error code from last debit attempt | The customer exhausted the number of payment attempts with a credit card      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.hyp.co.il/enterprise/available-payment-options/payment-request.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
