# HolestPay FrontCore Integration — Guide for Lovable / AI Code Generators

> **Full technical reference:** https://apps.holest.com/holest-pay/AI_INTEGRATION_GUIDE_FRONTCORE.md.txt  
> **Working sample (sandbox):** https://apps.holest.com/holest-pay/test/sandbox-164-hpay-frontcore-sample.html  
> (View page source and inspect `<code>` tags for real implementation examples.)
>
> **Sample data files — read these to understand real data structures:**
> - `pos_as_read.json` — https://apps.holest.com/holest-pay/pos_as_read.json  
>   Full `client.POS` (same as HPay.POS) object as returned by `HPayInit()`. Contains `payment`, `shipping`, and `fiscal` method arrays with all their properties (`Uid`, `HPaySiteMethodId`, `Name`, `Hidden`, `SubsciptionsType`, `POps`, `PayInputUrl`, `Use IFRAME`, etc.). **Read this to know what payment/shipping methods look like before building any selector UI.**
> - `response_sample.json` — https://apps.holest.com/holest-pay/response_sample.json  
>   Full `hpay_response` object as received in `onHPayResult` event and as POST-back `hpay_forwarded_payment_response`. Contains `payment_status`, `status`, `transaction_uid`, `transaction_user_info`, `vault_token_uid`, `vault_card_brand`, `vault_card_umask`, `vault_exp`, `payment_html`, `fiscal_html`, `integr_html`, `shipping_html`, and all other result fields. **Read this to know what data is available when displaying the thank-you / order confirmation page.**

---

## ?? FIRST ACTION — Ask the User for Their FrontCore Script URL

**Before writing any code, ask the user:**

> *"Please give me your HolestPay FrontCore script URL. It looks like this:*
> `<script src="https://sandbox.pay.holest.com/clientpay/handlers/pos/YOUR-UID/frontend-script-core.js"></script>`
> *Do you have it?"*

**If the user says they don't have it, or doesn't know what it is, explain:**

> *"This is a unique `<script>` tag that HolestPay generates specifically for your POS/site. It contains your Merchant Site UID in the URL and acts as the authorization key for the JavaScript-only checkout — no backend signature is needed because of it.*
>
> *Here is how to get it:*
> 1. Go to https://sandbox.pay.holest.com (if you are testing) or https://pay.holest.com (if you are going live). Create an account if you don't have one.
> 2. Create a **company** on the HPay panel.
> 3. Create a **POS / site** for that company.
> 4. Add the **payment methods** you want to offer. You can test them right away using the built-in **Pay-By-Link** feature (no integration needed for that).
> 5. *(Optional)* Add **fiscal**, **integration**, and/or **shipping** modules if you need them.
> 6. In the top bar, select your company and site, then go to **Site Settings**.
> 7. Find the field **"Frontend Script-Core Origins"** and enter your site's domain (one per line, wildcards allowed — e.g. `*.mysite.com`). Save.
> 8. The panel will immediately display the full `<script>` tag. Copy it and paste it here."*

**Do not proceed with implementation until the user provides this script tag.**  
Once you have it, extract the `src` URL — that is all you need to continue.

> ### ?? IMPORTANT — Tell the user this before any code is written:
>
> *"Before we start the implementation, please make sure you have done the following on the HolestPay panel:*
>
> - ? **All payment methods** you want to offer are added to your POS and working
> - ? **Shipping methods** are added and configured (if you need shipping)
> - ? **Fiscal / integration modules** are added and configured (if you need fiscalization)
> - ? **Every method has been tested using the HPay panel's Pay-By-Link feature** — this lets you create a real test payment link without any code and confirm each method actually processes correctly
>
> *This is critical. If a payment method is missing, misconfigured, or untested on the HPay panel, the implementation here will point in the wrong direction and you will waste time debugging something that is actually a panel configuration problem, not a code problem. Fix the HPay panel first, then come back here."*

Then ask the user the following **before starting to build**:

