HolestPay

User Manual

Version 1.0.2, January 2025

About this Manual:

This is a general user manual for the HolestPay system that explains functionalities applicable to all platforms. This document does not mention specific features of individual e-commerce platforms (WooCommerce, Custom, Shopify, Magento, OpenCart, Drupal, WiX, Etsy, Kajabi etc...) but focuses on:

For specific instructions related to your platform (module installation, configuration, platform-specific features), please consult the additional documentation for that platform.

Table of Contents

1. Introduction to HolestPay

HolestPay is an advanced system that enables integrated management of payments, shipping, fiscalization, and business processes through a single central platform. The system is provided by Holest e-Commerce doo, a PSP (Payment Service Provider).

HolestPay Dashboard

Figure 1: HolestPay Dashboard

Key System Features:

Important - What is POS in HolestPay Terminology:
In the HolestPay system, the term "POS" refers to a website (web shop), Android application, or iOS application - NOT a physical POS terminal used in stores. Each POS represents a single sales point, whether it's a website, mobile application, or desktop application.
Important: HolestPay is available in two environments:

These environments are intentionally isolated. You need to create and configure all parameters separately for each environment.

2. Basic Concepts and Terminology

Before you start using the HolestPay system, it's important to understand the basic concepts and terminology used in the platform. This section explains the key operations and statuses that form the foundation of working with the system.

2.1. Payment Operations

HolestPay supports various types of payment operations, depending on the business model and needs:

Authorization

Standard payment model where money is immediately transferred from the customer's card to the merchant's account.

Flow:

  1. Customer enters card details
  2. System sends authorization request to the bank
  3. Bank approves or declines the transaction
  4. If approved, money is transferred to merchant's account (clearing 1-3 days)

Pre-Authorization

First step in a two-step payment model that enables fund reservation.

Characteristics:

When to use:

Post-Authorization / Capture

Second step in the two-step model - executing the actual money transfer after reservation.

Characteristics:

VOID (Cancellation)

Operation that cancels a transaction before the bank executes clearance.

Usage:

Advantages:

Note: After the bank executes clearance (usually 2-24 hours), VOID is no longer possible. Then you need to use REFUND. IPS method does NOT support VOID operation.

REFUND (Money Return)

Operation that returns money to the customer after the transaction is already executed and clearing is completed.

Characteristics:

Status Query

Operation to check transaction status directly with the payment gateway.

When to use:

2.2. HolestPay Status Format

HolestPay uses a complex status format that combines statuses from all modules (payment, fiscalization, shipping). This is the most authoritative status to use in your work.

HolestPay Status Format:

[PAYMENT:payment_status][ (fmethod1_uid)_FISCAL:(fmethod1_status) [(fmethod2_uid)_INTEGR:(fmethod2_status)]...][ (smethod1_uid)_SHIPPING:packet_no@shipping_status [(smethod2_uid)_SHIPPING:packet_no@shipping_status]...]

Important Rules:

Possible Payment Statuses:

Status Description
SUCCESS / PAID Fully paid
RESERVED Amount reserved (pre-authorization), not yet captured
AWAITING Awaiting payment (e.g., bank payment slip)
PAYING Partially paid, used for advance or multi-source payments
REFUNDED Fully refunded
PARTIALLY-REFUNDED Partially refunded
VOID Voided
OVERDUE Payment deadline expired
EXPIRED Deadline expired (for methods with expiry)
OBLIGATED Same as AWAITING but when service delivery has started or there's legal guarantee
REFUSED Refused
FAILED Failed
CANCELED Canceled

HolestPay Status Examples:

PAYMENT:PAID efiscalrs_FISCAL:sale dexpressrs_SHIPPING:AG0304309722@DELIVERED

Explanation: Payment completed, fiscal module added "sale" status, package delivered

PAYMENT:RESERVED

Explanation: Pre-authorization, awaiting capture

