Payment gateway

You are currently reading the integration documentation for the MúzaPay payment gateway.

Product category

MúzaPay needs to know the product category of the purchase to draw from the correct budgets and apply legal rules for drawing employee benefits. For each payment, it's a simple selection from two categories:

• Travel, tourism, culture, sports, printed books and education (“leisure”).

• Goods or services of a health, medical, hygienic and similar nature from medical facilities or the purchase of medical devices on prescription ("health"). For Czechia only. Please use “leisure“ also for health-related (and non-pharmaceutical) goods in Slovakia. From API version 2.

• Pharmaceutical goods - From API version 3. For Slovakia only.

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

MúzaPay does not allow joint payment for a cart that contains a combination of these categories. If you need to deal with such a situation, your e-shop must split the payments into parts (split payments).

Integration process

1. Request access to the gateway's testing environment at support@benefit-plus.cz

   1. Generate a pair of signing keys following the instructions in https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818547

   2. Provide the following information:

      1. Name of the partner/integrator (legal entity)

      2. ID of the partner/integrator

      3. Type of entity that will be connecting - Partner or Integrator.

      4. Email for technical contact

      5. Phone number for technical contact

      6. Name and surname of technical contact

      7. The country in which you want to register the e-shop - CZ, SK

      8. The public name of the e-shop to be displayed to customers

      9. Your public signing key.

2. Receive access credentials (eshopId, password) needed for trial operation from MúzaPay.

3. Implement and test the integration of your e-shop with the gateway in the testing environment

   1. In case of technical problems, contact support@benefit-plus.cz.

4. Perform test scenarios specified in the Integration tests chapter.

5. Announce readiness for transition to production operation.

6. MúzaPay verifies the integration, set up access credentials and keys for the production environment with you, and schedule pre-production verification with you.

7. Together, we conduct the pre-production verification.

8. MúzaPay switches the gateway to production mode.

Payment gateway API

General rules:

• The Application Programming Interface (API) is specified according to the OpenAPI standard version 3: https://swagger.io/specification/v3/.

• The API is REST-ful.

• The transmission protocol is HTTPS.

• The standard data structure is JSON.

• UTF-8 encoding is used for all communication.

• Parameters representing dates and times are formatted according to the Internet Date/Time Format - RFC 3339 chapter 5.6 (ISO 8601 profile) and are in UTC time zone.

• String-type parameters containing a string of zero length or null will be considered not received.

• String-type parameters starting or ending with invisible characters, or containing only invisible characters, will be rejected as invalid.

The payment flow

Open

1. The customer in the e-shop chooses to pay with “MúzaPay“ payment method.

2. The e-shop's backend obtains an access token from the payment gateway's backend, and using it, initiates a payment. This obtains a payment identifier and a dynamic URL for the gateway UI.

3. The e-shop opens the customer's browser to the dynamic URL of the gateway.

4. The customer reads and confirms the payment in the mobile app. No action is required from the e-shop in this step.

5. The gateway redirects the customer's browser back to the e-shop or the e-shop retrieves the updated state of the payment from the gateway's backend.

6. The e-shop loads the update payment state from the gateway's backend (if not yet done).

7. The e-shop displays the payment result to the customer.

Sequence diagram of the payment

Open

Troubleshooting

A payment that has moved to one of the final states can no longer be continued. If you do not have a paid purchase/cart yet, you must request a new payment and can use the same cart identifier orderReferenceCode.

Do not rely on the customer's browser redirection, as it cannot be guaranteed. Always use Payment state monitoring to check the payment state.

If you are unsure of the payment state for any reason, you should attempt a cancellation. Ideally, do this with the certain delay after payment to allow for recovery from any connectivity or functionality outage of the gateway. If the cancellation fails, you may retry, but please avoid an infinite loop. A reasonable number of cancellation attempts is 3, ideally with progressively increasing intervals.

When reporting payment problems to MúzaPay support, it's crucial to provide the paymentId, orderReferenceCode, and the time when the payment was executed (the paymentDateTime value or at least an approximate time).

When requesting technical support during integration, it's ideal to report the log of the entire request and any responses including HTTP headers.

Details

The following chapters contain more detailed information supplementing the API specification.

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818355

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818393

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818435

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818481

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818547

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/87818515

https://benefitplus.atlassian.net/wiki/spaces/BP2/pages/623017985