> *"A few things to know before we start:*
>
> - **Existing payment and shipping methods on your site do not need to be removed.** HolestPay payment and shipping methods are added **alongside** whatever you already have. You can keep PayPal, Stripe, manual bank transfer, COD — all of it — and HolestPay methods appear as additional options in the same selectors.
>
> - **Tip:** HolestPay also supports defining **generic payment methods** directly in the HPay panel — cash on delivery (COD), manual bank transfer, and other custom manual methods. If you want everything managed in one place through HolestPay (instead of mixing HolestPay with your platform's built-in methods), that is possible. Just add those methods on the HPay panel as well. But this is entirely optional — you decide what goes through HolestPay and what doesn't.
>
> *Do you also need:*
> - ?? **Shipping modules** — HolestPay can provide shipping method selection with carrier integrations, address autocomplete, and shipping labels/receipts. Do you have shipping methods configured on your HPay POS?
> - ?? **Fiscalization** — HolestPay can issue fiscal receipts automatically after payment (required by law in some countries). Do you have a fiscal module configured on your HPay POS?"*

- ?? **Subscriptions / card saving** — HolestPay can save a card token after the first payment so the buyer doesn't need to re-enter card details next time, or for automatic recurring charges. **Note: not all payment methods support this** — only methods where `pm.SubsciptionsType` contains `"cof"` or `"mit"` do. Do you plan to offer subscriptions or saved-card checkout?
  - **Important:** automatic renewal charges (MIT — Merchant Initiated Transaction) require a **merchant account at a bank that supports MIT**. Subscriptions can still be charged **manually** without automatic MIT.
  - If yes, also update Terms of Service / purchase conditions so they describe subscriptions from the **buyer's perspective** (what renewals look like, how to cancel, how saved cards are used). See **Subscriptions Integration Recommendations**.
  - Implement subscriptions **only if the user confirms**.

- ?? **Backend admin commands (refunds, captures, cancellations, etc.)** — HolestPay provides admin operations that can be triggered from your order detail / order list pages (e.g. capture a reservation, issue a refund, resend a fiscal receipt). These require the **Merchant Site Secret Key** on the server side.
  - **If the site runs on Shopify, BigCommerce, or a similar hosted platform** — skip this, backend is not needed.
  - **If you are building a custom backend or the user's platform allows custom server code** — ask: *"Do you want admin payment actions (refund, capture, cancel, etc.) available on your order detail or order list pages?"*
  - Also ask: *"Do you need your admin backend to list / load / update HolestPay orders via REST (`getOrders` / `getOrder` / `updateOrder`)? See Admin Order REST API."*
  - Also ask: *"Do you need manual server calls for payment sync (`queryRequest`), void, refund, capture, or other fiscal/shipping/integration handlers? See Payment / Module Backend Handlers."*
  - Also ask: *"Do you need HolestPay fiscal/shipping/integration (or a Pay-By-Link) on orders that were not paid via HPay checkout? See Store Order API (`POST /clientpay/store`)."*

- ?? **Shopify payment method name parity (Shopify only)** — If the user is on Shopify, ask them to create a custom/manual Shopify payment method with the **exact same name** as configured in HolestPay admin. If the name is changed later, it must be updated in **both** Shopify and HolestPay admin to stay aligned.

- ?? **Shopify shipping method/price parity (Shopify only)** — If the user is on Shopify, ask them to configure Shopify shipping rates using the **same shipping method names** as in HolestPay POS, and keep names synchronized in both systems if they are renamed.

- ?? **Footer bank/card/3DS logotypes** — Do you want us to implement the footer branding strip with card logos, bank logos, and 3DS logos sourced from HolestPay POS parameters (as required by banks for production approval)? These logotypes should be visible in the site footer on **all site pages**, not only on checkout.

- ?? **Terms of Service source strategy** — Do you want to use the HolestPay-provided Terms of Service page directly, compare it and merge equivalent clauses into your existing Terms page, or handle Terms in another way?

- ?? **Checkout acceptance checkbox** — Do you need an `I accept Terms of Service` checkbox on checkout, where `Terms of Service` is clickable (opens your TOS page or modal)?

Implement shipping, fiscalization, subscription/card-saving, and backend admin commands **only if the user confirms they need them.** If unsure, tell them they can add it later — the POS configuration drives what is available (`client.POS.shipping`, `client.POS.fiscal`, `pm.SubsciptionsType`, `pm.POps`) and nothing breaks if a feature is not configured.

---

## What FrontCore Is

FrontCore is a **JavaScript-only** HolestPay integration. No backend signature is required for checkout — the POS-specific script URL acts as the authorization token. A secret key is only needed on the server for backend charges and admin operations.

## HolestPay Order Status Format

```shell
[PAYMENT:payment_status][ (fmethod1_uid)_FISCAL:(fmethod1_status) [(fmethod2_uid)_FISCAL:(fmethod2_status)]...][ (imethod1_uid)_INTEGR:(imethod1_status) [(imethod2_uid)_INTEGR:(imethod2_status)]...][ (smethod1_uid)_SHIPPING:packet_no@shipping_status [(smethod2_uid)_SHIPPING:packet_no@shipping_status]...]
```

- ORDER OF SUB-STATUSES SECTIONS PAYMENT -> FISCAL & INTEGRATION -> SHIPPING IS IMPORTANT.
- ORDER OF METHOD STATUSES WITHIN SAME SUB-STATUSES SECTION IS NOT IMPORTANT.
- ONE AND ONLY ONE SPACE CHARACTER AS SUB-STATUSES SEPARATOR IS IMPORTANT.

```shell
Possible payment status:
    SUCCESS (alias of PAID)
    PAID
    PAYING (partially paid, indicates all partial payments are on time; used for advance payments or multi-source payments)
    AWAITING (waiting bank transfer, for example)
    REFUNDED
    PARTIALLY-REFUNDED
    VOID
    OVERDUE
    RESERVED (amount is reserved but still not captured from buyer card)
    EXPIRED (used with methods that have expiration)
    OBLIGATED (same as AWAITING but when service delivery has started or there is legal means to guarantee payment will happen)
    REFUSED
    FAILED
    CANCELED
```

`PAYMENT:payment_status` may not exist if HolestPay payment module is not used and you do not set it explicitly.

```shell
Possible fiscal module status:
  - varies depending on module
```

Fiscal/Integration statuses exist only if fiscal/integration modules add status and are executed.

```shell
Possible packet shipping status:
    PREPARING - initial status if shipping address is OK; instructions can be submitted to courier from this status
    READY - used by some companies to indicate goods are checked and ready for courier submission
    SUBMITTED - request submitted to courier
    DELIVERY - under delivery
    DELIVERED - delivered
    ERROR - error in courier API request
    RESOLVING - shipping address (or something else) needs backend attention
    FAILED - delivery permanently failed, or courier API refused the request
    REVOKED - explicitly canceled by buyer or company
```

Shipping statuses exist only when packets are handled by HolestPay shipping modules.

### ?? FrontCore Security Trade-off — Amount Manipulation

Because everything runs on the frontend without a server-side signature, **FrontCore does not protect against amount manipulation**. A technically skilled buyer could in theory alter the `order_amount` in the JavaScript before the payment is submitted (e.g. change 3000 RSD to 30 RSD) and the payment would succeed at the tampered amount.

**When this is acceptable (most cases):**
- Sites selling **physical/tangible goods** — the merchant sees 30 RSD was paid instead of 3000 RSD and simply does not ship the order. No automated fulfillment happens before a human reviews it.
- Low-risk digital goods or services where order values are small or fixed.
- Situations where the webhook (`notify_url`) result is verified server-side before fulfillment is triggered.

**When you should use the Standard integration instead (server-side signature):**
- Automatic digital fulfillment (license keys, downloads, subscriptions activated instantly)
- High-value orders where manual review of every payment is not practical
- Any case where the server automatically fulfills the order based solely on the payment result without a human check

> **Tell the user this before implementing FrontCore:**  
> *"FrontCore is the simplest integration but it does not prevent a determined buyer from manipulating the payment amount on the frontend. For most shops selling physical goods this is fine — you simply don't ship if the paid amount doesn't match the order. If your site automatically delivers digital goods or activates services immediately after payment, you need the **Standard integration with server-side signature** instead — see https://apps.holest.com/holest-pay/AI_INTEGRATION_GUIDE_STANDARD.md.txt — which cryptographically signs each request on your server so the amount cannot be tampered with on the frontend."*

---

## What You Need from the User Before You Start

**The user must provide one thing to start: their FrontCore script `<script>` tag.**

It looks like this (sandbox example):

```html
<script src="https://sandbox.pay.holest.com/clientpay/handlers/pos/07f689c5-5bc8-44b6-a563-8facc6870fab/frontend-script-core.js"></script>
```

The UID segment in the URL (`07f689c5-...`) is the Merchant Site UID — it is embedded in the URL itself.

**If the user confirms they need backend implementation** (admin actions, backend charges — see pre-build questions above), they must also provide:
- **Merchant Site UID** — visible in HPay panel ? Site Settings (also in the FrontCore script URL)
- **Merchant Site Secret Key** — visible in HPay panel ? Site Settings (keep this server-side only, never expose on frontend)

### ?? Configuration values must be easily changeable by the user

Store all three of these as **user-editable configuration** (environment variables, a settings screen, or a clearly marked config file) — **never hardcode them**:

| Value | Where used | Why it changes |
|---|---|---|
| FrontCore script `src` URL | Frontend, global `<script>` tag | Different URL for sandbox vs production, or when switching POS |
| Merchant Site UID | Backend charge requests, admin ops | Changes with sandbox ? production swap or different POS |
| Merchant Site Secret Key | Backend only (charges, admin, webhook verification) | Changes with sandbox ? production swap or different POS |

The most common user action after initial setup is **swapping sandbox ? production** — this should require changing only these three values and nothing else.

---

## Integration Steps

### Step 1 — Add the FrontCore Script

Add the user's script tag **once**, in a global location so it is available on all pages/views. This is important for payment methods like Apple Pay / Google Pay that can be triggered from a product listing page.

```html
<!-- Place in global layout, e.g. <head> or before </body> -->
<!-- USER PROVIDES THIS TAG — store src as a config value so sandbox?production swap is one edit -->
<script src="FRONTCORE_SCRIPT_URL_FROM_USER"></script>
```

When the HPay script is loaded, it also exposes these globals on `window`:
- `window.presentHPayPayForm` — function
- `window.HPayIsSandbox` — environment flag variable

Add a startup check to catch misconfiguration early:

```javascript
// After page load — warn developer if FrontCore failed to initialize
setTimeout(function() {
  if (typeof HolestPayCheckout === 'undefined') {
    console.error(
      'HolestPay FrontCore script did not load. ' +
      'Check that the current origin is listed in "Frontend Script-Core Origins" in the HPay panel.'
    );
  }
}, 5000);
```

---

### Step 2 — Initialize HPay and Load Payment/Shipping Methods

Call `HPayInit()` once when the checkout page loads (or when the user reaches it). It returns a Promise.

- `merchant_site_uid` and environment (`sandbox`/`production`) are **not** parameters — they come from the script URL automatically.
- Language is optional — if omitted, HPay uses the `<html lang="...">` attribute or the language set in HPay panel POS settings.

```javascript
// Save this after HPayInit so it can be used in charge_request and admin ops later
let hpayMerchantSiteUid = null;

HPayInit(/* language optional, e.g. 'en' */).then(async client => {
  hpayMerchantSiteUid = client.MerchantsiteUid;

  // Filter available methods by buyer's country (recommended)
  const country = 'RS'; // use actual buyer country, ISO 3166-1 alpha-2
  let availablePayment = [], availableShipping = [];
  try { availablePayment  = await HPay.availablePaymentMethods(country, orderAmount, orderCurrency); } catch(e) {}
  try { availableShipping = await HPay.availableShippingMethods(country, orderAmount, orderCurrency); } catch(e) {}

  // Populate payment method selector
  client.POS.payment.forEach(pm => {
    if (!pm.Hidden && (!availablePayment.length || availablePayment.find(m => m.Uid == pm.Uid))) {
      // Add pm to your UI selector
      // pm.HPaySiteMethodId ? use as pay_request.payment_method
      // pm.Name             ? display name (use this — do NOT invent a name)
      // pm.SubsciptionsType ? contains "cof" or "mit" ? card saving is supported for this method
      // pm.POps             ? e.g. "charge,refund" ? backend operations available
      // pm.PayInputUrl      ? if set, this method supports docking (embedded payment input)
      // pm['Use IFRAME']    ? if false, method uses redirect flow (bank page POST redirect)
    }
  });

  // Populate shipping method selector (if POS has shipping configured)
  if (client.POS.shipping) {
    client.POS.shipping.forEach(sm => {
      if (!sm.Hidden && (!availableShipping.length || availableShipping.find(m => m.Uid == sm.Uid))) {
        // sm.HPaySiteMethodId ? use as pay_request.shipping_method
        // sm.Name             ? display name
      }
    });
  }
});
```

> **Make sure existing payment methods in your UI have a name and description.** Use `pm.Name` from the POS config — do not hardcode or invent names.

---

### Step 3 — Build the `pay_request` and Initiate Payment

```javascript
const pay_request = {
  // NOTE: merchant_site_uid is NOT included here for FrontCore — the script handles auth automatically
  hpaylang: 'en',                                // optional
  order_uid: 'ORDER-20260425-001',               // required — technical unique order ID (maps to order.Uid)
  order_name: '#Order 204',                      // optional — order label (order.Name): shop order number, NOT product name — products go in order_items[].name
  order_amount: '15000.00',                         // required — string, in smallest currency unit or decimal
  order_currency: 'RSD',                         // required — ISO 4217
  payment_method: '179',                         // required — pm.HPaySiteMethodId from Step 2
  shipping_method: '45',                         // optional — sm.HPaySiteMethodId
  order_user_url: 'https://yoursite.com/thanks', // recommended — redirect/thank-you page URL
  notify_url: 'https://yoursite.com/webhook',    // optional — server-to-server webhook (must be publicly reachable)
  order_sitedata: {                              // optional — custom site metadata -> order.Data.sitedata (no order_data on pay_request; store API uses order_data for PBL)
    id: 204,
    customer_id: 1,
  },
  cof: 'optional',                               // optional — 'optional'|'required'|'none' — enables card saving
  vault_token_uid: '',                           // optional on pay_request: 'new'|1|true to save card; existing token for logged-in fast checkout (presentHPayPayForm) — NOT for server MIT; use /clientpay/charge for MIT
  order_billing: {                               // optional — maps to order.Data.billing on HPay order
    email: 'customer@example.com',
    first_name: 'TEST',
    last_name: 'TEST',
    phone: '+38111111111',
    is_company: 0,
    company: '',                                   // company legal name
    company_tax_id: '',                            // company tax ID in merchant's country
    company_reg_id: '',                            // company registration ID in merchant's country
    address: 'TEST',                                // street name
    address2: '',                                   // recommended for street number / address addition
    city: 'Beograd',
    country: 'RS',
    state: 'Beograd',
    postcode: '11000',
    lang: 'sr_RS'                                // language from merchant platform/system
  },
  order_shipping: {                              // optional — maps to order.Data.shipping on HPay order
    shippable: false,
    is_cod: 1,                                      // set to 1 when COD logic is used/allowed
    first_name: '',
    last_name: '',
    phone: '',
    company: '',
    address: '',                                    // street name
    address2: '',                                   // recommended for street number / address addition
    city: '',
    country: '',
    state: '',
    postcode: ''
  },
  order_items: [                                  // strongly recommended — maps to order.Data.items on HPay order
    {
      posuid: 114,                                           // merchant's own internal item ID (string or number)
      type: 'product',
      name: 'Sample product name',
      sku: '000550',
      qty: 1,
      price: 4695.99,
      subtotal: 4695.99,
      tax_label: '',
      tax_amount: 0,
      length: '',                                          // always in centimeters (cm)
      width: '',                                           // always in centimeters (cm)
      height: '',                                          // always in centimeters (cm)
      weight: '',                                          // always in grams (g)
      split_pay_uid: '',
      virtual: true,
      tax_percent: 0
    }
  ]
};

// Remove empty fields before sending
Object.keys(pay_request).forEach(k => { if (pay_request[k] === '') delete pay_request[k]; });

// Initiate payment — shows modal or triggers redirect depending on payment method
HPay.presentHPayPayForm(pay_request);
```

**Important — `order_items` field naming must match HolestPay template keys:**

- Use `name`, not `title`
- Use `posuid`, not `variantId`
- Use `qty`, not `quantity`
- `subtotal` is mandatory for each item line
- `posuid` can be any identifier from the merchant's system (SKU/variant/product/internal DB ID)
- **Product name / title** → `order_items[].name` (→ `order.Data.items[].name`). **Do not** put product names in `order_name` — that field is the **order** label (`order.Name`), e.g. `#Order 204`.

If source platform fields are Shopify-style, map them explicitly before sending:
- `variantId -> posuid`
- `title -> name`
- `quantity -> qty`
- top-level `items -> order_items`

The same order payload structure is used across all three markups/docs (Lovable prompt, FrontCore guide, Standard guide).
Address convention recommendation: use `address` for street name and `address2` for street number/additional address details.

### Request/response vs HolestPay order object — key mapping

`pay_request` / `charge_request` / `hpay_response` use **different field names** than the HolestPay order object (`getOrder`, webhook `order`, admin API). Do not copy request keys onto the order root.

| Request/response field | HolestPay order object path | Notes |
|---|---|---|
| `order_uid` | `Uid` | Technical unique order ID — signatures, webhooks, `/clientpay/charge` |
| `order_name` | `Name` | **Order** label (e.g. `#Order 204`) — **not** product name; products use `order_items[].name` → `Data.items[].name` |
| `order_amount` | `Amount` | |
| `order_currency` | `Currency` | |
| `order_sitedata` | `Data.sitedata` | Custom site metadata (e.g. platform order id, customer_id) — **not** `order_data` |
| **`order_items`** | **`Data.items`** | Line items array — **not** `order.Items` at root |
| **`order_billing`** | **`Data.billing`** | Billing address/contact — **not** `order.Billing` at root |
| **`order_shipping`** | **`Data.shipping`** | Shipping address/contact — **not** `order.Shipping` at root |

When reading `HPay.getOrder(...)` or webhook `order`, access billing/items/shipping/sitedata as `ord.Data.billing`, `ord.Data.items`, `ord.Data.shipping`, `ord.Data.sitedata`. When sending **checkout** `pay_request`, use top-level `order_billing`, `order_items`, `order_shipping`, `order_sitedata`. **There is no `order_data` field on checkout `pay_request`.** (For server **`POST /clientpay/store`**, optional `order_data` → top-level `order.Data` for Pay-By-Link; see **Store Order API**.)

Set `order_name` from your **shop order number** (what buyers see as "your order #204"). **Do not** put a product name, item title, or catalog description in `order_name` — that belongs in `order_items[].name` for each line item.

---

### Step 4 — Docking (Embedded Payment Input)

Some payment methods support an embedded payment input directly in the page (e.g. card form inline). Check `pm.PayInputUrl` — if it is set, docking is supported for that method.

Call `HPay.setPaymentMethodDock()` **when the user selects a payment method or when any checkout field changes** (amount, currency, etc.).

```html
<!-- Place dock container below payment method description in your checkout UI -->
<div id="paymentMethodDock" style="max-width:460px;"></div>
```

```css
#paymentMethodDock { background: #ffffff9e; }
```

```javascript
function updateDock() {
  const selectedPm = /* pm object for selected payment method */;
  if (selectedPm && selectedPm.PayInputUrl) {
    HPay.setPaymentMethodDock(
      pay_request.payment_method,
      {
        order_amount:         pay_request.order_amount,
        order_currency:       pay_request.order_currency,
        monthly_installments: null,
        vault_token_uid:      pay_request.vault_token_uid || null,
        hpaylang:             pay_request.hpaylang,
        cof:                  pay_request.cof
      },
      document.getElementById('paymentMethodDock')
    );
  } else {
    document.getElementById('paymentMethodDock').innerHTML = '';
  }
}
```

---

### Step 5 — Handle Results

#### A — Event handler (iframe / modal methods)

Most payment methods return the result via this event, fired on the current page:

```javascript
document.addEventListener('onHPayResult', function(e) {
  const r = e.hpay_response;
  if (!r) return;

  if (r.error && r.error.code) {
    // Payment error — retry
    HPay.presentHPayPayForm(pay_request);
    return;
  }

  if (/PAID|RESERVED|SUCCESS|PAYING|OBLIGATED|AWAITING/i.test(r.payment_status)) {
    // Payment completed or pending payment instructions (AWAITING/OBLIGATED are NOT failed)
    // Clear cart for PAID/RESERVED and also for PAYING/AWAITING/OBLIGATED.

    // Display HTML receipts in dedicated containers on your thank-you page:
    // r.payment_html  ? payment receipt HTML
    // r.fiscal_html   ? fiscal receipt HTML (if fiscal module active)
    // r.integr_html   ? integration module HTML
    // r.shipping_html ? shipping label/receipt HTML (if shipping module active)
    // r.transaction_user_info ? object with card brand, masked number, etc.

    if (r.vault_token_uid) {//only if card save is on for some reason subscription or simply token save for faster checkout
      // IMPORTANT: save this to your database linked to the user account — do NOT only store in browser
      const saveCardData = {
        vault_token_uid:   r.vault_token_uid,    //e.g. hJ0khUi67856765rtyrytrytry 12 up to 128 characters
        vault_card_brand:  r.vault_card_brand,   // e.g. "MASTERCARD"
        vault_card_umask:  r.vault_card_umask,   // e.g. "544358******4639"
        vault_exp:         r.vault_exp,          // e.g. "12/26"
        vault_scope:       r.vault_scope,        // terminal/routing scope — which terminals token can be used on
        vault_onlyforuser: r.vault_onlyforuser,  // 1 = presentHPayPayForm only; 0 = presentHPayPayForm and /clientpay/charge — subscriptions need 0
        pay_method_uid:    r.pay_method_uid      //Uid of payment method from HPay.POS.payment[N].Uid
      };
      // POST saveCardData to your backend
    }

    // Redirect to thank-you page if needed:
    // window.location.href = r.order_user_url;
  }

  // r.status ? order status (always present)
});

document.addEventListener('onHPayPanelClose', function(e) {
  const r = e.hpay_response; // null if user closed without completing
  const reason = String((r && r.reason) || '').toLowerCase();

  // If pay button was locked during payment start, unlock it on close reasons below.
  if (/^(user|timeout|cancel|error)$/.test(reason)) {
    const payBtn = document.getElementById('do-pay');
    if (payBtn) payBtn.disabled = false;
  }

  if (r && r.reason === '' && /* user wants retry */ false) {
    setTimeout(() => HPay.presentHPayPayForm(pay_request), 300);
  }
});
```

#### B — POST-back redirect (redirect methods)

Some payment methods (e.g. certain bank integrations) require a **full page redirect to the bank**. `HPay.presentHPayPayForm()` handles this automatically with a POST redirect. After the bank interaction, the user is returned to `order_user_url` via a POST-back.

On `order_user_url` (your thank-you/return page), read the result from the POST body:

```javascript
// Server-side (Node.js example)
// The POST body contains: hpay_forwarded_payment_response = JSON string
const result = JSON.parse(req.body.hpay_forwarded_payment_response);
// result is the same structure as e.hpay_response from onHPayResult
```

> Implement **both** the event handler (Step 5A) and the POST-back handler (Step 5B). Which one fires depends on the payment method the buyer chooses — you cannot predict it at build time.

#### C — Webhook topics, panel URL, and `notify_url` override

If server-to-server notifications are needed, configure panel setting:
- `I(P|S|F|I)N - Link za instant notifikacije - plaćanje/isporuka/fiskal/integracije`
- `I(P|S|F|I)N - Instant payment/shipping/fiscal/integation notification url`

If request payload includes `notify_url`, it overrides panel-level `I(P|S|F|I)N` URL for that request.

HPay appends query string parameter `topic` and sends POST JSON.

`topic` can be:
- `payresult` — same shape as `onHPayResult` / `https://apps.holest.com/holest-pay/response_sample.json`
- `orderupdate` — root includes `order_uid`, `status`, `vhash`; payload fields are the same as `payresult`; and has `order` property with HolestPay order object in the same format as `ord` from `HPay.getOrder(order_uid).then(ord => {...})` (`https://apps.holest.com/holest-pay/hpay_order_sample.json`) (`"id"` is ID from HPay system); validate `vhash` the same way as `payresult`
- `posconfig-updated` — contains POS object (`HPay.POS` format plus non-public fields), `environment`, and `checkstr = md5(${merchant_site_uid}${secret_token})`

Important payload mapping note:
- Request and response payloads are similar in shape; response usually contains request fields plus normalization and additional result fields.
- Hash field names are different by direction: request -> `verificationhash`, response -> `vhash`.
- `order` payload is a different model (same as `HPay.getOrder(...)` `ord` object), so do not map it as request/response.
- Example key differences (request/response field → HolestPay order object):
  - `order_uid` → `Uid`
  - `order_name` → `Name` (**order** label / shop order number — **not** product name; use `order_items[].name` for products)
  - `order_amount` → `Amount`
  - `order_currency` → `Currency`
  - **`order_sitedata` → `Data.sitedata`** (custom site metadata — no `order_data` on checkout `pay_request`; see Store API for PBL `order_data`)
  - **`order_items` → `Data.items`** (line items array — nested under `Data`, not at order root)
  - **`order_billing` → `Data.billing`** (billing address/contact — nested under `Data`, not at order root)
  - **`order_shipping` → `Data.shipping`** (shipping address/contact — nested under `Data`, not at order root)
  - fiscal method specific data -> `order.FiscalData[fiscal_method_uid] = {...}` (module-specific payload)
  - integration method data -> `order.Data[integr_method_uid] = {...}` (may exist or may be empty/missing)
  - shipping method data -> `order.ShippingData[real_or_temp_shipping_code] = { method_uid: shipping_method_uid, ... }`

The same result may arrive from browser callback and webhook; use `vhash` (plus order/transaction IDs) to prevent duplicate processing.

#### D — Redirect POST-back parse robustness

For redirect methods, HPay can return result via:

```html
<form method='POST' id='frmRedirect' action='${order_user_url}'>
  <input type='hidden' name='hpay_forwarded_payment_response' id='hpay_response' />
</form>
<script nonce='${csp_nonce}'>
  document.getElementById('hpay_response').value = JSON.stringify(hpay_result);
  document.getElementById('frmRedirect').submit();
</script>
```

If `JSON.parse` fails on first try, normalize escaped payload and retry:

```javascript
function parseForwardedHPayResponse(raw) {
  if (!raw) return null;
  if (typeof raw === 'object') return raw;
  try { return JSON.parse(raw); } catch (_) {}
  const unescaped = String(raw).replace(/\\\\\"/g, '"').replace(/\\\\\\\\/g, '\\');
  try { return JSON.parse(unescaped); } catch (_) {}
  return null;
}
```

---

### Step 6 — Display HTML Receipts on Thank-You Page

On the thank-you page, always render data in this order:
1) `transaction_user_info` block first  
2) `payment_html`, `fiscal_html`, `shipping_html`, `integr_html` blocks

