# API Actions

The Hyp Pay API allows you to perform various financial operations through server-to-server requests.

When working with the API, keep the following technical requirements and error handling practices in mind:

* **GET requests**: Every API call on this page is made using a standard HTTP GET request. Most calls can also be performed using equivalent HTTP POST requests.
* **Base URL**: All requests are sent to the base URL `https://pay.hyp.co.il/p/`, followed by specific URL parameters.
* **Backend execution**: For security purposes, you should always make these API calls from your application's backend. Never expose your API credentials by making calls from a browser or mobile app.
* **Error handling**:
  * **HTTP status codes**: Hyp Pay returns a `200 OK` status code for almost all requests, even when an error occurs. You should never rely on HTTP status codes to determine the success of an operation. Instead, always parse the response string for the `CCode` parameter.
  * **Response format**: Before parsing the response for a status code, check the content of the response. If the response contains HTML instead of a URL-encoded string or JSON, it indicates a system error.

This page is organized by the available values of the `action` parameter. If a single `action` value supports multiple scenarios, they are described in separate subsections.

Use the links below to jump to a specific operation:

* **Payment pages and validation** (`action=APISign`):
  * [Create a payment page request](#create-a-payment-page-request)
  * [Validate a transaction](#validate-a-transaction)
  * [Generate a link to an invoice](#generate-a-link-to-an-invoice)
* **Cancel a transaction** ([`action=CancelTrans`](#action-canceltrans))
* **Finalize a postponed transaction** ([`action=commitTrans`](#action-committrans))
* **Request a token** ([`action=getToken`](#action-gettoken))
* **Terminate or resume a recurring payment agreement** ([`action=hkstatus`](#action-hkstatus))
* **Payment links** (`action=payRequest`):
  * [Create and send a payment link](#create-and-send-a-payment-link)
  * [Get a list of payment links](#get-a-list-of-payment-links)
  * [Cancel a payment link](#cancel-a-payment-link)
* **Direct charges and payouts** (`action=soft`):
  * [Charge a saved token](#charge-a-saved-token)
  * [Capture (J4) after J5 authorization](#capture-j4-after-j5-authorization)
  * [Perform a payout](#perform-a-payout)
  * [Create an invoice for an offline transaction](#create-an-invoice-for-an-offline-transaction)
* **Perform a refund** ([`action=zikoyapi`](#action-zikoyapi))

## `action=APISign`

The `APISign` command is used to securely [create a payment page](/pay/getting-started/creating-a-payment-page.md) or [validate a transaction](/pay/security/transaction-validation.md). It uses your API key and password to sign requests or verify responses from the Hyp Pay servers.

### Create a payment page request

This is the first step in [accepting credit cards](/pay/common-use-cases/credit-cards.md). You send the transaction details to Hyp, and we return a signed response that you use to redirect the customer to our secure payment page.

#### Prerequisites

Before making this call, you need:

* Your terminal number (`Masof`), API key (`KEY`), and API password (`PassP`).
* To decide on the transaction amount and currency.

#### Parameters

The parameters for creating a payment page are grouped into several tables below based on their purpose. This makes it easier to find the specific options you need for different payment scenarios, such as [invoicing](/pay/invoicing/basic-invoicing.md), [installments](/pay/common-use-cases/installments.md), or [recurring payments](/pay/advanced-features/recurring-payments.md).

**Basic parameters**

| Parameter | Format           | Required | Description                                                                                                                           |
| --------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `action`  | `APISign`        | Yes      | Must be set to `APISign`.                                                                                                             |
| `What`    | `SIGN`           | Yes      | Must be set to `SIGN` to request a new payment page.                                                                                  |
| `Masof`   | 10 digits        | Yes      | Your terminal number.                                                                                                                 |
| `KEY`     | String           | Yes      | Your terminal API key.                                                                                                                |
| `PassP`   | String           | Yes      | Your terminal API password.                                                                                                           |
| `Amount`  | Decimal          | Yes      | The amount to charge. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`).          |
| `Sign`    | `True` / `False` | No       | Set to `True` to receive a security signature that is required for [transaction validation](/pay/security/transaction-validation.md). |

**Customer information**

| Parameter     | Format   | Required | Description                            |
| ------------- | -------- | -------- | -------------------------------------- |
| `UserId`      | 9 digits | No       | The customer's Israeli ID.             |
| `ClientName`  | String   | No       | The customer's first name.             |
| `ClientLName` | String   | No       | The customer's last name.              |
| `street`      | String   | No       | The customer's street address.         |
| `city`        | String   | No       | The customer's city.                   |
| `email`       | String   | No       | The customer's email address.          |
| `cell`        | String   | No       | The customer's mobile phone number.    |
| `Order`       | String   | No       | An internal order ID for your records. |

**Installments**

| Parameter         | Format           | Required | Description                                                                                                                                  |
| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tash`            | Number           | No       | The maximum number of installments allowed.                                                                                                  |
| `FixTash`         | `True` / `False` | No       | If set to `True`, the customer must use the exact number of installments specified in `Tash`.                                                |
| `tashType`        | `1` / `6`        | No       | The [type of installments](/pay/common-use-cases/installments.md): `1` for regular (no interest, default) or `6` for credit (with interest). |
| `ShowEngTashText` | `True` / `False` | No       | Set to `True` to show installment labels when `PageLang` is `ENG`.                                                                           |

**Two-phase commits and postponing**

| Parameter  | Format           | Required | Description                                                                                                                          |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `Postpone` | `True` / `False` | No       | Set to `True` to [postpone the transaction](/pay/common-use-cases/postponing-transactions.md) for up to 72 hours.                    |
| `J5`       | `True` / `False` | No       | Set to `True` to perform a [two-phase commit](/pay/advanced-features/two-phase-commits.md) (authorization without immediate charge). |
| `MoreData` | `True` / `False` | No       | Set to `True` to receive additional parameters like `UID` and `UserId` in the redirect (required for two-phase commits).             |

If you set `MoreData=True` in the request, Hyp Pay will include additional transaction details in the [payment completion redirect](/pay/getting-started/creating-a-payment-page.md#handle-the-redirect-back-to-your-website):

| Parameter   | Description                                                                                                                         |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Bank`      | The name of the acquiring bank.                                                                                                     |
| `TransType` | The type of transaction (for example, `Internet-Secure`, `ApplePay`, or `GooglePay`).                                               |
| `Payments`  | The number of installments used for the transaction.                                                                                |
| `UserId`    | The customer's Israeli ID.                                                                                                          |
| `Brand`     | The brand of the credit card used (for example, `Visa` or `MasterCard`).                                                            |
| `Issuer`    | The entity that issued the card.                                                                                                    |
| `L4digit`   | The last four digits of the credit card.                                                                                            |
| `street`    | The customer's street address.                                                                                                      |
| `city`      | The customer's city.                                                                                                                |
| `zip`       | The customer's zip code.                                                                                                            |
| `cell`      | The customer's mobile phone number.                                                                                                 |
| `Coin`      | The currency used for the transaction.                                                                                              |
| `Tmonth`    | The expiration month of the card.                                                                                                   |
| `Tyear`     | The expiration year of the card.                                                                                                    |
| `Hesh`      | The invoice number, if an invoice was generated.                                                                                    |
| `UID`       | A unique transaction identifier used for [two-phase commits](/pay/advanced-features/two-phase-commits.md) and other advanced flows. |
| `spType`    | A code representing a special card type (for example, `Tourist` or `Immediate`).                                                    |
| `bincard`   | The first six digits of the card (Bank Identification Number).                                                                      |

**Recurring payments**

| Parameter          | Format           | Required | Description                                                                                                                                                                                             |
| ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HK`               | `True` / `False` | No       | Set to `True` to enable [recurring payments](/pay/advanced-features/recurring-payments.md).                                                                                                             |
| `freq`             | Number           | No       | The billing cycle in months for recurring payments.                                                                                                                                                     |
| `Tash`             | Number           | No       | How many charges to make. If you want it to keep recurring indefinitely, set this to `999`.                                                                                                             |
| `TashFirstPayment` | Number           | No       | Use this if you want the very first payment to be a different amount than the rest.                                                                                                                     |
| `FirstPaymentTash` | Number           | No       | The number of installments applied specifically to the first payment.                                                                                                                                   |
| `OnlyOnApprove`    | `True` / `False` | No       | Set to `True` if you only want the recurring agreement to kick in once the first payment is approved. `False` (the default) sets up the agreement even if that first payment is still pending or fails. |

**Invoicing**

| Parameter         | Format                         | Required | Description                                                                                                                          |
| ----------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `SendHesh`        | `True` / `False`               | No       | Set to `True` to [automatically email an invoice](/pay/invoicing/basic-invoicing.md) to the customer.                                |
| `sendHeshSMS`     | `True` / `False`               | No       | Set to `True` to send a link to the invoice via SMS.                                                                                 |
| `Pritim`          | `True` / `False`               | No       | Set to `True` to send a [detailed list of items](/pay/invoicing/basic-invoicing.md) for the invoice and show it on the payment page. |
| `heshDesc`        | String                         | No       | A description of the purchase for the invoice, or a list of items if `Pritim` is `True`.                                             |
| `EZ.lang`         | `he` / `en`                    | No       | The language for the invoice document. `he` (Hebrew) is the default.                                                                 |
| `EZ.comment`      | String                         | No       | Additional text that will be added after the body of the invoice document.                                                           |
| `EZ.description`  | String                         | No       | Text that will be inserted as the subheader of the invoice.                                                                          |
| `EZ.cc_emails`    | Comma-delimited list of emails | No       | You can provide a list of up to 10 additional email addresses to receive a copy of the invoice.                                      |
| `EZ.vat`          | Decimal                        | No       | Overrides the default VAT rate for the invoice.                                                                                      |
| `EZ.customer_crn` | String                         | No       | The customer's company number (BN) for the invoice.                                                                                  |

**Payment page UI customization**

| Parameter  | Format           | Required | Description                                                                     |
| ---------- | ---------------- | -------- | ------------------------------------------------------------------------------- |
| `PageLang` | `HEB` / `ENG`    | No       | The UI language for the payment page. `HEB` (Hebrew) is the default.            |
| `tmp`      | Number           | No       | The template number to use for the page's layout.                               |
| `hideBtns` | `True` / `False` | No       | Set to `True` to hide the payment method selection buttons on the payment page. |

#### Example request

Here's an example API request to create a payment page:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=APISign&What=SIGN&Sign=True&KEY=your-api-key&PassP=your-api-password&Masof=0010345518&Amount=10&Order=12345678910&tmp=2&PageLang=ENG&UserId=203269535&ClientName=Jenny&ClientLName=Parkington&street=HaDekel%2014&city=Rishon%20LeZion&email=jennyp@example.co.il&cell=0504999999
```

{% endcode %}

#### Example response

A successful request returns a URL-encoded string containing all parameters and a `signature`:

{% code overflow="wrap" %}

```
Amount=10&ClientLName=Parkington&ClientName=Jenny&Masof=0010345518&Order=12345678910&PageLang=ENG&Sign=True&UserId=203269535&action=pay&cell=0504999999&city=Rishon%20LeZion&email=jennyp%40example.co.il&street=HaDekel%2014&tmp=2&signature=0806fe45b00f11d4b3f3392d894fbfe8be372bb3822ae83fef87831c7c35426a
```

{% endcode %}

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=904
```

#### Response parameters

| Parameter   | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `action`    | This changes to `pay` in the response.                         |
| `signature` | The security signature generated by Hyp Pay.                   |
| `...`       | All other parameters passed in the request are returned as-is. |

#### Common status codes

| Code  | Meaning                                    |
| ----- | ------------------------------------------ |
| `0`   | Success. The request was signed correctly. |
| `902` | Authentication failure: wrong `PassP`.     |
| `904` | Missing `What` parameter.                  |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Validate a transaction

This is used to [verify transaction details](/pay/security/transaction-validation.md) directly with Hyp Pay's servers after a customer is redirected back to your site. It ensures the data hasn't been tampered with.

#### Prerequisites

* You must have included `Sign=True` in the initial `APISign` request.
* You need the full set of parameters from the [payment completion redirect](/pay/getting-started/creating-a-payment-page.md#handle-the-redirect-back-to-your-website).

#### Parameters

| Parameter | Format    | Required | Description                                                    |
| --------- | --------- | -------- | -------------------------------------------------------------- |
| `action`  | `APISign` | Yes      | Must be set to `APISign`.                                      |
| `What`    | `VERIFY`  | Yes      | Must be set to `VERIFY`.                                       |
| `Masof`   | 10 digits | Yes      | Your terminal number.                                          |
| `KEY`     | String    | Yes      | Your terminal API key.                                         |
| `PassP`   | String    | Yes      | Your terminal API password.                                    |
| `...`     | Various   | Yes      | All parameters from the redirect URL, in their original order. |

#### Example request

Here's an example API request to validate a transaction:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=APISign&What=VERIFY&Masof=0010345518&KEY=your-api-key&PassP=your-api-password&Id=408941655&CCode=0&Amount=10&ACode=0505293&Order=12345678910&Fild1=Jenny%20Parkington&Fild2=jennyp%40example.co.il&Fild3=&Sign=a84b11187377554427f267a9139ad4fd7daf7fb661dd668a9b954cf41cd25904
```

{% endcode %}

#### Example response

A successful validation request returns a simple confirmation:

```
CCode=0
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=200
```

#### Response parameters

| Parameter | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| `CCode`   | The status code. `0` indicates the transaction is valid and authentic. |

#### Common status codes

| Code  | Meaning                                                              |
| ----- | -------------------------------------------------------------------- |
| `0`   | Success. The transaction is verified.                                |
| `200` | Missing one or more parameters from the payment completion redirect. |
| `902` | Authentication failure: wrong `PassP`.                               |
| `904` | Missing `What` parameter.                                            |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Generate a link to an invoice

This is used to request a set of URL parameters that is then used to construct a URL to [download an existing invoice](/pay/invoicing/basic-invoicing.md#generating-links-to-invoices).

#### Prerequisites

* The transaction ID (`TransId`) or the invoice ID (`asm`) of the document you want to link to.

#### Parameters

| Parameter | Format      | Required | Description                                                                                      |
| --------- | ----------- | -------- | ------------------------------------------------------------------------------------------------ |
| `action`  | `APISign`   | Yes      | Must be set to `APISign`.                                                                        |
| `ACTION`  | `PrintHesh` | Yes      | The operation to be signed.                                                                      |
| `Masof`   | 10 digits   | Yes      | Your terminal number.                                                                            |
| `KEY`     | String      | Yes      | Your terminal API key.                                                                           |
| `PassP`   | String      | Yes      | Your terminal API password.                                                                      |
| `What`    | `SIGN`      | Yes      | Must be set to `SIGN` for the response to include a signature.                                   |
| `type`    | `EZCOUNT`   | Yes      | Must be set to `EZCOUNT`.                                                                        |
| `TransId` | String      | Yes      | The unique ID of the transaction to generate an invoice link for.                                |
| `asm`     | String      | No       | The unique ID of the invoice document to link to. This is not required if `TransId` is provided. |

#### Example request

Here's an example API request to get a set of URL parameters to generate an invoice link:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?Masof=0010210290&action=APISign&KEY=your-api-key&What=SIGN&PassP=your-api-password&TransId=55373520&type=EZCOUNT&ACTION=PrintHesh
```

{% endcode %}

#### Example response

A successful response returns a URL-encoded string:

{% code overflow="wrap" %}

```
Masof=0010345518&TransId=408615223&action=PrintHesh&type=EZCOUNT&signature=76942f55ffe7e2d7ba9d2501792a394cbce4e7d00de3da0d71f372ae919db9cd
```

{% endcode %}

If the request fails, you'll receive an error code:

```
CCode=902
```

#### Response parameters

| Parameter   | Description                            |
| ----------- | -------------------------------------- |
| `Masof`     | Your terminal number.                  |
| `TransId`   | The unique transaction ID.             |
| `action`    | The action being signed (`PrintHesh`). |
| `type`      | The document type (`EZCOUNT`).         |
| `signature` | The secure signature.                  |

#### Common status codes

| Code  | Meaning                                |
| ----- | -------------------------------------- |
| `0`   | Success. The signature was generated.  |
| `902` | Authentication failure: wrong `PassP`. |

For a full list of codes, see the [Status Codes](/pay/reference/response-status-codes.md) page.

## `action=CancelTrans`

The `CancelTrans` command is used to [cancel a transaction](/pay/common-use-cases/cancellations.md) before it has been transmitted to the card company for settlement.

#### Prerequisites

* The transaction must not have been transmitted yet (typically before 22:00 Israel time on the same day).
* You need the transaction `Id` (passed as `TransId`).

#### Parameters

| Parameter | Format        | Required | Description                                   |
| --------- | ------------- | -------- | --------------------------------------------- |
| `action`  | `CancelTrans` | Yes      | Must be set to `CancelTrans`.                 |
| `Masof`   | 10 digits     | Yes      | Your terminal number.                         |
| `PassP`   | String        | Yes      | Your terminal API password.                   |
| `TransId` | String        | Yes      | The unique `Id` of the transaction to cancel. |

#### Example request

Here's an example API request to cancel a transaction:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=CancelTrans&Masof=0010131918&PassP=your-api-password&TransId=405532558
```

{% endcode %}

#### Example response

A successful cancellation request returns a confirmation that looks like this:

```
TransId=405532558&CCode=0&Hesh=EZ&ReversalStatus=777
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
TransId=412701022&CCode=920
```

#### Response parameters

| Parameter        | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `TransId`        | The ID of the cancelled transaction.                     |
| `CCode`          | The status code. `0` indicates success.                  |
| `ReversalStatus` | A code indicating the cancellation status (e.g., `777`). |

#### Common status codes

| Code  | Meaning                                                                           |
| ----- | --------------------------------------------------------------------------------- |
| `0`   | Success. The transaction was cancelled.                                           |
| `902` | Authentication failure: wrong `PassP`.                                            |
| `920` | Transaction cannot be cancelled (e.g., doesn't exist or was already transmitted). |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

## `action=commitTrans`

The `commitTrans` command is used to [finalize a postponed transaction](/pay/common-use-cases/postponing-transactions.md). This completes a payment that was previously authorized with the `Postpone=True` parameter.

#### Prerequisites

* You must have a transaction that was initiated with `Postpone=True` and received a `CCode=800`.
* You need the transaction `Id` (passed as `TransId`).
* The finalization must occur within 72 hours of the original request.

#### Parameters

| Parameter | Format        | Required | Description                                   |
| --------- | ------------- | -------- | --------------------------------------------- |
| `action`  | `commitTrans` | Yes      | Must be set to `commitTrans`.                 |
| `Masof`   | 10 digits     | Yes      | Your terminal number.                         |
| `PassP`   | String        | Yes      | Your terminal API password.                   |
| `TransId` | String        | Yes      | The unique `Id` of the postponed transaction. |

#### Example request

Here's an example API request to finalize a postponed transaction:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=commitTrans&Masof=0010345518&TransId=403377225&PassP=your-api-password
```

{% endcode %}

#### Example response

A successful finalization request returns a URL-encoded string containing the unique transaction ID and other details:

```
Id=404011214&CCode=0&Fild1=&Fild2=&Fild3=&HeshASM=EZ
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
Id=41325843&CCode=250&Fild1=&Fild2=&Fild3=&HeshASM=0
```

#### Response parameters

| Parameter | Description                                                                |
| --------- | -------------------------------------------------------------------------- |
| `Id`      | The unique transaction ID for the finalized charge.                        |
| `CCode`   | The status code. `0` indicates the transaction was finalized successfully. |

#### Common status codes

| Code  | Meaning                                             |
| ----- | --------------------------------------------------- |
| `0`   | Success. The transaction was finalized and charged. |
| `250` | Transaction not found.                              |
| `902` | Authentication failure: wrong `PassP`.              |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

## `action=getToken`

The `getToken` command is used to [request a card token](/pay/common-use-cases/tokenization.md) after a card transaction. This allows you to charge the same card later without handling raw card data.

#### Prerequisites

* You must have the transaction ID (`Id`) from a previous transaction.
* Your terminal must have tokenization permissions.

#### Parameters

| Parameter    | Format           | Required | Description                                                                      |
| ------------ | ---------------- | -------- | -------------------------------------------------------------------------------- |
| `action`     | `getToken`       | Yes      | Must be set to `getToken`.                                                       |
| `Masof`      | 10 digits        | Yes      | Your terminal number.                                                            |
| `PassP`      | String           | Yes      | Your terminal API password.                                                      |
| `TransId`    | String           | Yes      | The unique transaction ID (`Id`) from the original payment.                      |
| `allowFalse` | `True` / `False` | No       | Set to `True` to get a token even if the original transaction wasn't successful. |

#### Example request

Here's an example API request to request a token:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=getToken&Masof=0010020610&PassP=your-api-password&TransId=401594866&allowFalse=True
```

{% endcode %}

#### Example response

A successful request returns a URL-encoded string containing the token and its expiration date:

{% code overflow="wrap" %}

```
Id=401594866&CCode=0&Token=0505743578473060772&Tokef=3105&Fild1=&Fild2=&Fild3=
```

{% endcode %}

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=902&Fild1=&Fild2=&Fild3=
```

#### Response parameters

| Parameter | Description                                  |
| --------- | -------------------------------------------- |
| `Token`   | The 19-digit card token.                     |
| `Tokef`   | The card's expiration date in `YYMM` format. |
| `CCode`   | The status code. `0` indicates success.      |

#### Common status codes

| Code  | Meaning                                                                  |
| ----- | ------------------------------------------------------------------------ |
| `0`   | Success. The token was retrieved.                                        |
| `901` | No permission for tokenization.                                          |
| `902` | Authentication failure: wrong `PassP`.                                   |
| `910` | Invalid transaction for tokenization (unless `allowFalse=True` is used). |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

## `action=HKStatus`

The `HKStatus` command is used to [manage recurring payment agreements](/pay/advanced-features/recurring-payments.md), specifically to terminate or resume them.

#### Prerequisites

* You need the unique agreement ID (`HKId`).
* You must decide whether to terminate or resume the agreement.

#### Parameters

| Parameter | Format     | Required | Description                                                      |
| --------- | ---------- | -------- | ---------------------------------------------------------------- |
| `action`  | `HKStatus` | Yes      | Must be set to `HKStatus`.                                       |
| `Masof`   | 10 digits  | Yes      | Your terminal number.                                            |
| `PassP`   | String     | Yes      | Your terminal API password.                                      |
| `HKId`    | String     | Yes      | The unique ID of the recurring agreement.                        |
| `NewStat` | `1` / `2`  | Yes      | The new status for the agreement: `1` (Terminate), `2` (Resume). |

#### Example request

Here's an example API request to terminate a recurring payment agreement:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=HKStatus&Masof=0010131918&PassP=your-api-password&HKId=64239&NewStat=1
```

{% endcode %}

#### Example response

A successful request returns the agreement ID and a confirmation:

```
HKId=64239&CCode=0
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
HKId=642390&CCode=906
```

#### Response parameters

| Parameter | Description                                               |
| --------- | --------------------------------------------------------- |
| `HKId`    | The ID of the updated agreement.                          |
| `CCode`   | The status code. `0` indicates the update was successful. |

#### Common status codes

| Code  | Meaning                                                                                 |
| ----- | --------------------------------------------------------------------------------------- |
| `0`   | Success. The agreement status was updated.                                              |
| `905` | Unsupported payment agreement state: `NewStat` is missing or set to an incorrect value. |
| `906` | The agreement does not exist.                                                           |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

## `action=payRequest`

The `payRequest` command is used to manage [payment links](/pay/common-use-cases/send-payment-links.md). It allows you to create, list, and cancel unique links that can be sent to customers via SMS or email.

### Create and send a payment link

This creates a new payment link and sends it to the customer.

#### Prerequisites

* You must enable the **payment links** feature in the Hyp Market section of your portal.
* You need the customer's email or mobile number.

#### Parameters

| Parameter    | Format       | Required | Description                                                                                                                             |
| ------------ | ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `action`     | `payRequest` | Yes      | Must be set to `payRequest`.                                                                                                            |
| `iCommand`   | `CREATE`     | Yes      | Must be set to `CREATE`.                                                                                                                |
| `Masof`      | 10 digits    | Yes      | Your terminal number.                                                                                                                   |
| `PassP`      | String       | Yes      | Your terminal API password.                                                                                                             |
| `Amount`     | Decimal      | Yes      | The amount for the payment link. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`). |
| `ClientName` | String       | Yes      | The customer's first name.                                                                                                              |
| `email`      | String       | No       | The customer's email address. Required if sending via email.                                                                            |
| `cell`       | String       | No       | The customer's mobile phone number. Required if sending via SMS.                                                                        |
| `Info`       | String       | No       | A description for the transaction.                                                                                                      |

#### Example request

Here's an example API request to create and send a payment link:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=payRequest&iCommand=CREATE&Masof=0010345518&PassP=your-api-password&Amount=100&Coin=1&Info=Order1234&UserId=000000000&ClientName=David&ClientLName=Cohen&email=david@example.com&cell=0501234567
```

{% endcode %}

#### Example response

A successful request returns the unique link ID and the payment URL:

{% code overflow="wrap" %}

```
payRequestId=abc123xyz&Fild1=Order1234&paymentURL=https://pay.hyp.co.il/p/?pay=3zwf90y
```

{% endcode %}

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=16&errMsg=Missing required fields
```

#### Response parameters

| Parameter      | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `payRequestId` | The unique ID for this payment link. Save this to manage the link later. |
| `paymentURL`   | The direct URL to the secure payment page.                               |

#### Common status codes

| Code  | Meaning                                 |
| ----- | --------------------------------------- |
| `0`   | Success. The link was created and sent. |
| `16`  | Missing required fields.                |
| `902` | Authentication failure: wrong `PassP`.  |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Get a list of payment links

This returns a list of the most recent payment links created for your terminal.

#### Parameters

| Parameter  | Format       | Required | Description                  |
| ---------- | ------------ | -------- | ---------------------------- |
| `action`   | `payRequest` | Yes      | Must be set to `payRequest`. |
| `iCommand` | `LIST`       | Yes      | Must be set to `LIST`.       |
| `Masof`    | 10 digits    | Yes      | Your terminal number.        |
| `PassP`    | String       | Yes      | Your terminal API password.  |

#### Example request

Here's an example API request to get a list of payment links:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=payRequest&iCommand=LIST&Masof=0010345518&PassP=your-api-password
```

{% endcode %}

#### Example response

A successful request returns a JSON array of link objects:

```json
[
  {
    "payRequestId": "abc123xyz",
    "status": "2",
    "Amount": "100",
    "paymentURL": "https://pay.hyp.co.il/p/?pay=3zwf90y",
    "dateCreated": "2026-03-10 14:56:20"
  }
]
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=902&Fild1=
```

#### Response parameters

| Parameter      | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `payRequestId` | The unique ID of the link.                                            |
| `status`       | The current status: `0` (Deleted), `1` (New), `2` (Sent), `3` (Paid). |
| `Amount`       | The link amount.                                                      |
| `paymentURL`   | The URL for the link.                                                 |

#### Common status codes

| Code  | Meaning                                       |
| ----- | --------------------------------------------- |
| `0`   | Success. The list was retrieved successfully. |
| `902` | Authentication failure: wrong `PassP`.        |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Cancel a payment link

This deactivates an existing payment link so it can no longer be used.

#### Prerequisites

* You need the `payRequestId` of the link you want to cancel.
* The link must not have been paid yet.

#### Parameters

| Parameter    | Format       | Required | Description                               |
| ------------ | ------------ | -------- | ----------------------------------------- |
| `action`     | `payRequest` | Yes      | Must be set to `payRequest`.              |
| `iCommand`   | `DELETE`     | Yes      | Must be set to `DELETE`.                  |
| `Masof`      | 10 digits    | Yes      | Your terminal number.                     |
| `PassP`      | String       | Yes      | Your terminal API password.               |
| `PayRequest` | String       | Yes      | The `payRequestId` of the link to cancel. |

#### Example request

Here's an example API request to cancel a payment link:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=payRequest&iCommand=DELETE&Masof=0010345518&PassP=your-api-password&PayRequest=abc123xyz
```

{% endcode %}

#### Example response

A successful cancellation returns a confirmation:

```
CCode=0&status=0
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=250
```

#### Response parameters

| Parameter | Description                                    |
| --------- | ---------------------------------------------- |
| `CCode`   | The status code. `0` indicates success.        |
| `status`  | The new status of the link. `0` means deleted. |

#### Common status codes

| Code  | Meaning                                                  |
| ----- | -------------------------------------------------------- |
| `0`   | Success. The link was cancelled.                         |
| `250` | Link doesn't exist.                                      |
| `995` | Link cannot be deleted because it has already been paid. |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

## `action=soft`

The `soft` command is the primary server-to-server execution engine for Hyp Pay. Unlike hosted pages, this action performs a direct financial operation and returns a raw response string, typically URL-encoded text, that contains the transaction result.

Because this command is multi-purpose, the required parameters and logic change based on the specific use case.

### Charge a saved token

This is used for [recurring billing](/pay/advanced-features/recurring-payments.md) or "one-click" payments where you already have a valid [token](/pay/common-use-cases/tokenization.md) from a previous transaction.

#### Prerequisites

To charge a saved token, you must have previously obtained:

* A 19-digit `Token` for the customer's card.
* The card's expiration date (`Tokef`) in `YYMM` format.
* The customer's Israeli ID number (`UserId`), if your terminal requires it.

#### Parameters

| Parameter          | Format                  | Required | Description                                                                                                                                          |
| ------------------ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`           | `soft`                  | Yes      | Must be set to `soft`.                                                                                                                               |
| `Masof`            | 10 digits               | Yes      | Your terminal number.                                                                                                                                |
| `PassP`            | String                  | Yes      | Your terminal API password.                                                                                                                          |
| `ClientName`       | String                  | Yes      | The customer's first name.                                                                                                                           |
| `Info`             | String                  | Yes      | A description of the transaction for reporting purposes.                                                                                             |
| `Token`            | `True` / `False`        | Yes      | Set to `True` to indicate the `CC` field contains a token.                                                                                           |
| `CC`               | 19-digit token          | Yes      | The saved token string that replaces the raw card number.                                                                                            |
| `Amount`           | Decimal                 | Yes      | The amount to charge. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`).                         |
| `Tmonth`           | MM                      | Yes      | The card expiry month in MM format.                                                                                                                  |
| `Tyear`            | YY                      | Yes      | The card expiry year in YY format.                                                                                                                   |
| `UserId`           | 9 digits or `000000000` | Yes      | The customer's Israeli ID. If your terminal doesn't require one, use `000000000`.                                                                    |
| `ClientLName`      | String                  | No       | The customer's last name.                                                                                                                            |
| `street`           | String                  | No       | The customer's street address.                                                                                                                       |
| `city`             | String                  | No       | The customer's city.                                                                                                                                 |
| `zip`              | String                  | No       | The customer's zip code.                                                                                                                             |
| `phone`            | String                  | No       | The customer's landline phone number.                                                                                                                |
| `cell`             | String                  | No       | The customer's mobile phone number.                                                                                                                  |
| `email`            | String                  | No       | The customer's email address.                                                                                                                        |
| `Coin`             | `1` / `2` / `3` / `4`   | No       | The currency of the transaction: `1` for ILS (default), `2` for USD, `3` for EUR, `4` for GBP.                                                       |
| `Tash`             | Number                  | No       | The number of installments for the transaction.                                                                                                      |
| `tashType`         | `1` / `6`               | No       | The [type of installments](/pay/common-use-cases/installments.md): `1` for regular or `6` for credit.                                                |
| `TashFirstPayment` | Decimal                 | No       | A different amount for the first installment. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`). |
| `tOwner`           | 10 digits               | No       | In a multi-terminal setup, specifies the terminal number that obtained the card token when it's different from the terminal making the charge.       |
| `Postpone`         | `True` / `False`        | No       | Set to `True` to [postpone the transaction](/pay/common-use-cases/postponing-transactions.md) for up to 72 hours.                                    |
| `J5`               | `True` / `False`        | No       | Set to `True` to perform a [two-phase commit](/pay/advanced-features/two-phase-commits.md) (authorization without immediate charge).                 |
| `sendemail`        | `True` / `False`        | No       | Set to `True` to send a payment confirmation email to the customer.                                                                                  |
| `MoreData`         | `True` / `False`        | No       | Set to `True` to receive additional transaction details in the response.                                                                             |
| `UTF8`             | `True` / `False`        | No       | Set to `True` if the request data is encoded in UTF-8.                                                                                               |
| `UTF8out`          | `True` / `False`        | No       | Set to `True` to receive the response encoded in UTF-8.                                                                                              |
| `Fild1`            | String                  | No       | A custom field for your own use. This value is returned in the response but not saved by Hyp Pay.                                                    |
| `Fild2`            | String                  | No       | A custom field for your own use. This value is returned in the response but not saved by Hyp Pay.                                                    |
| `Fild3`            | String                  | No       | A custom field for your own use. This value is returned in the response but not saved by Hyp Pay.                                                    |

If you set `MoreData=True` in the request, Hyp Pay will include additional transaction details in the [payment completion redirect](/pay/getting-started/creating-a-payment-page.md#handle-the-redirect-back-to-your-website):

| Parameter   | Description                                                                                                                         |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `Bank`      | The name of the acquiring bank.                                                                                                     |
| `TransType` | The type of transaction (for example, `Internet-Secure`, `ApplePay`, or `GooglePay`).                                               |
| `Payments`  | The number of installments used for the transaction.                                                                                |
| `UserId`    | The customer's Israeli ID.                                                                                                          |
| `Brand`     | The brand of the credit card used (for example, `Visa` or `MasterCard`).                                                            |
| `Issuer`    | The entity that issued the card.                                                                                                    |
| `L4digit`   | The last four digits of the credit card.                                                                                            |
| `street`    | The customer's street address.                                                                                                      |
| `city`      | The customer's city.                                                                                                                |
| `zip`       | The customer's zip code.                                                                                                            |
| `cell`      | The customer's mobile phone number.                                                                                                 |
| `Coin`      | The currency used for the transaction.                                                                                              |
| `Tmonth`    | The expiration month of the card.                                                                                                   |
| `Tyear`     | The expiration year of the card.                                                                                                    |
| `Hesh`      | The invoice number, if an invoice was generated.                                                                                    |
| `UID`       | A unique transaction identifier used for [two-phase commits](/pay/advanced-features/two-phase-commits.md) and other advanced flows. |
| `spType`    | A code representing a special card type (for example, `Tourist` or `Immediate`).                                                    |
| `bincard`   | The first six digits of the card (Bank Identification Number).                                                                      |

#### Example request

Here's an example API request to charge a saved token:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&Amount=10&CC=6920843946458103712&Tmonth=06&Tyear=26&Token=True&UserId=000000000&ClientName=Jenny&Info=recurring%20transaction
```

{% endcode %}

#### Example response

A successful charge returns a URL-encoded string containing the unique transaction ID and other details:

{% code overflow="wrap" %}

```
Id=408671193&CCode=0&Amount=10&ACode=0502150&Fild1=&Fild2=&Fild3=&Hesh=EZ
```

{% endcode %}

If the charge fails, the response will include a non-zero status code:

```
Id=414564871&CCode=997&Amount=10&ACode=&Fild1=&Fild2=&Fild3=
```

#### Response parameters

| Parameter | Description                                          |
| --------- | ---------------------------------------------------- |
| `Id`      | The unique transaction ID for this charge.           |
| `CCode`   | The status code. A value of `0` indicates success.   |
| `Amount`  | The final amount charged.                            |
| `ACode`   | The authorization code returned by the card company. |
| `Hesh`    | The type of invoice or receipt generated.            |

#### Common status codes

| Code  | Meaning                                                                              |
| ----- | ------------------------------------------------------------------------------------ |
| `0`   | Success. The transaction was approved and charged.                                   |
| `6`   | Transaction declined: incorrect CVV2. May also indicate a missing Israeli ID number. |
| `401` | First or last name is required but not provided.                                     |
| `402` | Transaction information is required but not provided.                                |
| `447` | Incorrect card number or a missing `Token=True` parameter.                           |
| `902` | Authentication failure: wrong `PassP`.                                               |
| `901` | No permission. Your terminal isn't authorized for tokenization.                      |
| `997` | Invalid token.                                                                       |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Capture (J4) after J5 authorization

This is used to finalize a [two-phase transaction](/pay/advanced-features/two-phase-commits.md). This moves the **frozen funds** from the authorization phase into the merchant's account.

#### Prerequisites

Before you can perform a capture, you must have already authorized a transaction (J5) and saved the following values from that authorization:

* The transaction's `ACode`.
* The transaction's unique `UID`.
* The card `Token` and its expiration date (`Tokef`).
* The original authorized amount.
* The customer's Israeli ID number (`UserId`).

#### Parameters

| Parameter                          | Format                  | Required | Description                                                                                                                                                                                            |
| ---------------------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action`                           | `soft`                  | Yes      | Must be set to `soft`.                                                                                                                                                                                 |
| `Masof`                            | 10 digits               | Yes      | Your terminal number.                                                                                                                                                                                  |
| `PassP`                            | String                  | Yes      | Your terminal API password.                                                                                                                                                                            |
| `AuthNum`                          | String                  | Yes      | The authorization code received as `ACode` from the original J5 response.                                                                                                                              |
| `inputObj.originalAmount`          | Integer (subunits)      | Yes      | The original amount authorized in the J5 step, in currency subunits (like agurot or cents).                                                                                                            |
| `inputObj.originalUid`             | String                  | Yes      | The unique `UID` returned by the original J5 response.                                                                                                                                                 |
| `inputObj.authorizationCodeManpik` | `7`                     | Yes      | A static value used for captures — always set this to `7`.                                                                                                                                             |
| `Amount`                           | Decimal                 | Yes      | The final amount to capture. This must be less than or equal to the original authorized amount. This can be a decimal number with up to two fractional digits (for example, `15.00`, `15.5`, or `15`). |
| `Token`                            | `True` / `False`        | Yes      | Must be set to `True` since you're using a card token.                                                                                                                                                 |
| `CC`                               | 19-digit token          | Yes      | The saved token string from the original transaction.                                                                                                                                                  |
| `Tmonth`                           | MM                      | Yes      | The card expiry month in MM format.                                                                                                                                                                    |
| `Tyear`                            | YY                      | Yes      | The card expiry year in YY format.                                                                                                                                                                     |
| `UserId`                           | 9 digits or `000000000` | Yes      | The Israeli ID you saved from the original transaction. If the customer didn't enter one, use `000000000`.                                                                                             |
| `ClientName`                       | String                  | Yes      | The customer's first name.                                                                                                                                                                             |
| `Info`                             | String                  | Yes      | Any extra info you want to include with the transaction.                                                                                                                                               |

#### Example request

Here's an example API request to capture a previously authorized transaction:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&Token=True&CC=4652588708969300772&Tmonth=05&Tyear=31&AuthNum=0463077&Amount=15&inputObj.originalAmount=1500&inputObj.originalUid=26031819235508822860136&inputObj.authorizationCodeManpik=7&UserId=000000000&ClientName=Jenny&Info=final%20charge
```

{% endcode %}

#### Example response

A successful capture returns a URL-encoded string with the charge details:

{% code overflow="wrap" %}

```
Id=404274302&CCode=0&Amount=15&ACode=0463077&Fild1=&Fild2=&Fild3=&Hesh=EZ
```

{% endcode %}

If the request fails, the response will contain a non-zero status code (`CCode`):

```
Id=0&CCode=402&Amount=16&ACode=&Fild1=&Fild2=&Fild3=
```

#### Response parameters

| Parameter | Description                                                |
| --------- | ---------------------------------------------------------- |
| `Id`      | The unique transaction ID for the capture.                 |
| `CCode`   | The status code. `0` indicates the capture was successful. |
| `Amount`  | The final amount captured.                                 |
| `ACode`   | The authorization code for the capture.                    |

#### Common status codes

| Code  | Meaning                                                           |
| ----- | ----------------------------------------------------------------- |
| `0`   | Success. The funds were captured and the transaction is complete. |
| `401` | First or last name is required but not provided.                  |
| `402` | Transaction information is required but not provided.             |
| `902` | Authentication failure: wrong `PassP`.                            |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Perform a payout

This is used to [push funds](/pay/advanced-features/payouts.md) from the merchant account back to a customer's card. This requires a secondary security password.

#### Prerequisites

To perform a payout, you must:

* Contact Hyp support to obtain a **credit password** (`zPass`).
* Obtain a card `Token` and its expiration date for the card receiving the funds.

#### Parameters

| Parameter    | Format                  | Required | Description                                                                                                                                         |
| ------------ | ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`     | `soft`                  | Yes      | Must be set to `soft`.                                                                                                                              |
| `Masof`      | 10 digits               | Yes      | Your terminal number.                                                                                                                               |
| `PassP`      | String                  | Yes      | Your terminal API password.                                                                                                                         |
| `zPass`      | String                  | Yes      | A secondary password specifically for payouts and refunds.                                                                                          |
| `CC`         | 19-digit token          | Yes      | The card token receiving the funds.                                                                                                                 |
| `Amount`     | Decimal                 | Yes      | The amount to send to the customer. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`).          |
| `Token`      | `True` / `False`        | No       | Set to `True` if you are using a token in the `CC` field.                                                                                           |
| `Tmonth`     | MM                      | Yes      | The card expiry month in MM format.                                                                                                                 |
| `Tyear`      | YY                      | Yes      | The card expiry year in YY format.                                                                                                                  |
| `UserId`     | 9 digits or `000000000` | Yes      | The customer's Israeli ID number. If you're making a payout to a non-Israeli card or you don't want to save the ID number, set this to `000000000`. |
| `ClientName` | String                  | Yes      | The customer's first name.                                                                                                                          |
| `Info`       | String                  | Yes      | Any extra info you want to include with the transaction.                                                                                            |

#### Example request

Here's an example API request to perform a payout:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&zPass=8179&Amount=10&CC=4724478937284730772&Tmonth=05&Tyear=31&Token=True&UserId=203269535&ClientName=Jenny&Info=payout
```

{% endcode %}

#### Example response

A successful payout returns a URL-encoded string confirming the operation:

{% code overflow="wrap" %}

```
Id=5920751&CCode=0&Amount=10&ACode=0034903&Fild1=&Fild2=&Fild3=&Hesh=47
```

{% endcode %}

If the request fails, the response will contain a non-zero status code (`CCode`):

```
Id=0&CCode=401&Amount=1&ACode=&Fild1=&Fild2=&Fild3=
```

#### Response parameters

| Parameter | Description                               |
| --------- | ----------------------------------------- |
| `Id`      | The unique transaction ID for the payout. |
| `CCode`   | The status code. `0` indicates success.   |
| `Amount`  | The amount credited to the customer.      |
| `ACode`   | The authorization code for the payout.    |

#### Common status codes

| Code  | Meaning                                               |
| ----- | ----------------------------------------------------- |
| `0`   | Success. The funds were sent to the card.             |
| `401` | First or last name is required but not provided.      |
| `402` | Transaction information is required but not provided. |
| `901` | Wrong `zPass`.                                        |
| `902` | Authentication failure: wrong `PassP`.                |
| `997` | Invalid token.                                        |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.md).

### Create an invoice for an offline transaction

This is used to generate an [invoice for an offline transaction](/pay/invoicing/basic-invoicing.md#creating-invoices-for-offline-transactions).

#### Parameters

The parameters for creating an offline invoice are grouped into basic transaction details and payment type-specific fields.

**Basic parameters**

| Parameter     | Format                     | Required | Description                                                                                                                          |
| ------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `action`      | `soft`                     | Yes      | Must be set to `soft`.                                                                                                               |
| `Masof`       | 10 digits                  | Yes      | Your terminal number.                                                                                                                |
| `PassP`       | String                     | Yes      | Your terminal API password.                                                                                                          |
| `Amount`      | Decimal                    | Yes      | The amount received. This can be a decimal number with up to two fractional digits (for example, `200.00`, `200.5`, or `200`).       |
| `TransType`   | `Cash` / `Check` / `Multi` | Yes      | The type of payment received. Use `Multi` for multiple checks.                                                                       |
| `SendHesh`    | `True` / `False`           | No       | Set to `True` if you want to email the invoice to the customer.                                                                      |
| `Pritim`      | `True` / `False`           | No       | Set to `True` to send a [detailed list of items](/pay/invoicing/basic-invoicing.md) for the invoice and show it on the payment page. |
| `heshDesc`    | String                     | No       | A description of the purchase for the invoice, or a list of items if `Pritim` is `True`.                                             |
| `email`       | String                     | No       | Your customer's email address.                                                                                                       |
| `ClientName`  | String                     | Yes      | The customer's first name.                                                                                                           |
| `ClientLName` | String                     | No       | The customer's last name.                                                                                                            |
| `UserId`      | 9 digits                   | Yes      | Your customer's Israeli ID. If unknown or not applicable, use `000000000`.                                                           |
| `Info`        | String                     | Yes      | A description of the transaction for your records.                                                                                   |
| `UTF8`        | `True`                     | No       | Set to `True` to ensure Hebrew characters in parameters are processed correctly.                                                     |
| `UTF8out`     | `True`                     | No       | Set to `True` to receive the response in UTF-8 encoding.                                                                             |

**Payment type-specific parameters**

Depending on the `TransType`, you may need to provide additional details:

* For `Cash`: No additional parameters are required.
* For `Check`: Provide `Bank` (bank code), `Snif` (branch number), `PAN` (account number), `CheckNum` (check number), and `Date` (in `YYYYMMDD` format).
* For `Multi`: You can send details for multiple checks by providing comma-separated lists for the check parameters (e.g., `Amount=100,50&CheckNum=111,222`).

#### Example request

Here's an example API request to record a cash payment of 200 ILS and generate an invoice:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&Amount=200&TransType=Cash&SendHesh=True&Info=Offline+cash+payment&email=jennyp@example.co.il&ClientName=Jenny&ClientLName=Parkington&UserId=890108558
```

{% endcode %}

#### Example response

A successful response contains `CCode=0`, which confirms that the transaction was recorded and the invoice was generated:

{% code overflow="wrap" %}

```
Id=416194874&CCode=0&Amount=200&ACode=&Fild1=&Fild2=&Fild3=&Hesh=EZ
```

{% endcode %}

If the request fails, the response will contain a non-zero status code:

```
Id=0&CCode=400&Amount=200&ACode=&Fild1=&Fild2=&Fild3=
```

#### Response parameters

| Parameter | Description                                              |
| --------- | -------------------------------------------------------- |
| `CCode`   | The status code of the operation. `0` indicates success. |
| `Amount`  | The transaction amount.                                  |
| `Id`      | The unique ID assigned to this record in Hyp Pay.        |
| `ACode`   | The authorization code. Empty for offline transactions.  |
| `Hesh`    | The type of invoice or receipt generated.                |

#### Common status codes

| Code  | Meaning                                                                              |
| ----- | ------------------------------------------------------------------------------------ |
| `0`   | Success. The transaction was recorded and the invoice was generated.                 |
| `6`   | Transaction declined: incorrect CVV2. May also indicate a missing Israeli ID number. |
| `400` | Sum of items differs from transaction amount.                                        |

For a full list of codes, see the [Status Codes](/pay/reference/response-status-codes.md) page.

## `action=zikoyAPI`

The `zikoyAPI` command is used to [perform a refund](/pay/common-use-cases/refunds.md) for a transaction that has already been settled.

#### Prerequisites

* The original transaction must have been transmitted and settled.
* You need the transaction `Id` (passed as `TransId`).
* You need to specify the amount to refund (can be partial).

#### Parameters

| Parameter | Format     | Required | Description                                                                                                                  |
| --------- | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `action`  | `zikoyAPI` | Yes      | Must be set to `zikoyAPI`.                                                                                                   |
| `Masof`   | 10 digits  | Yes      | Your terminal number.                                                                                                        |
| `PassP`   | String     | Yes      | Your terminal API password.                                                                                                  |
| `TransId` | String     | Yes      | The unique `Id` of the original transaction.                                                                                 |
| `Amount`  | Decimal    | Yes      | The amount to refund. This can be a decimal number with up to two fractional digits (for example, `10.00`, `10.5`, or `10`). |

#### Example request

Here's an example API request to perform a refund:

{% code overflow="wrap" %}

```http
https://pay.hyp.co.il/p/?action=zikoyAPI&Masof=0010131918&PassP=your-api-password&TransId=12290620&Amount=10
```

{% endcode %}

#### Example response

A successful request returns a URL-encoded string containing the new unique transaction ID for the refund:

```
Id=405577499&CCode=0&ACode=0476241&HeshASM=EZ
```

If the request fails, the response will contain a non-zero status code (`CCode`):

```
CCode=33
```

#### Response parameters

| Parameter | Description                                   |
| --------- | --------------------------------------------- |
| `Id`      | The new unique ID for the refund transaction. |
| `CCode`   | The status code. `0` indicates success.       |

#### Common status codes

| Code  | Meaning                                        |
| ----- | ---------------------------------------------- |
| `0`   | Success. The refund was processed.             |
| `33`  | Amount exceeds the original transaction value. |
| `902` | Authentication failure: wrong `PassP`.         |

For a full list of possible response codes, see [Status Codes](/pay/reference/response-status-codes.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/pay/reference/actions.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.