PAYMENT:PAID efiscalrs_FISCAL:sale some_uploader_INTEGR:uploaded dexpressrs_SHIPPING:AG001@PREPARING

Explanation: Paid, fiscal module (_FISCAL) added "sale" status, integration module (_INTEGR) added "uploaded" status, package preparing

PAYMENT:PAID dexpressrs_SHIPPING:AG0304309722@DELIVERED

Explanation: Paid and delivered. Fiscal module is configured but doesn't add status to HolestPay format

some_uploader_INTEGR:97

Explanation: Only integration module with status 97, without payment and shipping modules

Important: This is a uniform status format used throughout the platform - in the panel, API responses, webhook notifications, and platform modules. Understanding this format is crucial for proper implementation and order management.

3. Prerequisites and Initial Setup

3.1. Creating a User Account

Before using the HolestPay system, you need to create a user account in the appropriate environment:

HolestPay Login screen

Figure 2: HolestPay system login screen

  1. Visit the website: https://sandbox.pay.holest.com/ (for testing) or https://pay.holest.com/ (for production)
  2. Click on "Register" option
  3. Fill in the data:
  4. Check the option to set up biometric/WebAuthn identity protection (recommended)
  5. Click "Register"
HolestPay registration form

Figure 3: New user registration form

3.2. Multi-Factor Authentication (MFA)

HolestPay requires Multi-Factor Authentication for all users. This is a mandatory security measure that protects your account.

MFA verification

Figure 4: Security code entry screen (MFA)

Supported MFA Methods:

MFA Verification Process:

  1. Enter email and password
  2. System will send security code to email or phone
  3. Enter received code in "SECURITY CODE" field
  4. System will log you in after successful verification
Note: We recommend using biometric authentication (fingerprint, face-id) as it's the fastest and most secure option.

3.3. Creating a Company

Important - How Company Creation Works:

Company creation process (for the first user - founder):

  1. Log in to HolestPay panel
  2. In the left menu, select "COMPANY" option
  3. Click "Create a company" button
  4. Enter company data:
  5. Save the data
  6. You automatically get the "Owner" role for this company
Company list

Figure 5: List of companies the user manages

For other users: If you're not the company founder, first create your account (Chapter 3.1), then ask the company Owner to grant you access (Chapter 3.4 - User Management).

3.4. User Management

If multiple people need access to the HolestPay panel, you can assign them appropriate roles:

User Roles:

Adding a New User:

  1. New user must first create their account on HolestPay platform
  2. In Company settings, go to "Users" section
  3. Click "Add user"
  4. Enter user's email address
  5. Assign appropriate role (Administrator or Operator)
  6. Save
Important - Role Rules:

3.5. Creating a POS (Site or Application)

Each company can have multiple POSes (websites, Android/iOS applications):

  1. In the left menu, select "SITES/APPLICATIONS/SplitPay"
  2. Click "Add new POS"
  3. Select POS type:
  4. Enter data:
  5. Save
POS list

Figure 6: List of POSes (Sites/Applications) for company

Merchant POS UID and Merchant POS Secret: After creating a POS, the system will generate two key pieces of data:

You will use this data to connect your site or application to the HolestPay system. Keep them in a safe place!

HolestPay Subscriptions:

4. Payment Methods

HolestPay supports various payment methods that can be configured according to your business needs. Availability of certain methods depends on the type of subscription you have.

Payment method list

Figure 7: Example of payment methods list for POS

Note: You don't need to specify card brands (Visa, Mastercard, etc.) in advance - this depends on dynamic options and payment methods you add. Each method has its own supported cards.

4.1. Payment Method Types

Card Payments

Characteristics:

Note: HolestPay supports a large number of payment gateways for card payments. Each gateway module you add brings its own specific options and operations (VOID, Capture, Refund, Status Query, etc.). Availability of certain operations depends on the module you use.

IPS Mobile Payments

Instant Payment System - Payment via:

Advantages:

Important: IPS payments do NOT support VOID operation. For money return, you can only use REFUND.