For bank production approval, thank-you page must also show complete order summary for all outcomes (success, failed, awaiting payment):
- buyer/customer identity data
- billing and email data
- shipping data
- order number
- ordered products list with quantity, unit price, and line totals
- shipping cost
- payment method name and shipping method name
- grand total amount

If any field is missing in response, keep the block visible and show a placeholder message.

Create containers for transaction details and each receipt type:

```html
<div id="hpay-transaction-user-info"></div> <!-- translated keys, original values -->
<div id="hpay-receipt-payment"></div>  <!-- payment receipt -->
<div id="hpay-receipt-fiscal"></div>   <!-- fiscal receipt (white background recommended for legibility) -->
<div id="hpay-receipt-integr"></div>   <!-- integration module output -->
<div id="hpay-receipt-shipping"></div> <!-- shipping label / receipt -->
```

```javascript
function renderTransactionUserInfo(info, keyMap) {
  const host = document.getElementById('hpay-transaction-user-info');
  if (!host) return;
  host.innerHTML = '';
  if (!info || typeof info !== 'object' || !Object.keys(info).length) {
    host.innerHTML = '<p class="hpay-placeholder">Transaction details are not available.</p>';
    return;
  }
  const dl = document.createElement('dl');
  Object.entries(info).forEach(([k, v]) => {
    const dt = document.createElement('dt');
    const dd = document.createElement('dd');
    dt.textContent = keyMap[k] || k;  // keys can be translated
    dd.textContent = String(v ?? ''); // values must stay original
    dl.appendChild(dt);
    dl.appendChild(dd);
  });
  host.appendChild(dl);
}

renderTransactionUserInfo(r.transaction_user_info, {
  'Order UID': 'Order UID',
  'Payment Status': 'Payment Status',
  'Transaction Time': 'Transaction Time',
  'Amount in order currency': 'Amount in order currency',
  'Amount in payment currency': 'Amount in payment currency',
  'Bank Account': 'Bank Account',
  'REF MOD97 PNB': 'REF MOD97 PNB',
  'Purphose': 'Purpose'
});

const FALLBACK_HTML = '<p class="hpay-placeholder">Not available for this payment.</p>';
document.getElementById('hpay-receipt-payment').innerHTML  = r.payment_html  || FALLBACK_HTML;
document.getElementById('hpay-receipt-fiscal').innerHTML   = r.fiscal_html   || FALLBACK_HTML;
document.getElementById('hpay-receipt-shipping').innerHTML = r.shipping_html || FALLBACK_HTML;
document.getElementById('hpay-receipt-integr').innerHTML   = r.integr_html   || FALLBACK_HTML;
```

