Integration of POS Systems

You are now reading the integration documentation of the MúzaPay service for Point-of-Sale systems (POS API).

Co‑existence with Benefit Plus POS integration

If you already have implemented a POS integration using Benefit Plus PartnerService – i.e., a program that uses the Benefit Plus card to identify the customer – and you want to keep the old integration, you may differentiate the services by adding a new payment method “MúzaPay” in addition to the original “Benefit Plus”. Based on the selected payment method your POS system should then use either the old or the new integration.

Product Category

MúzaPay requires knowing the product category of the purchase in order to draw from correct budgets and to apply legal rules for employee benefit spending. For each payment the selection is from three categories:

• Travel, tourism, culture, sport, printed books, education (“leisure”)

• Goods or services of a health‑care, treatment, hygiene and similar nature from health‑care providers or acquisition of medical devices on medical prescription (“health”) - this code is necessary for Czechia only. In Slovakia please use “leisure“ for health-related goods.

• Food and non‑alcoholic beverages (“meal vouchers”)

MúzaPay does not allow a combined payment for a cart that contains a mix of these categories. If you need to handle such a situation, your POS system must split the price of the cart into parts (to perform split payments).

Integration process

1. Request access to the test environment of the service at support@benefit‑plus.cz Provide the following details:

   1. Partner/Integrator name (entity)

   2. Partner/Integrator ID (registration number)

   3. Type of entity connecting – Partner, Integrator.

   4. Email of the technical contact

   5. Phone number of the technical contact

   6. First name and last name of the technical contact

   7. Country in which you wish to register the POS integration – CZ, SK

   8. List of stores/branches where you intend to operate integrated POS systems.

2. You will receive from MúzaPay the identifier(s) of the store storeId and secret key(s) that you will need for test operation.

3. Implement and test your system’s integration with the service in the test environment.

   1. In case of technical issues contact support@benefit‑plus.cz.

4. Carry out the test scenarios specified in the Integration Tests – POS document.

5. Notify readiness to move into production.

6. MúzaPay will verify the integration, set up the secret keys for the production environment and schedule a pre‑production verification with you.

7. You will jointly conduct the pre‑production verification.

8. MúzaPay switches the service for you into production mode.

POS API

General rules:

• The API is specified according to the OpenAPI standard version 3 OpenAPI Specification - Version 3.1.0 | Swagger

• The API is REST‑ful.

• The transport protocol is HTTPS.

• Standard data format is JSON.

• Communication uses UTF‑8 encoding.

• Parameters representing dates and times are formatted according to the Internet Date/Time Format – RFC 3339 (ISO 8601) date‑time, with full three digits seconds fraction (milliseconds) and timezone indicator. Example: 2025-11-03T22:30:43.030Z.

  • Exception: date/time values sent in a URL where delimiters, milliseconds and the timezone indicator are removed — only numerical values of date, hours, minutes and seconds remain. These times are always in UTC. Example: 20251103223043.

• Parameters of type string that contain zero characters are considered not received.

• Parameters of type string starting or ending with invisible characters, or containing only invisible characters, are rejected as invalid.

Payment flow

Open

1. Customer informs the cashier they wish to pay via MúzaPay (i.e., using the MúzaPay mobile app).

2. Cashier closes the shopping cart in the POS and selects the payment method “MúzaPay”.

   1. The POS instructs the cashier to scan the barcode from the customer’s MúzaPay mobile app.

3. Customer opens the MúzaPay mobile app and shows the barcode to the cashier.

4. Cashier scans the barcode.

5. POS initiates the payment by calling the MúzaPay cloud service. The request includes the scanned code.

6. POS monitors the payment flow until the payment reaches a decisive state.

7. POS displays the payment result to the cashier.

8. The mobile app shows the payment result to the customer.

Sequence diagram of the payment

Open

Troubleshooting

In exceptional cases the service may return HTTP status 472, indicating the need to re‑scan the barcode. In such a case instruct the cashier to repeat the barcode scan and create a new payment.

For a payment that has entered one of the terminal states (CANCELED, DECLINED, EXPIRED) it is no longer possible to continue. If the purchase/cart has not yet been paid (i.e., state is not PAID), create a new payment where you may reuse the same cart identifier orderReferenceCode.

If you are not sure of the payment state for any reason you should attempt to cancel it. Preferably allow a time interval before attempting cancellation, to accommodate potential connectivity or service recovery. You may retry cancellation in case of failure, but avoid infinite loops. A reasonable number of cancellation attempts is 3, ideally with progressively increasing delay intervals.

When reporting an issue with a payment to MúzaPay support it is crucial to provide paymentId, orderReferenceCode and the time when the payment was executed (the value of paymentTimestamp or at least date and approximate time).

Details

The following chapters contain detailed information.