Payment Slip with NBS QR Code

Automatic generation of payment slip containing:

Characteristics:

Installment Payments

Enables customers to pay in monthly installments through the bank:

Warning: Installment payments cannot be refunded programmatically. In case of need for refund, you must contact the bank directly. This is due to interest rates and specific installment payment structure.

5. Shipping Methods

HolestPay enables integration with various courier services and complete shipping process management.

Shipping method list

Figure 8: Example of shipping methods list

Shipping Module Features:

Note: HolestPay supports integration with various courier services. Each shipping module you add brings its own specific options and operations. Basic options include creating courier instructions and printing tickets, while additional features depend on the module and courier API you use.

Editing Shipping Data

When creating or editing a shipment, you can customize all data sent to the courier:

Shipping data editing form

Figure 8a: Form for editing data sent to courier service - enables complete control over shipment information

The form enables editing:

Important: All data can be modified before the shipment is finalized and sent to the courier service. After the courier picks up the package, changes can only be made through the courier service directly.

5.1. Shipping Statuses

Each package has a label in format:

<courier-tracking-code>@STATUS [(warehouse name - if not default)]

Example:

AG0304309722@PREPARING AG0304309723@READY (Warehouse Gornji Milanovac)

Status List:

Status Description
PREPARING Initial status when delivery address is valid. Goods are being prepared for shipping.
READY Goods are prepared and checked, ready for courier pickup.
SUBMITTED Request sent to courier service, awaiting pickup.
DELIVERY Shipment is with courier, delivery in progress.
DELIVERED Shipment successfully delivered to customer.
ERROR Error in communication with courier service API.
RESOLVING Delivery address or something else requires attention (manual intervention).
FAILED Delivery permanently failed (customer unavailable after multiple attempts) or courier API rejected request.
REVOKED Delivery canceled by customer or company.
Note: Status REVOKED is used instead of CANCELED. This is aligned with the latest system version.

6. Fiscalization and Integrations

HolestPay provides advanced fiscalization and business system integration capabilities.

Fiscal and integration methods list

Figure 9: Example of fiscal and integration methods list

6.1. E-Fiscal RS (Electronic Fiscalization - Serbia)

Automatic integration with the Tax Administration system of the Republic of Serbia for issuing electronic fiscal receipts.

Fiscal receipt

Figure 10: Example of electronic fiscal receipt with QR code

Capabilities:

Legal Framework: According to law, fiscal receipt must be issued no later than 24 hours after the sale. With HolestPay system, it's possible to issue receipt at the moment of goods delivery to customers, which is the ideal solution.

When goods are shipped via courier service, three options are possible by law:

Option 1: Digital fiscal receipt before delivery

Option 2: Printed fiscal receipt with package

Option 3: Fiscal proforma + delayed fiscal sale (recommended)

HolestPay supports all three options - choose the one that best fits your business process.

6.2. Fiscal Document Types

Fiscal Sale Receipt

When issued:

Contains:

Fiscal Refund Receipt

When issued:

Required:

Important: Without valid customer TIN, fiscal refund cannot be issued. In that case, "Recall" is used instead of refund.

Receipt Recall (Fiscal Recall)

When used:

Characteristics:

Advance Payment Receipt (Fiscal Advance)

When used:

Process:

  1. Advance receipt is issued for received amount
  2. Additional advance receipts can be issued (each references previous one)
  3. Final sale receipt references all advances

Required: Customer TIN identification

Proforma Invoice (Fiscal Proforma)

When used:

Process:

Required: Customer TIN identification

6.3. TIN and Tax Identification

For fiscal refunds, advances, and proformas, customer identification via TIN (Tax Identification Number) is mandatory.

TIN Format:

PREFIX:VALUE

Supported Prefixes:

Prefix Description Example
10 Customer Tax ID / RS VAT NO (legal entity) 10:105677555
11 Personal ID (individuals - RS citizens) 11:1008985730021
12 Tax ID and JBKJS (sales to government institutions) 12:...
20 ID card number (RS ID) 20:...
21 Refugee card number 21:...
22 EBS 22:...
23 Passport number (Serbian passport) 23:...
30 Passport number (foreign passport) 30:...
31 Diplomatic card 31:...
32 ID card (North Macedonia) 32:...
33 ID card (Montenegro) 33:...
34 ID card (Albania) 34:...
35 ID card (Bosnia and Herzegovina) 35:...
40 Tax ID from foreign country (Foreign TIN) 40:61-2344005

6.4. Other Fiscal & Integration Integrations

Important - How Fiscal & Integration Modules Work:

Types of Fiscal & Integration Modules:

1. Electronic Invoicing and Fiscalization

Modules for integration with tax systems of different countries. Automatic creation and sending of fiscal receipts, invoices, and other documents according to local regulations.

2. Order Export (FTP/SFTP/API)

Modules for automatic order export to external systems:

3. Book-keeping Software Integrations

Modules for two-way integration with accounting software:

4. Data Feed Modules

Enable order data availability through various feed formats.

5. Notification Modules

Specialized modules for sending notifications (push, SMS, email) in specific scenarios.

6. Custom Integrations

HolestPay supports development of custom fiscal & integration modules for your specific business needs via API.

Note: The list of available fiscal & integration modules is constantly expanding. For currently available modules and their capabilities, check the "FISCAL/INTEGRATION MODULES" section in HolestPay panel or contact support.

7. Backend Order Operations

HolestPay enables management of all order aspects in two ways:

  1. Directly on your site - via ready-made modules (WooCommerce, Magento, OpenCart, VirtueMart, Shopify...)
  2. In HolestPay panel - central management of all POSes
Advantage of Ready-Made Modules - Everything in One Place:

HolestPay Integration on Your Site

HolestPay box in order details

Figure 11: HolestPay section in order details on site (WooCommerce example) - all operations available directly in your admin panel

When using a ready-made module (WooCommerce, Magento, OpenCart, VirtueMart, Shopify...), in each order's details you see HolestPay box displaying:

Important: ALL operations possible for a given order will be available in HolestPay box on your site, identical to how they're available in HolestPay panel. There's no difference in functionality - you get full control directly from your platform's admin panel.

Management via HolestPay Panel

Order list

Figure 12: Order list in HolestPay panel with statuses and available options

Order details

Figure 13: Order details in HolestPay panel with available operations

HolestPay panel enables central order management from all your POSes (sites/applications). Useful for:

Note: Set of available operations depends on current order status and system configuration. System dynamically displays only operations that are valid at given moment.

7.1. Payment Operations

Status Query

Function: Re-checks transaction status directly with payment gateway.

When to use:

Capture (Post-Authorization)

Function: Executes charging after pre-authorization.

Note:

VOID (Cancellation)

Function: Cancels transaction before bank executes clearance.

When available:

Advantage: Usually no commission (unlike refund)

Note: IPS method does NOT support VOID operation. For money return from IPS, use only REFUND.

REFUND (Money Return)

Function: Returns money to customer after transaction is executed and clearance completed.

Characteristics:

Note: After executing refund, corresponding fiscal document (refund or recall) needs to be created.

Warning for Installment Payments: Payments made in installments cannot be refunded programmatically. You must contact bank directly for refunding such payments.

Send Payment Link - PAY-BY-LINK

Function: Creates and sends link to customer for completing payment off your site (offsite option).

Useful for:

How it works:

  1. In HolestPay panel (or via API) you create payment link
  2. Enter amount, description, customer data
  3. System generates unique link
  4. Send link to customer via any channel
  5. Customer clicks and opens payment page (hosted by HolestPay)
  6. Customer completes payment
  7. You receive notification about result
Note: This is offsite option - customer doesn't buy on your site but directly on HolestPay payment page. This is exception from standard flow where customers buy on your site.