Example `transaction_user_info` payload:

```json
{
  "transaction_user_info": {
    "Order UID": "NIPI-1777290504591-8X6YD2",
    "Payment Status": "AWAITING",
    "Transaction Time": "2026-04-27 13:48:27.847Z",
    "Amount in order currency": "1360.00 RSD",
    "Amount in payment currency": "1360.00 RSD",
    "Bank Account": "160-6000002552312-02",
    "REF MOD97 PNB": "(97) 2726042713",
    "Purphose": "Order npinipi17772905045918x6yd2"
  }
}
```

Rule: keys may be translated for UI labels, but values should be displayed exactly as received. If any section is missing, render a visible placeholder instead of hiding the section.

For `AWAITING` and `OBLIGATED`, always render `payment_html` on the thank-you page. These are not failed statuses; they are commonly used for account/invoice payment instructions (bank transfer details).
Cart handling rule: clear cart for `PAID`, `RESERVED`, `PAYING`, `AWAITING`, and `OBLIGATED` (same cart behavior for all these statuses).

---

### Step 7 — Verify Response `vhash` on Server (Node.js)

Important naming:
- request to HPay (`pay_request` / `charge_request`) -> field `verificationhash` -> generate with `generatePOSRequestSignature(...)`
- response from HPay (browser callback / webhook) -> field `vhash` -> validate with `verifyHPayResponse(...)`

Always verify response `vhash` server-side before marking order as paid/fulfilled.

```javascript
const crypto = require('crypto');
const md5 = require('md5');

function generatePOSRequestSignature(merchant_site_uid, secretKey, payload) {
  const amount = Number(payload.order_amount ?? 0).toFixed(8);
  const src =
    String(payload.transaction_uid ?? '').trim() + '|' +
    String(payload.status ?? '').trim() + '|' +
    String(payload.order_uid ?? '').trim() + '|' +
    amount + '|' +
    String(payload.order_currency ?? '').trim() + '|' +
    String(payload.vault_token_uid ?? '').trim() + '|' +
    String(payload.subscription_uid ?? '').trim() +
    String(payload.rand ?? '').trim();

  const srcMd5 = md5(src + merchant_site_uid);
  return crypto.createHash('sha512').update(srcMd5 + secretKey).digest('hex').toLowerCase();
}

function verifyHPayResponse(result, merchant_site_uid, secretKey) {
  if (!result || !result.vhash) return false;
  if (!result.order_uid || !String(result.order_uid).trim()) return false;

  const expected = generatePOSRequestSignature(merchant_site_uid, secretKey, {
    transaction_uid: result.transaction_uid ?? '',
    status: result.status ?? '',
    order_uid: result.order_uid,
    order_amount: result.order_amount ?? 0,
    order_currency: result.order_currency ?? '',
    vault_token_uid: result.vault_token_uid ?? '',
    subscription_uid: result.subscription_uid ?? '',
    rand: result.rand ?? ''
  });

  return expected === String(result.vhash).toLowerCase();
}
```

---

## Optional — Advanced: Backend Charges (Server-Server MIT) — `/clientpay/charge`

> **Skip this section** unless the user explicitly asked for subscriptions, automatic recurring charges, or merchant-initiated billing. The standard checkout flow (Steps 1–6) is completely independent of this.

### Critical: `presentHPayPayForm(pay_request)` vs `/clientpay/charge` — do not confuse

Both can use a saved `vault_token_uid`, but they are **different flows**:

| | **`presentHPayPayForm(pay_request)`** (CIT / buyer checkout) | **`/clientpay/charge`** (MIT / server-server) |
|---|--------------------------------------------------------------|-----------------------------------------------|
| **Who initiates** | Buyer at checkout | Your server — cron renewal, merchant admin |
| **Buyer present** | Yes — HPay UI opens from `presentHPayPayForm` | No — silent, no card form |
| **`vault_token_uid`** | Optional on `pay_request` | **Required** on `charge_request` |
| **Use existing token when** | Logged-in buyer **selects** a saved `user_vault_token` at checkout for faster payment | Server charges token from DB without buyer |
| **Do not use for MIT** | — | This is the correct path for MIT |

**Wrong pattern (common mistake):** cron / admin renewal calling **`presentHPayPayForm(pay_request)`** with `vault_token_uid`.  
**Correct pattern:** server POST to **`/clientpay/charge`** with body `{ request_data: charge_request }`.

### What server-server charge is

Lets your **server** charge a saved card with **no buyer interaction** — used for:
- Recurring subscription billing (cron)
- MIT — merchant-initiated charge from admin

### Prerequisites

- Payment method with `pm.SubsciptionsType` containing `"cof"` or `"mit"`
- `pm.POps` contains `"charge"`
- `vault_token_uid` in your DB (`user_vault_token`) from a prior successful payment
- **Merchant Site UID** + **Secret Key** on server only
- MIT renewals need a bank that supports MIT; manual merchant charges can still use `/clientpay/charge` where supported

### How the token gets saved (CIT via `presentHPayPayForm` — not `/clientpay/charge`)

First payment / card save uses **`presentHPayPayForm(pay_request)`** (buyer checkout), not `/clientpay/charge`:

```javascript
vault_token_uid: 'new'   // save new card
// OR logged-in buyer picked saved card at checkout:
vault_token_uid: 'existing-token-uuid'   // still presentHPayPayForm (CIT), not MIT
```

After success, persist `vault_*` fields (example):

> **`vault_token_uid`** is reused in two ways:  
> - **`presentHPayPayForm(pay_request)`** — logged-in buyer selects a saved `user_vault_token` at checkout (user/site-initiated CIT; buyer present).  
> - **`/clientpay/charge`** — server-server MIT only (cron renewal, merchant admin); only `vault_token_uid` is required in `charge_request`.  
> **Store all `vault_*` fields** in `user_vault_token` — `vault_card_brand`, `vault_card_umask`, and `vault_exp` let the buyer recognize the card and let you show/warn about expiry; `vault_scope` and `vault_onlyforuser` help scope and manage tokens.

> **`vault_onlyforuser`:** `1` = token usable only with **`presentHPayPayForm`** (logged-in saved-card checkout); `0` = usable with **`presentHPayPayForm`** and **`/clientpay/charge`** (server MIT). For subscriptions / renewal charges, persist tokens with `0`.
> **`vault_scope`:** e.g. `"13IN002780"` — useful when you use **many payment methods and routing**; indicates **which terminal(s)** the token can be applied on. Store it with the token and match `payment_method` / terminal when reusing in `pay_request` or `charge_request`.

```javascript
{
  "vault_token_uid": "Ij0BZTRhgkuhDG2nqSg8IQ", // reuse in pay_request (presentHPayPayForm) or charge_request (/clientpay/charge, e.g. subscription renewal)
  "vault_card_brand": "VISA",                   // store — card identification in account UI
  "vault_card_umask": "432484***0474",          // store — masked PAN for buyer
  "vault_exp": "10/27",                         // store — expiry display / warnings
  "vault_scope": "13IN002780",                  // store — terminal/routing scope; which terminals token applies to
  "vault_onlyforuser": 0                        // 1 = presentHPayPayForm only; 0 = presentHPayPayForm and /clientpay/charge — subscriptions need 0
}
```

### Server-server charge request (Node.js)

Same signature function as `pay_request`. **Wrap body as `{ request_data: charge_request }`.**

```javascript
// SERVER-SIDE ONLY
const crypto = require('crypto');
const md5    = require('md5');

function generatePOSRequestSignature(merchant_site_uid, secretKey, request) {
  const amt = parseFloat(request.order_amount || 0).toFixed(8);
  let cstr  = [request.transaction_uid, request.status, request.order_uid,
               amt, request.order_currency, request.vault_token_uid,
               request.subscription_uid].map(v => String(v || '').trim()).join('|');
  cstr     += String(request.rand || '').trim();
  return crypto.createHash('sha512')
    .update(md5(cstr + merchant_site_uid) + secretKey)
    .digest('hex').toLowerCase();
}

const MERCHANT_SITE_UID = 'YOUR-MERCHANT-SITE-UID';
const SECRET_KEY        = 'YOUR-POS-SECRET-KEY';
const BASE_URL          = 'https://sandbox.pay.holest.com'; // or https://pay.holest.com

const charge_request = {
  merchant_site_uid: MERCHANT_SITE_UID,
  hpaylang:          'en',
  order_uid:         '20260823-519442',       // technical ID (order.Uid)
  order_name:        '#Order 18',             // order label (order.Name) — order number, NOT product name
  order_amount:      '15000',
  order_currency:    'RSD',
  payment_method:    '841',
  vault_token_uid:   'Ij0BZTRhgkuhDG2nqSg8IQ', // from user_vault_token — /clientpay/charge (server MIT, e.g. subscription renewal) only; not presentHPayPayForm
  // same optional fields as pay_request (billing, shipping, items, notify_url, etc.)
  // omit order_user_url: no user exists to be redirected in backend charge flow
  // omit cof: not applicable for backend charge
};

charge_request.verificationhash = generatePOSRequestSignature(
  MERCHANT_SITE_UID, SECRET_KEY, charge_request
);

const result = await fetch(BASE_URL + '/clientpay/charge', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body:    JSON.stringify({ request_data: charge_request }),
}).then(r => r.json());

// Verify result vhash before fulfilling (verifyHPayResponse)
if (/PAID|PAYING|RESERVED|OBLIGATED|AWAITING/i.test(result.payment_status)) {
  // charge succeeded
}
```

---

## Subscriptions Integration Recommendations

Ask the user whether they want subscriptions before implementing any of this. If they decline, skip this section entirely.

### Bank / MIT prerequisite

- Automatic renewal charges (MIT) require a **merchant account at a bank that supports MIT**.
- Subscriptions can still be charged **manually** (operator-triggered charge) even without MIT support.
- Only payment methods where `pm.SubsciptionsType` contains `"cof"` or `"mit"` and `pm.POps` contains `"charge"` support this flow.
- FrontCore checkout itself does not need the Secret Key, but **every MIT / backend charge still requires the Secret Key on your server**.

### Terms of Service

If subscriptions are offered, the site Terms of Service / purchase conditions **must** state that this option exists and describe, from the **buyer's perspective**, what they can expect (e.g. how renewals work, how to cancel, how saved cards are used, when charges happen).

### First payment (CIT) — create or reuse a vault token via `presentHPayPayForm`

For the initial customer-initiated (CIT) subscription payment, use **`presentHPayPayForm(pay_request)`** (buyer checkout), not `/clientpay/charge`. Set in `pay_request`:

```javascript
vault_token_uid: 'new'   // save a new card token
// OR, if the buyer already has a saved card from a previous checkout:
vault_token_uid: 'existing-token-uuid'   // logged-in buyer picked user_vault_token — still presentHPayPayForm (CIT), not MIT
```

Renewals and merchant-initiated billing use **`/clientpay/charge`** (see Backend Charges section above).

### Successful CIT response — vault fields to persist

After a successful CIT payment, the response typically includes the `vault_*` fields shown above. Persist them immediately. The same **`vault_token_uid`** is passed again in **`pay_request`** for **`presentHPayPayForm`** when the logged-in user picks that saved card, or in **`charge_request`** for **`/clientpay/charge`** (server MIT — only field required there).

### Data model — `user_vault_token` and subscription reference

- Persist all `vault_*` fields in a structure such as `user_vault_token`, keyed to the customer, together with the payment method identifier (`payment_method` / `pay_method_uid`).
- A customer may have **multiple** `user_vault_token` records.
- The **subscription** object should store a **reference** to the specific `user_vault_token` used for that subscription.
- If an MIT charge fails and the customer has multiple tokens, try them **in order** until a `charge_request` succeeds.
- The customer should be able to:
  - choose a **default** vault token when they have more than one;
  - **remove** a vault token if they no longer want that card charged;
  - choose, **per subscription**, which of their `user_vault_token`s to use (when they have multiple tokens and/or multiple subscriptions).

### Card-save only (amount `0`)

A CIT payment with `order_amount: "0"` and `vault_token_uid: 'new'` may be used to **save a new card without charging**. This zero-amount save applies only when the request has `vault_token_uid: 'new'`.

### Site-owned renewals — do not rely on HolestPay `subscription_uid`

This recommended implementation **does not** use the HolestPay subscription object (`subscription_uid`). HolestPay will **not** create renewals by itself. The site only uses `vault_token_uid` to perform charges.

Your site must implement:

1. Logic that checks whether it is time to renew.
2. Creation of a renewal order (or equivalent renewal object with a unique identifier).
3. Building a `charge_request` from that renewal and calling the backend charge endpoint (server-side, with Secret Key).

### Fiscalization with subscription renewals

If HolestPay fiscalization is used with subscriptions, successful responses will simply include fiscal receipt data when fiscal receipts are configured to be created automatically. The system should still listen to webhook `orderupdate` for renewals, because fiscal receipts may be created later (fiscal temporarily unavailable, or the merchant configured fiscal printing on click instead of automatic).

---

## Optional: Shipping Address Autocomplete (AdaptCheckout)

If the user uses HolestPay shipping modules, some methods provide address autocomplete/suggestion UI. Call `adaptCurrentShipping()` whenever the selected shipping method changes. Pass `null` to destroy the adapter when no shipping method is selected.

The selector strings map your existing checkout input fields to HolestPay's address model — **update them to match your actual input selectors**.

```javascript
let adapted_checkout_destroy    = null;
let adapted_shipping_method_uid = null;

function adaptCurrentShipping(shipping_method_uid) {
  try {
    if (shipping_method_uid) {
      if (shipping_method_uid === adapted_shipping_method_uid) return;
      const smethod = HPay.POS.shipping.find(s => s.Uid == shipping_method_uid);
      if (smethod && smethod.AdaptCheckout) {
        adapted_checkout_destroy = smethod.AdaptCheckout({
          billing: {
            address:         "#addressInput[name='address1']",       // update selectors to match your inputs
            address_num:     "#addressLine2Input[name='address2']",
            postcode:        "#postCodeInput[name='postalCode']",
            city:            "#cityInput[name='city']",
            municipality:    "#provinceInput[name='stateOrProvince']",
            phone:           "#phoneInput[name='phone']",
            country:         "#countryCodeInput[name='countryCode']",
            is_company:      "#companyInput[name='company']",
            company:         "#companyInput[name='company']",
            company_tax_id:  "",
            company_reg_id:  ""
          },
          shipping: {
            address:         "#addressInput[name='shippingAddress.address1']",
            address_num:     "#addressLine2Input[name='shippingAddress.address2']",
            postcode:        "#postCodeInput[name='shippingAddress.postalCode']",
            city:            "#cityInput[name='shippingAddress.city']",
            municipality:    "#provinceInput[name='shippingAddress.stateOrProvince']",
            phone:           "#phoneInput[name='shippingAddress.phone']",
            country:         "#countryCodeInput[name='shippingAddress.countryCode']",
            is_company:      "#companyInput[name='shippingAddress.company']",
            company:         "#companyInput[name='shippingAddress.company']",
            company_tax_id:  "",
            company_reg_id:  ""
          }
        }) || null;
        adapted_shipping_method_uid = shipping_method_uid;
      }
    } else {
      if (adapted_checkout_destroy) {
        adapted_checkout_destroy();
        adapted_checkout_destroy = null;
        adapted_shipping_method_uid = null;
      }
    }
  } catch(ex) { console.error(ex); }
}
```

---

## No Backend Needed for Basic Checkout

If the site runs on Shopify, BigCommerce, or any platform where you cannot run custom server code, the FrontCore flow (Steps 1–6) is fully self-contained — no backend is required for standard checkout. Backend code is only needed if you implement:
- **Backend charges** (subscription / MIT auto-charge)
- **Admin operations** (refunds, captures, etc.)
- **Admin Order REST API** (list / get / update HolestPay orders from your admin backend)
- **Payment / module handlers** (`queryRequest`, void, refund, capture, fiscal/shipping/integration methods)
- **Webhook verification** (verify response `vhash` from `notify_url` payload)

For webhooks and backend operations you also need the **Merchant Site Secret Key** (from HPay panel ? Site Settings).

---

## Optional — Advanced: Admin Order REST API (Site Admin Backend)

> **Skip this section** unless the user has a custom backend / admin area and needs to list, load, or update HolestPay orders from the server. Not needed for basic FrontCore checkout. Never call these endpoints from the browser.

Reference sample: `hpay_orders_api_sample_nodejs.js`

Use this for the **administrative part of the merchant site** (order list, order detail, editing order fields). Requires **Merchant Site UID** + **POS Secret Key** on the server. Signature algorithm is the same as backend charge / `generatePOSRequestSignature`. Auth goes in HTTP headers: `rand` + `verificationhash`.

HolestPay can also render a full admin UI via `orderActions`; manual REST and **Payment / Module Backend Handlers** (`queryRequest`, void, refund, capture, …) are still commonly needed for custom admin backends. See `hpay_payment_queryRequest_sample_nodejs.js`.

**Interactive handbook (try live calls):** https://apps.holest.com/holest-pay/hpay_common_backend_api_calls.html — enter POS credentials, try `store` / Pay-By-Link preview / orders + payment handler calls and inspect METHOD, URL, headers, body, and response (PHP / Node.js / C# tabs).

Order object format is the HolestPay order model (same as webhook `orderupdate.order` / `HPay.getOrder`), sample: `https://apps.holest.com/holest-pay/hpay_order_sample.json` — not the `pay_request` / `hpay_response` field names.

### Endpoints

Base: `https://sandbox.pay.holest.com` or `https://pay.holest.com`

**1) List orders — `getOrders`**

```
GET /clientpay/orders/{merchant_site_uid}?offset=0&limit=50&filter={...}&sort_order={...}
Headers: rand, verificationhash
```

`filter` / `sort_order` match HolestPay admin UI format, e.g.:

```javascript
// filter={"CreatedAt":{"op":"between","value":["2026-05-03T00:00:00","2026-08-10T23:59:59"]}}
// sort_order=[["id","DESC"]]
const filter = {
  CreatedAt: { op: 'between', value: [fromLocalDateTime, toLocalDateTime] },
};
const sort_order = [['id', 'DESC']];
```

Response may be a bare array or wrapped under `items` / `Orders` / `orders` / `data` / `result` / `Results`. Prefer `Uid` on each order.

**2) Get one order — `getOrder`**

```
GET /clientpay/orders/{merchant_site_uid}/{order_uid}
Headers: rand, verificationhash
Sign fields: { order_uid }
```

**3) Update order — `updateOrder`**

```
POST /clientpay/orders/{merchant_site_uid}/{order_uid}/update
Headers: rand, verificationhash, Content-Type: application/json
Sign fields: { order_uid }
Body: { "Order": { /* partial order fields */ } }
```

Example:

```javascript
const updateBody = {
  Order: {
    Data: {
      billing: { note: 'Updated via API' },
    },
  },
};
```

### Signature headers (same as charge)

```javascript
function hpaySign(fields, merchantSiteUid, secretToken) {
  const amount = Number(fields.order_amount != null ? fields.order_amount : 0).toFixed(8);
  const src =
    String(fields.transaction_uid || '').trim() + '|' +
    String(fields.status || '').trim() + '|' +
    String(fields.order_uid || '').trim() + '|' +
    amount + '|' +
    String(fields.order_currency || '').trim() + '|' +
    String(fields.vault_token_uid || '').trim() + '|' +
    String(fields.subscription_uid || '').trim() +
    String(fields.rand || '').trim();
  const md5 = crypto.createHash('md5').update(src + merchantSiteUid, 'utf8').digest('hex');
  return crypto.createHash('sha512').update(md5 + secretToken, 'utf8').digest('hex').toLowerCase();
}
```

For list calls, signed fields may be empty except `rand`. For get/update, include `order_uid` in signed fields.

### vs browser admin toolbox / manual handlers

HolestPay can **easily render a full admin interface** for order detail or order list (`orderActions` after normal `hpay.js` + secret). Integrators **often still need manual server-to-server calls** (custom admin, cron, bank sync).

- REST API above → your server order list / detail / field edits
- `HPayInit(..., secret_key)` + `orderActions` on normal `hpay.js` (not FrontCore) → ready-made refund / fiscal / shipping UI
- **`POST /clientpay/store`** below → orders not paid via HPay checkout that still need fiscal / shipping / integration / Pay-By-Link
- **Payment / module handlers** below → `queryRequest`, void, refund, capture, and the same pattern for fiscal/integration/shipping

---

## Optional — Advanced: Store Order API (`POST /clientpay/store`) + Pay-By-Link

> **Skip unless** the user needs HolestPay fiscal / integration / shipping (or a Pay-By-Link) on orders that were **not** created through an HPay payment method on the frontend. Server-side only (Secret Key). Never call from the browser.

After create/update via `/store`, the order exists in HolestPay like any other — full **admin rendering** (`orderActions`) and module handlers such as **`defaultAction`**.

Reference sample: `hpay_store_order_sample_nodejs.js`  
Interactive try: https://apps.holest.com/holest-pay/hpay_common_backend_api_calls.html (`store` panel + Pay-By-Link checkbox / URL preview)

```
POST /clientpay/store
Body: { "request_data": { /* full order fields + rand + verificationhash */ } }
```

- **Creates** when `order_uid` is new; **updates** when it already exists.
- Signature lives **inside** `request_data` (same algorithm as charge). Include `order_uid`, `order_amount`, `order_currency`, `rand`.
- Typical fields: `merchant_site_uid`, `order_uid`, `order_name`, `order_amount`, `order_currency`, `payment_method`, `shipping_method`, `order_items`, `order_billing`, `order_shipping`, `order_sitedata`, optional `order_data`.
- Externally paid / unpaid-via-HPay samples often use `payment_method: '0'` and `shipping_method: '0'` until HPay modules are applied.
- **Note:** checkout `pay_request` uses `order_sitedata` → `order.Data.sitedata`. On `/store`, optional **`order_data`** merges into **`order.Data`** (Pay-By-Link flags). Do not confuse the two.

```javascript
const requestData = {
  merchant_site_uid: MERCHANT_SITE_UID,
  order_uid: 'API-STORE-...',
  order_name: '#API-STORE-...',
  order_amount: '1500.00',
  order_currency: 'RSD',
  payment_method: '0',
  shipping_method: '0',
  order_items: [ /* ... */ ],
  order_billing: { /* ... */ },
  order_shipping: { /* ... */ },
  order_sitedata: { id: '...', payment_method_id: 'external' },
  // optional Pay-By-Link:
  // order_data: { is_pbl: 1, pbl_offer_days: 7, allow_pm: [...], allow_sm: [...], pbl_sms: 0 },
};
requestData.verificationhash = generatePOSRequestSignature(MERCHANT_SITE_UID, SECRET_KEY, requestData);
await fetch(BASE_URL + '/clientpay/store', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ request_data: requestData }),
});
```

### Pay-By-Link (optional)

Works for a newly stored order or an **existing** one (store/update with PBL fields). Set under **`order_data`** → HolestPay **`order.Data`**:

```javascript
order_data: {
  is_pbl: 1,
  pbl_offer_days: 7, // required for P-B-L - link validity in days
  allow_pm: [ /* optional payment method UIDs; omit = all */ ],
  allow_sm: [ /* optional shipping method UIDs; omit = all */ ],
  pbl_sms: 0,        // optional 1|0 — SMS for Serbian mobiles only
}
```

Example `allow_pm` UIDs (omit the list to allow all): `nbsipspt_rs`, `upc_redirect`, `nestpay_redirect`, `nestpay_3d_mit`, `nestpay_redirect_halk`, `cpay_redirect`, `method_udev`, `cardbinrouter`, `manual`, `raiaccept_redirect`, `ipgtas_redirect`, `sia_redirect`, `nbs_ips_skeniraj_pt`, `quipu_redirect`, `banktransferrs-2`, `sia_api`.

### Pay-By-Link URL

Same as `HPay.getPayByLinkForOrderUid(order_uid)`:

```javascript
function addChecksum27(str) {
  str = String(str);
  let sum = 0;
  for (let i = 0; i < str.length; i++) sum += str.charCodeAt(i);
  return str + String(sum % 27).padStart(2, '0');
}
function getPayByLinkForOrderUid(baseUrl, hpaySiteId, orderUid) {
  const uid = String(orderUid || '').replace(/^PBL/, '');
  return `${String(baseUrl).replace(/\/$/, '')}/pbl/${hpaySiteId}-${addChecksum27(uid)}`;
}
// https://sandbox.pay.holest.com/pbl/{HPaySiteId}-{order_uid}{checksum27}
```

---

## Optional — Advanced: Payment / Module Backend Handlers

> **Skip unless** the user needs server-side payment sync, void, refund, capture, or other module actions without the HPay admin UI. Never call from the browser.

### URL pattern

```
POST /clientpay/handlers/{type}/{merchant_site_uid}/{module_uid}/{order_uid}/{method}
```

`{type}`: `payment` | `integration` | `fiscal` | `shipping`.

Payment example: `.../handlers/payment/{merchant}/{payment_method_uid}/{order_uid}/queryRequest`

Same pattern applies to other modules. Fiscal/integration use **`defaultAction`** for the default expected op (e.g. efiscal → `createSale`). They do not all share payment-like standard method names — prefer `orderActions` UI, or ask Holest support for module-specific endpoints.

### Auth (JSON body — not headers)

Handlers put `order_uid`, `rand`, `verificationhash` in the **JSON body** (Orders Admin API uses headers instead). Signature algorithm is the same as charge / `generatePOSRequestSignature`.

Reference sample: `hpay_payment_queryRequest_sample_nodejs.js`

**Interactive handbook:** https://apps.holest.com/holest-pay/hpay_common_backend_api_calls.html — try `store` / Pay-By-Link, payment handlers, and Orders Admin API calls live (sandbox/production), with request log and PHP / Node.js / C# samples.

```javascript
const body = { order_uid: orderUid };
body.rand = `rnd${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
body.verificationhash = generatePOSRequestSignature(merchantSiteUid, SECRET_KEY, body);

await fetch(
  `${BASE_URL}/clientpay/handlers/payment/${encodeURIComponent(merchantSiteUid)}/`
  + `${encodeURIComponent(paymentMethodUid)}/${encodeURIComponent(orderUid)}/queryRequest`,
  { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }
);
```

After `queryRequest`, call **`getOrder`** for current HolestPay status. Status changes may fire **`orderupdate`** webhook (`I(P|S|F|I)N` URL).

### Standard payment methods

| Method | Purpose | Body notes |
|--------|---------|------------|
| `queryRequest` | Sync payment state from bank GTW into HPay | `order_uid`, `rand` (+ signature) |
| `syncOnPOS` | Explicitly trigger `orderupdate` webhook | `order_uid`, `rand`. **Requires** panel `I(P|S|F|I)N` notify URL to be configured — otherwise HolestPay has nowhere to send the webhook |
| `voidRequest` | Full cancel before bank clearing | `order_uid`, `rand` |
| `refundRequest` | Refund | Required: `order_uid`, `rand`. Optional partial: `total` (order currency); with items: `order_items[]` + `refunded_qty` / `refunded` per item |
| `captureRequest` | Capture RESERVED (pre-auth) amount | Required: `order_uid`, `rand`. Optional partial: `total`; with items: `captured_qty` / `captured` per item |

### Fiscal / integration — `defaultAction`

Fiscal and integration modules have **`defaultAction`** — runs the module’s default expected operation for the order (e.g. **efiscal**: `defaultAction` ≈ **`createSale`**).

```
POST /clientpay/handlers/fiscal/.../{order_uid}/defaultAction
POST /clientpay/handlers/integration/.../{order_uid}/defaultAction
```

Unlike payment (`queryRequest`, `voidRequest`, …), fiscal/integration modules do **not** share one fixed action list for every module — each is different. For custom server-side ops beyond `defaultAction`, **ask Holest support**. Prefer the built-in **`orderActions` admin UI** (same as HPay panel): it renders all available payment / fiscal / integration / shipping actions for the current order status. Use raw handlers mainly for automation.

If the merchant uses a **WAF / firewall**, whitelist **`pay.holest.com`** (and `sandbox.pay.holest.com` for tests) — see CSP / WAF section.

---

## Checklist

- [ ] FrontCore `<script>` tag added globally (all pages/views)
- [ ] Script URL stored as a single config value (easy sandbox ? production swap)
- [ ] `HPayInit()` called on checkout page load; `client.MerchantsiteUid` saved
- [ ] Payment method selector populated from `client.POS.payment` using `pm.Name` and `pm.HPaySiteMethodId`
- [ ] Shipping method selector populated from `client.POS.shipping` (if applicable)
- [ ] `onHPayResult` event handler implemented
- [ ] POST-back handler implemented on `order_user_url` page (for redirect-type methods)
- [ ] Receipt containers (`payment_html`, `fiscal_html`, `integr_html`, `shipping_html`) present on result page
- [ ] If card saving used: `vault_token_uid` saved to database on successful payment
- [ ] Dock container present if any payment method supports docking (`pm.PayInputUrl`)
- [ ] Footer logotypes rendered from `HPay.POS.pos_parameters` (cards, banks, 3DS)
- [ ] TOS checkbox present near Pay button; TOS content from `/clientpay/tos/<uid>`

---

## Required for Bank Production Approval — Logotypes and Terms of Service

> ?? **This section has nothing to do with payment functionality** — payments work without it. However, **almost all banks in the region will require these elements to be present on the site before approving the POS for production use.** Implement these alongside the payment integration.

---

### Footer Logotypes (Card logos, Bank logos, 3DS logos)

Banks require card brand logos, acquiring bank logos, and 3DS security logos to appear in the site footer — in a single horizontal line, **no taller than approximately 1 cm visually**. Order: card logos first, bank logos in the middle (with some spacing on both sides), 3DS logos on the right. Bank and 3DS logos must be linked. The footer strip must be visible across **all pages of the website**, not just the checkout page.

HolestPay provides all logo image URLs and link targets via `HPay.POS.pos_parameters` after `HPayInit()`. Use them — do not source logos elsewhere.

**CSS for the footer branding strip:**

```css
.hpay_footer_branding_wrapper {
  width: 100%;
  padding: 8px 0;
  border-top: 1px solid #e0e0e0;
}
.hpay_footer_branding {
  display: flex;
  align-items: center;
  gap: 0;
  flex-wrap: nowrap;
}
.hpay-footer-branding-cards,
.hpay-footer-branding-bank,
.hpay-footer-branding-3ds {
  display: flex;
  align-items: center;
  flex-wrap: nowrap;
}
.hpay-footer-branding-bank  { margin: 0 12px; }
.hpay_footer_branding img   { height: 1cm; width: auto; display: inline-block; }
```

**JavaScript — call this after `HPayInit()` resolves:**

```javascript
function renderHPayFooterLogotypes() {
  if (!(typeof HPay !== 'undefined' && HPay && HPay.POS)) return;
  if (!HPay.POS.pos_parameters) return;

  let card_images_html = '';
  let banks_html       = '';
  let threes_html      = '';

  if (HPay.POS.pos_parameters['Logotypes Card Images']) {
    HPay.POS.pos_parameters['Logotypes Card Images'].split('\n').forEach(src => {
      if (src.trim()) card_images_html += `<img src="${src.trim()}" alt="Card" />`;
    });
  }

  if (HPay.POS.pos_parameters['Logotypes Banks']) {
    HPay.POS.pos_parameters['Logotypes Banks'].split('\n').forEach(line => {
      if (!line.trim()) return;
      // format: "imageUrl:linkUrl" — colons in URLs are escaped before splitting
      const t = line.replace(/https:/gi, '-PS-').replace(/http:/gi, '-P-')
        .split(':').map(r => r.replace(/-P-/g, 'http:').replace(/-PS-/g, 'https:'));
      banks_html += t.length > 1
        ? `<a href="${t[1]}" target="_blank"><img src="${t[0]}" alt="Bank" /></a>`
        : `<img src="${t[0]}" alt="Bank" />`;
    });
  }

  if (HPay.POS.pos_parameters['Logotypes 3DS']) {
    HPay.POS.pos_parameters['Logotypes 3DS'].split('\n').forEach(line => {
      if (!line.trim()) return;
      const t = line.replace(/https:/gi, '-PS-').replace(/http:/gi, '-P-')
        .split(':').map(r => r.replace(/-P-/g, 'http:').replace(/-PS-/g, 'https:'));
      threes_html += t.length > 1
        ? `<a href="${t[1]}" target="_blank"><img src="${t[0]}" alt="3DS" /></a>`
        : `<img src="${t[0]}" alt="3DS" />`;
    });
  }

  const logotypesDiv = document.createElement('div');
  logotypesDiv.className = 'hpay_footer_branding';
  logotypesDiv.innerHTML =
    `<div class="hpay-footer-branding-cards">${card_images_html}</div>` +
    `<div class="hpay-footer-branding-bank">${banks_html}</div>` +
    `<div class="hpay-footer-branding-3ds">${threes_html}</div>`;

  const wrapper = document.createElement('div');
  wrapper.className = 'hpay_footer_branding_wrapper';
  wrapper.appendChild(logotypesDiv);

  (document.querySelector('footer') || document.querySelector('main') || document.body)
    .appendChild(wrapper);
}

// Call after HPayInit resolves:
// HPayInit().then(client => { renderHPayFooterLogotypes(); });
```

---

### Terms of Service Acceptance Checkbox

Almost all banks in the region require the customer to explicitly accept the site Terms of Service before payment — typically a checkbox with a link to the TOS content.

**HolestPay provides a ready-to-use Terms of Service / Purchase Conditions template page for each POS/site:**

```
https://sandbox.pay.holest.com/clientpay/tos/<merchant_site_uid>?lang=rs
https://pay.holest.com/clientpay/tos/<merchant_site_uid>?lang=en
```

Supported `lang` values: `en`, `rs`, `bs`, `hr`, `me`, `de`, `es`, `gr`, `tr`, `mk`, and others.

This URL returns HTML content (no `<html>` wrapper) and can be:
- Loaded in an `<iframe>`
- Fetched with `fetch()` / AJAX and injected into a modal
- Opened directly in the browser (use `target="_blank"`)

> ?? **Important:** This is **not** a separate "second HolestPay Terms" that replaces your site Terms. The `/clientpay/tos/<merchant_site_uid>` content is a merchant-specific **template/proposal of your own purchase Terms** (with your POS/merchant context), meant to be used as the same Terms of Service page your checkout checkbox points to. Keep one coherent TOS page for customers (your site TOS), and ensure it includes the required payment clauses.

**Implementation — TOS modal using HolestPay built-in dialog** (`hpay_dialog_open` becomes available after `client.loadHPayUI()` resolves):

```javascript
// Call client.loadHPayUI() first to make hpay_dialog_open available:
// HPayInit().then(client => client.loadHPayUI()).then(() => { /* hpay_dialog_open is ready */ });

function openTOS(merchant_site_uid, lang) {
  const tos_url = `https://sandbox.pay.holest.com/clientpay/tos/${merchant_site_uid}?lang=${lang || 'en'}`;
  // Replace sandbox host with pay.holest.com for production
  hpay_dialog_open('tos', 'Terms of Service', tos_url, 'large', {
    ['I understand and accept these Terms of Service']: {
      Run: function(dlg) {
        dlg.close();
        if (dlg.parentNode) dlg.parentNode.removeChild(dlg);
        // Mark TOS as accepted — enable the Pay button or proceed with payment
      },
      action_position: 'center',
      style: { 'min-width': '120px' }
    }
  });
}
```

**Minimum required UI — add this near the Pay button:**

```html
<label style="display:flex;align-items:center;gap:8px;margin-bottom:8px;">
  <input type="checkbox" id="tos-accept" required />
  <span>
    I accept the
    <a href="#" onclick="openTOS(MERCHANT_SITE_UID, 'en'); return false;">Terms of Service</a>
  </span>
</label>
<!-- Disable Pay button until checkbox is checked -->
```

```javascript
document.getElementById('tos-accept').addEventListener('change', function() {
  document.getElementById('do-pay').disabled = !this.checked;
});
```

**Checklist for bank approval:**
- [ ] Card brand logos visible in footer (from `HPay.POS.pos_parameters['Logotypes Card Images']`)
- [ ] Bank logos visible in footer, linked (from `HPay.POS.pos_parameters['Logotypes Banks']`)
- [ ] 3DS logos visible in footer, linked (from `HPay.POS.pos_parameters['Logotypes 3DS']`)
- [ ] All logos in a single horizontal line, max ~1 cm height
- [ ] TOS checkbox present near the Pay button, Pay button disabled until checked
- [ ] TOS content matches or includes HolestPay-provided TOS (`/clientpay/tos/<uid>`)

---

## Test Cards for Sandbox Testing

Test card numbers for almost all supported banks and payment methods can be found directly on the **dashboard page** of the HolestPay sandbox panel at https://sandbox.pay.holest.com — no need to search elsewhere. Log in and check the dashboard.

---

## Terms of Service Page — Required Content

The "Terms of Service" page that the customer checks before payment must be **comprehensive and self-contained**. Because the customer ticks a single "I accept the Terms of Service" checkbox that links to this one page, **everything required by the bank and by law must be covered on that exact page** — not spread across separate pages.

The following must be present in the Terms of Service content (either written directly or clearly summarized with a reference to the full document inline):

- **Purchase conditions** — what is being sold, pricing, order confirmation process
- **Delivery policy** — delivery methods, timeframes, costs, geographic coverage
- **Refund and return policy** — conditions, process, and timeframes for refunds and returns
- **Subscriptions (if offered)** — state that recurring/subscription billing exists on the site and describe from the buyer's perspective what they can expect (renewal timing, cancellation, use of saved cards)
- **PCI DSS statement** — explicit confirmation that card data transfer/processing is secured according to PCI DSS standards and that the merchant does not store raw card data (HolestPay handles card processing on the merchant's behalf)
- **Merchant contact information** — legal business name, address, email, and phone number for customer support

> The merchant may have separate dedicated pages for privacy policy, delivery conditions, refund policy, etc. — that is fine. But **all of the above topics must also appear on the single Terms of Service page** that the payment checkbox links to, because that is the only page the customer is asked to review and accept before paying.

> HolestPay provides a base TOS/purchase-conditions text via `/clientpay/tos/<merchant_site_uid>` that already includes payment-security wording (including PCI DSS transfer handling). Treat it as baseline content for the merchant's own single Terms page, then extend it with delivery, refund, and contact details — not as a separate second TOS document.

---

## Before Requesting Bank Production Approval — Site Readiness

Before the merchant contacts their bank to activate the POS for production, the site must be genuinely complete. A bank technician will review the site manually and will reject it if it does not look like a real, finished online store.

**The following will cause immediate rejection:**

- **Placeholder content** — any "Lorem ipsum", "Coming soon", "Test product", dummy images, or unfilled template text anywhere on the site
- **Mixed languages** — site content, product names, descriptions, and all pages must be consistently in one language (or properly localized if multilingual); a mix of languages on the same page signals an unfinished site
- **Missing or incomplete pages** — the site must have real products/services with actual descriptions and prices, a working checkout flow, and all required legal pages (Terms of Service, Privacy Policy, Contact/About)
- **Non-functional links or broken pages** — every linked page must load and contain real content
- **Test or sandbox data visible** — no test order UIDs, sandbox URLs, or debug output visible to visitors

> Tell the user: *"Before you ask your bank to approve the POS for production, make sure the site looks like a finished, real store. Bank technicians visit the site in person before approving. If they see Lorem ipsum text, empty product pages, mixed languages, or anything that looks unfinished, they will ask you to complete the site first and resubmit — which adds weeks to the process."*

---

## Bank Validation Testing Before Production Approval

Most banks require a **formal validation test** to be performed before activating the POS for production. This is separate from the developer's own sandbox testing.

What this typically involves:

- The bank provides a set of **specific test scenarios** that must be completed successfully (e.g. approved payment, declined payment, 3DS challenge flow, cancellation)
- Tests are performed using **test cards provided by the bank** (which may differ from the general sandbox test cards on the HPay dashboard)
- Results are reported back to the bank (sometimes automatically via their test monitoring system, sometimes manually by the merchant)
- **Whether validation testing is required, and exactly how it is done, depends on the bank and the specific payment method** — some banks require it for every new integration, others only for certain card brands or 3DS configurations

> Tell the user: *"Before your bank activates the production POS, they will likely ask you to run a set of validation test payments using specific test cards they provide. This is a standard bank requirement and is separate from the testing you did during development. Contact your bank's technical integration team to find out exactly what tests are required for your payment method — HolestPay sandbox will be used for these tests as well."*

---

## Shipping Method UI — Required `hpay-sm-options` Placeholder

In the UI element that displays a shipping method's description (the area shown to the buyer when they select a shipping method), you **must include an empty `<span>` with the class `hpay-sm-options` and attribute `hpay_shipping_method_id="<hpay_shipping_method.HPaySiteMethodId>"`**:

```html
<span class="hpay-sm-options" hpay_shipping_method_id="<hpay_shipping_method.HPaySiteMethodId>"></span>
```

HolestPay uses this element to inject additional shipping options and information (e.g. parcel locker selector, delivery time slots, carrier tracking info) for the selected shipping method. Without this placeholder, those features will silently fail to render.

Place it inside the shipping method description container, after any static description text:

```html
<div class="shipping-method-description">
  <!-- your static description text here -->
  <span class="hpay-sm-options" hpay_shipping_method_id="45"></span>
</div>
```

---

## Content Security Policy (CSP) and Site Configuration Requirements

For HolestPay to function correctly, the site must permit the following — ensure these are not blocked by Content Security Policy headers, server configuration, or any firewall/proxy:

### WAF / firewall — whitelist HolestPay hosts

If the merchant site uses a **WAF** (Cloudflare, Sucuri, ModSecurity, AWS WAF, hosting firewall, etc.), **whitelist outbound and inbound traffic involving HolestPay**:

- **`pay.holest.com`** — required for production (browser scripts, API, webhooks from HPay to your notify URL may also need your site reachable from HPay)
- **`sandbox.pay.holest.com`** — required for sandbox/testing

Blocklists or aggressive bot rules that treat HolestPay as unknown traffic commonly break checkout scripts, `/clientpay/charge`, order/handler APIs, and webhook delivery. Always allow HolestPay hosts before blaming integration code.
### Allowed origins (iframes, scripts, XHR/fetch, content)

The site must allow iframes, scripts, and content loaded from:

```
https://pay.holest.com
https://sandbox.pay.holest.com
```

If the site sets a `Content-Security-Policy` header, include these in all relevant directives:

```
Content-Security-Policy:
  script-src  'self' https://pay.holest.com https://sandbox.pay.holest.com ...;
  frame-src   'self' https://pay.holest.com https://sandbox.pay.holest.com ...;
  connect-src 'self' https://pay.holest.com https://sandbox.pay.holest.com ...;
  img-src     'self' https://pay.holest.com https://sandbox.pay.holest.com data: ...;
```

### `eval()` must be permitted

HolestPay internally uses `eval()` to deserialize and execute certain POS method action functions returned from the server (`initActions`, `orderActions`). The site must **not** block `eval()`.

If a CSP header is set, `'unsafe-eval'` must be present in `script-src`:

```
Content-Security-Policy:
  script-src 'self' 'unsafe-eval' https://pay.holest.com https://sandbox.pay.holest.com ...;
```

> ?? If the site uses a strict CSP that blocks `eval()` or restricts iframes/scripts to specific origins, HolestPay will fail silently or partially. This is one of the most common causes of "nothing happens when I click Pay" during integration.

---

## Dock Container Placement

For each payment method row, use this visual order:
1) method **name/label**
2) method **description**
3) method **dock container** (if that method supports docking)

The dock container must be below the description of the same method, and before the next method name is rendered. It must **not** be placed after the full list of all payment methods.

Each payment method in the list that supports docking (`pm.PayInputUrl` is set) needs its own dock container adjacent to it. Best practice is to wrap **description + dock** in one method-details wrapper that is shown only when that method is selected. When the buyer selects that method, `HPay.setPaymentMethodDock()` renders the embedded payment input directly inside that container.

**Correct structure:**
```html
<label>
  <input type="radio" name="payment_method" value="179" />
  Credit Card
</label>
<div class="method-details is-selected" data-method="179">
  <div class="method-description">Card payment description...</div>
  <div id="paymentMethodDock-179" class="hpay-dock-container"></div>
</div>

<label>
  <input type="radio" name="payment_method" value="180" />
  Bank Transfer
</label>
<div class="method-details" data-method="180">
  <div class="method-description">Bank transfer description...</div>
  <!-- no dock here — this method does not support docking -->
</div>
```

---

## Always Render Method Description When Selected

Whenever a payment method or shipping method is selected by the buyer, **always display its description**. Do not skip or hide descriptions.

Method descriptions sometimes contain **functionally important content** — instructions the buyer must read (e.g. bank account number for manual transfer, pickup location details, special conditions). Hiding or omitting descriptions can cause buyer confusion and failed orders.

For shipping methods, the description container must also include the `<span class="hpay-sm-options" hpay_shipping_method_id="<hpay_shipping_method.HPaySiteMethodId>"></span>` placeholder (see earlier section) so HolestPay can inject carrier-specific UI into it.

---

## Shopify-Specific Notes (if building a Lovable app for Shopify)

### Order creation timing

If this integration is for a Shopify storefront, **all communication with the Shopify API (order creation, order update, fulfillment, etc.) must happen only after receiving the HolestPay payment result** — i.e. inside the `onHPayResult` handler or the POST-back handler on `order_user_url`. Do not create or confirm the Shopify order before payment is confirmed. The HolestPay result contains the definitive payment status (`payment_status: PAID|RESERVED|...`) that should trigger the Shopify order write.

### Shopify API credentials with `write_orders` permission

Shopify access tokens that merchants create themselves in the Shopify admin expire after **24 hours** and cannot be used for permanent integrations.

If a permanent Shopify API access token with `write_orders` permission is needed, the merchant can **borrow the credentials from the HolestPay Shopify app**:

1. In the HolestPay panel, go to site/POS settings for the Shopify site.
2. Find the **SHOPIFY CLIENT SECRET** parameter.
3. Use the **Copy All Shopify APP Credentials...** next to it to copy the credentials.

> ?? **Security warning — tell the user this explicitly:**  
> *"These are shared API credentials tied to the HolestPay Shopify app. Do not share them with anyone, do not commit them to a public repository, and do not expose them in frontend code. Store them as private environment variables on your server only."*

---

## HolestPay Language Codes

HolestPay uses its own language code convention — **do not use standard ISO/BCP-47 codes** for Serbian:

| Language | HolestPay code | ? Do NOT use |
|---|---|---|
| Serbian Latin | `rs` | `sr`, `sr-Latn`, `sr-YU`, `sr-lat` |
| Serbian Cyrillic | `rs-cyr` | `sr-Cyrl`, `sr-cyr`, `cyr` |
| Bosnian | `bs` | |
| Croatian | `hr` | |
| Slovenian | `si` | |
| Macedonian | `mk` | |
| English | `en` | |
| German | `de` | |
| Italian | `it` | |
| Spanish | `es` | |
| French | `fr` | |
| Portuguese | `pt` | |
| Dutch | `nl` | |
| Greek | `el` | `gr` |
| Turkish | `tr` | |

Pass this value as the `language` parameter to `HPayInit()` and as `hpaylang` in `pay_request`.