7.2. Shipping Operations

Create Shipment

Function: Creates shipment and gets tracking number from courier service.

Required data:

Print Label

Function: Generates and prints package label.

Label contains:

Submit to Courier

Function: Sends request to courier service to pick up package.

Status changes from: READY → SUBMITTED

Cancel Shipment

Function: Cancels shipment before or after sending to courier.

Note: Possible cancellation depends on courier service policy and current shipment status.

7.3. Fiscal Operations

Issue Fiscal Receipt

Function: Issues fiscal receipt for sale.

When: After payment is successfully completed.

Parameters: No additional parameters

Fiscal Refund

Function: Issues fiscal receipt for goods return.

Required parameters:

Note: Automatically links to original sale receipt.

Fiscal Recall

Function: Cancels previously issued receipt.

When to use:

Parameters: No additional parameters - TIN not required

Fiscal Advance

Function: Issues advance receipt for partial payment.

Required parameters:

Fiscal Proforma

Function: Issues proforma that doesn't affect taxes.

Required parameters:

Send Fiscal by Email

Function: Re-sends fiscal receipt to customer via email.

Useful when:

Sync on POS

Function: Re-sends results to your site/application

When to use: When you want to manually refresh data on your POS

8. Purchase Process (Customer Flow)

Important - Where Purchase Takes Place:

Standard Payment Flow (same for all methods):

  1. Payment initiation - Customer selects products on your site and chooses payment method on checkout page
  2. Input form presentation - System displays form for entering data specific to selected method (card details, QR code, payment slip, etc.)
  3. Result processing - Payment gateway processes transaction and returns result
  4. Calling fiscal and shipping methods - After successful payment, configured fiscal and shipping methods are automatically called
  5. Result display - Customer sees transaction result (success/failure), payment details, fiscal receipt, and shipping information
Important: Although basic flow is same for all payment methods, input form presentation and user experience differ:

Manual Method Invocation

Note: All payment, fiscal & integration, and shipping methods can be invoked manually:

Manual invocation is done from HolestPay panel or via API.

Pay-by-Link is a feature that allows you to create a unique payment link that you can send to your customer. There are two versions:

Creating link directly in HolestPay panel - customer pays on HolestPay hosted page.

Pay-by-Link form

Figure 12: Pay-by-Link creation form in HolestPay panel

How to create:

  1. In HolestPay panel, open Order or Transaction section
  2. Click on "Create Pay-by-Link" or similar option
  3. Enter order details:
  4. Select available payment methods that customer can use
  5. If shipping is required, select available shipping methods that customer can choose
  6. Set offer validity period (link will be active until specific date/time)
  7. Choose notification sending option (optional):
  8. Click on one of two buttons:
  9. System creates unique link that you can copy and send to customer (if you didn't use "Save and Notify")
Note - Personalization:

When customer opens the link:

When to use offsite Pay-by-Link:

Some platform modules (like WooCommerce) have on-site Pay-by-Link option that works similarly, but with an important difference:

The difference:

How on-site Pay-by-Link works:

  1. Order already exists in your WooCommerce system
  2. In HolestPay box in order details, click "Send Payment Link"
  3. Link leads customer directly to checkout page of your site for that order
  4. Customer completes payment through your standard checkout process

Advantages of on-site version:

Advantages of offsite version:

Important - Choosing version:

Order Tracking

Order tracking method depends on implementation on your site/application. Usually includes:

10. Help and Documentation

HolestPay system contains built-in help section with useful guides and examples.

Documentation and help

Figure 14: Help section with documents and guides

Types of Available Documentation:

Note: Available documentation depends on configured modules and methods on your POS. Documentation is regularly updated and expanded.

How to Access Documentation:

  1. In HolestPay panel left menu, click on "HELP" (or question mark icon)
  2. Select documentation category that interests you
  3. Click on document link you want to view
  4. Document will open in new tab or download

11. Platform Modules and Integration

HolestPay can be integrated with your platform in multiple ways:

Platform modules

Figure 15: Example of available platform modules list

Integration Types:

1. Ready-Made Platform Modules (plugin/extension)

HolestPay offers ready-made modules for popular e-commerce and CMS platforms. List of available modules is constantly expanding.

Ready-Made Module Characteristics:

Note: For currently available platforms and their modules, check "PLATFORM MODULES" section in HolestPay panel or on website. List is regularly updated.

2. JavaScript/HTML Integration

For custom platforms or direct web integration:

3. API Integration

For full control and custom integration:

Example - HolestPayPHP library:

PHP 7.2+, 8.*, 9.* Required PHP module: php-curl

How to Choose Integration Method:

Scenario Recommended Integration
Using popular e-commerce platform Check if ready-made module exists
Custom web application JavaScript/HTML integration or API
Mobile application (Android/iOS) API integration
Desktop application API integration
Full control needed API integration
Recommendations:

12. Email Template Editing

HolestPay enables full personalization of email messages that the system sends to customers. These settings are located in the POS settings section.

Email template list

Figure X: List of available email templates for customization

12.1. Available Templates

In the email templates section, you can see all available templates that you can customize. Each template serves a specific purpose in the payment and order process.

12.2. Template Editing Process

Email template editing is done in three steps:

Step 1: Select Template

  1. In HolestPay panel, go to POS settings
  2. Find the "Mail Templates" section
  3. Select the template you want to edit from the list

Step 2: Select Test Data

Before you start editing, you need to select test data:

Select test data

Figure X+1: Select existing order or order list for test data

Step 3: Editing in Editor

Email template editor

Figure X+2: Editor for editing email templates with live preview functionality

The editor is divided into three panels with live preview functionality:

Left side of editor:

Right side of editor - Preview panel:

Live preview functionality:

Additional features:

12.3. Liquid Template Language

Liquid is a template language used for secure customization of email messages:

Liquid Syntax Examples:

{{ customer.name }} {{ order.total | money }} {% if order.shipping_address %} Shipping address: {{ order.shipping_address }} {% endif %}
IMPORTANT - First Line of Liquid Output:

The first line of Liquid render output is used as the email subject (Subject). This is very important for proper email template operation.

Example:

Your order #{{ order.number }} has been confirmed <!-- This first line becomes the email Subject --> <html> <body> <h1>Thank you for your order!</h1> <p>Your order number {{ order.number }} has been successfully received.</p> </body> </html>

In this example, the email Subject will be: "Your order #12345 has been confirmed", while the rest will be the email body.

12.4. Saving Changes

After you finish editing the template:

  1. Review how it looks in preview with test data
  2. Test with different test data if needed
  3. Verify that the first line is properly formatted for the email Subject
  4. Click "Save" to apply changes
  5. New template will be immediately used for all future emails of that type
Important - Styling and Testing:

13. Support and Contact

Technical Support

For all questions, problems, or help related to HolestPay system:

Support Availability

Technical support is available on business days:

How to Request Help

When contacting support, prepare the following information:

  1. Problem description - as detailed as possible
  2. When problem occurred - date and time
  3. Order ID or transaction ID - if related to specific transaction
  4. Screenshots - if possible
  5. Steps to reproduce - how to replicate problem
  6. Company and POS name - so we can quickly locate your account

Documentation and Resources

Additional documentation, API reference, and video tutorials available at:

Sandbox Environment for Testing

Before production implementation, we recommend testing in sandbox environment:

Subscriptions and Pricing

For information about subscriptions, pricing, and available packages:

Important for Integrators: If you're an integrator working with multiple clients, you can use one account to manage all companies. Each company is created separately, and you can be administrator or owner for multiple companies simultaneously.

System Status

To check HolestPay service status in real-time:

Security Incidents

If you suspect a security incident or discover a vulnerability:

Feature Requests and Feedback

Your feedback is important! If you have suggestions for new features: