Form (redirect)

This documentation provides a comprehensive guide to integrating Monri
Redirect Form into your web application for secure and flexible payment
processing.

1. Overview

The WebPay Form is a straightforward web service designed to facilitate online payments. Merchants collect essential buyer profile and order information on their own website, then securely submit this data to our service using an HTTP POST request which then redirects user/buyer to new browser tab with Monri Form.

1.1 Key Benefits:

• PCI DSS Compliance: Sensitive data is handled directly by Monri.
• Simplified Integration: Streamlined process for card and crypto payments.
• Customizable Style: Form can be styled in limited capacity to match your brand.
  Note: For more comprehensive customization options please refer to Components integration logic.

1.2 Requirements

Integration must be done within our test environment first. When this process is finished and approved by our staff, you may go live and start processing with real money.
To start integrating with WebPay Form service you will need the following:

• Test merchant account - If you don’t have a test merchant account, please contact us at helpdesk@monri.com and we will open one for you.
  Then you can login into your account at https://ipgtest.monri.com/en/login with login and password provided.
• HTTP client library - If you need to programmatically manage approved transactions through API
• All submissions of payment information using Monri Form are made via a secure HTTPS connection. To ensure maximum security the page containing your payment form MUST also be served over HTTPS https:// rather than just http://.

2. Getting Started / QuickStart Guide

Here you can find step-by-step guide to achieve a basic successful integration

2.1 Integration Endpoints:

For testing and development, submit data to: https://ipgtest.monri.com/v2/form
For production, submit data to: https://ipg.monri.com/v2/form

Important Note on URLs:
The production URL subdomain will differ from https://ipgtest.monri.com. Ensure you parameterize this URL for easy transition to the production environment. When we say parameterize, we mean put your URL in some kind of config you so can easily change it when merchant production is due.

2.2 Payment Flow

How payment flow looks:

1. Request From Your System To Monri: Upon a valid request from the merchant system, the WebPay service presents a secure payment form to the buyer/user.
2. Card Details Entry: The user enters their card details and everything else what is needed after which he presses Pay and the form is submitted.
3. Authorization Process:
   • The service sends an authorization request to the acquirer bank from the Morni side.
   • If authorization is approved, the buyer is redirected back to the merchant's site if option was set (SuccessURL).
   • If authorization is declined, an appropriate message is displayed to the buyer directly on Monri form.
4. Response message:
   • Await response message from the Monri system

Important Note: Declined Transactions
3DS declines don't count as declined authorization transactions
If a transaction is declined, the buyer remains on Monri side and the form is displayed with an appropriate message, allowing them to retry. At this point, there is no direct means for the system to communicate the transaction failure back to the merchant.

2.3 Obtain API Credentials

API settings can be found under your merchant account. This information is necessary for service to work properly. API settings values reflect a configuration at the merchant site:

IMPORTANT Parametrize these values for API settings, we strongly advice a merchant to have both, testing and production environments.

• 'key': This is your primary cryptographic key used to secure communication with Monri, specifically for calculating the digest for outgoing requests (e.g., initial POST to the payment form).
• 'authenticity_token': This token identifies your merchant account to the Monri system for each request, ensuring the transaction is associated with your account.
• 'Redirect to success URL': This is a checkbox/flag in your merchant profile settings. When enabled (set to true), Monri will automatically redirect the buyer to your specified Success URL after a successful payment authorization. If disabled, the buyer will remain on the Monri payment page/form even after payment success.

2.4 Construct The Basic POST Request

The most common and flexible way to send data to Monri's WebPay Form is by dynamically creating and submitting an HTML form using JavaScript. This allows you to securely calculate the necessary digest client-side before submission.

Digest Calculation:

f71b8c1560bd7511ba2f0307b3823c06dd39042cd77480543e3d7bf9f3eefa6debed252979ba8edc7a82d9f111

Example Code (script.js):

// These values would typically come from your server-side configuration,
// but are hardcoded here for a quick demonstration.
const merchantKey = "key-8edd04c2ffccf82280fa36a65d999c49";
const authToken = "c81a1ac53bf3b7e553583a7cd2f542f92ad50671";

async function redirectToMonriForm() {
    // Generate dynamic order details for demonstration
    const orderNumber = `ORD-${Math.floor(Math.random() * 1000000)}`;
    const amount = (Math.floor(Math.random() * 900) + 100); // Amount in minor units (e.g., 100 = 1.00 EUR)
    const currency = 'EUR';

    // Calculate the SHA-512 digest
    const encoder = new TextEncoder();
    const dataToHash = merchantKey + orderNumber + amount + currency;
    const buffer = encoder.encode(dataToHash);
    const hashBuffer = await crypto.subtle.digest('SHA-512', buffer);
    const digest = Array.from(new Uint8Array(hashBuffer)).map(byte => byte.toString(16).padStart(2, '0')).join('');

    // Prepare the essential form data
    const formData = {
        "authenticity_token": authToken,
        "ch_full_name": "Monri Test User",
        "ch_email": "test@example.com",
        "order_info": "QuickStart Integration Demo",
        "amount": amount,
        "order_number": orderNumber,
        "currency": currency,
        "transaction_type": "purchase", // Or "authorize"
        "digest": digest,
        "language": "en",
        "success_url_override": "[https://yourDomain.com/success](https://yourDomain.com/success)", // Optional: Provide your override URL
        "callback_url": "[https://yourDomain.com/callback](https://yourDomain.com/callback)",     // Optional: Provide your callback URL
        "cancel_url": "[https://yourDomain.com/cancel](https://yourDomain.com/cancel)"         // Optional: Provide your cancel URL
    };

    // Create and submit the form
    const form = document.createElement('form');
    form.method = 'post';
    form.action = '[https://ipgtest.monri.com/v2/form](https://ipgtest.monri.com/v2/form)'; // Test endpoint

    Object.entries(formData).forEach(([key, value]) => {
        const input = document.createElement('input');
        input.type = 'hidden';
        input.name = key;
        input.value = value;
        form.appendChild(input);
    });
    document.body.appendChild(form);
    form.submit();
}`

Example HTML (index.html):

<!DOCTYPE html>
<html>
<head>
    <title>Monri WebPay Form QuickStart</title>
</head>
<body>
    <h1>Click to proceed to payment</h1>
    <button type="button" onclick="redirectToMonriForm()">Proceed to Payment</button>
    <script src="script.js"></script>
</body>
</html>

Please refer to the Variables - names lengths and formats section to see a complete list of all available parameters, including their lengths, formats, and mandatory requirements.

2.5 Process A Test Transaction

After constructing your form (from step 2.2), you can submit it to the test endpoint (https://ipgtest.monri.com/v2/form)

Use the following test card details for testing approved or declined authorization:

2.6. Verify Response (Callback & Success URL Endpoints)

2.6.1 Callback Mechanism

{
   "id":186562,
   "acquirer":"integration_acq",
   "order_number":"a6b62d07cc89aa0",
   "order_info":"order info for a6b62d07cc89aa0",
   "amount":100,
   "currency":"EUR",
   "ch_full_name":"John Doe",
   "outgoing_amount":100,
   "outgoing_currency":"EUR",
   "approval_code":"914783",
   "response_code":"0000",
   "response_message":"approved",
   "reference_number":"000002902038",
   "systan":"186561",
   "eci":"05",
   "xid":"fake authenticated xid +=",
   "acsv":"fake authenticated cavv +=",
   "cc_type":"visa",
   "status":"approved",
   "created_at":"2019-09-06T14:24:44.906+02:00",
   "transaction_type":"purchase",
   "enrollment":"Y",
   "authentication":"Y",
   "pan_token":null,
   "masked_pan":"434179-xxx-xxx-0044",
   "issuer":"zaba-hr",
   "number_of_installments":null,
   "custom_params":"{a:b, c:d}"
}

2.6.2 Success URL Mechanism

Redirect to success URL is made after transaction is approved and if redirect flag is set in API settings. Data for this transaction is returned back to merchant site in this step.

Following variables are set in redirect GET request to success URL:

• acquirer
• amount
• approval_code
• authentication
• cc_type
• ch_full_name
• currency
• custom_params
• enrollment
• language
• masked_pan
• number_of_installments
• order_number
• response_code
• digest (returned digest)

Success URL (HTTP GET request) looks like this:

https://ipgtest.monri.com/shop/success?acquirer=integration_acq&amount=100&approval_code=629762&authentication=Y&cc_type=visa&ch_full_name=John+Doe&currency=USD&custom_params=%7Ba%3Ab%2C+c%3Ad%7D&enrollment=Y&language=en&masked_pan=434179-xxx-xxx-0044&number_of_installments=&order_number=02beded6e6106a0&response_code=0000&digest=575 c64b2f5a0701997c8f9cfe4293706e88203cd911695ab747ce45830e4e3cbf71577c401e476988e4a4e1b0b 5f3ecbc56277394df07fa51fbe05869d1b067a

Success URL source check

2345klj

https://ipgtest.monri.com/shop/success?acquirer=integration_acq&amount=100&approval_code=629762&authentication=Y&cc_type=visa&ch_full_name=John+Doe&currency=USD&custom_params=%7Ba%3Ab%2C+c%3Ad%7D&enrollment=Y&language=en&masked_pan=434179-xxx-xxx-0044&number_of_installments=&order_number=02beded6e6106a0&response_code=0000

digest = SHA512('2345kljhttps://ipgtest.monri.com/shop/success?acquirer=integration_acq&amount=100&approval_code=629762&authentication=Y&cc_type=visa&ch_full_name=John+Doe&currency=USD&custom_params=%7Ba%3Ab%2C+c%3Ad%7D&enrollment=Y&language=en&masked_pan=434179-xxx-xxx-0044&number_of_installments=&order_number=02beded6e6106a0&response_code=0000')

b96025517326db3b952ba783281701bf48cd1fffa4fb61f0c05847e6498919f99630fbfd575ce9ea9f361ec8bb9bf9e0d349dee0c5474a5141ce91b3e1f95ef3

3. Advanced Features

3.1 Request Restriction: Forced Installments

To mandate that a payment be made with installments, use the force_installments option.

Supported values for this parameter are boolean true and string 'true'. If false is provided, or if the parameter is omitted, it will default to false.

When this option is enabled, the buyer is required to select one of the available installment options and is unable to make a single, one-off payment.

3.2 Request Restriction: Tokenize brands

tokenize_brands - provide this value if you want to limit card tokenization to card brand(s). Multiple brands can be sent (separated by comma).

This value is used in conjunction with tokenize_pan_offered = true .

Supported brands:

• visa
• master
• maestro
• diners
• amex
• jcb
• discover
• dina

Example:

• Set tokenize_pan_offered to true
• Set value tokenize_brands to master,maestro (comma separated values)
• Submit prepared data
• Enter mastercard or maestro card number in card number field
  • Save card for future payments is shown
  • Check Save card for future payments
  • Proceed with payment
  • Entered card is successfully tokenized
  • pan_token value is added to success_url if redirect to success url is enabled and callback is set in the merchant profile
• Enter visa, diners, discover or amex card number in card number field
  • Save card for future payments is now hidden & disabled
  • Proceed with payment
  • Card is not tokenized upon transaction approval

3.3 Request Restriction: Custom Attributes

Provide custom_attributes value if you want to customize form behaviour. This value (if provided) must be valid json.

Currently we support following keys:

• installments_config
• fields_config

Example:

{
  "installments_config": {
    "rules": [
      {
        "brand": "visa",
        "min_installments": 2,
        "max_installments": 12
      },
      {
        "brand": "master",
        "min_installments": 12,
        "max_installments": 24
      }
    ]
  },
  "fields_config": {
    "fields": [
      {
        "name": "ch_email",
        "readonly": true
      },
      {
        "name": "ch_full_name",
        "readonly": true
      }
    ]
  }
}

3.3.1 Installments Config

Used to customize installments selection after user’s card number input.

This extension can be used to fulfil contract between merchant and buyer, where buyer can only pay with one of supported card brands (provided in rules list) by selecting installments from min_installments to max_installments defined in installments config.

Types:

• InstallmentConfig
  • type = object
  • properties
    • rules
      • type = Array<InstallmentsConfigRule>
      • description = includes one or more installments config rule. Rule’s brand must be unique per rules
        array. This means you cannot include multiple brand = ‘brand’ rules.
• InstallmentsConfigRule
  • type = object
  • properties
    • brand
      • type = string
      • description = one of visa,master,maestro, diners, amex
    • min_installments
      • type = number, integer
      • description = min installments, must be < than max_installments
    • max_installments
      • type = number, integer
      • description = max installments, must be > than min_installments

Installments config example:

{
  "installments_config": {
    "rules": [
      {
        "brand": "visa",
        "min_installments": 2,
        "max_installments": 12
      },
      {
        "brand": "master",
        "min_installments": 12,
        "max_installments": 24
      }
    ]
  }
}

Usage example

Requirements

• installments are enabled in merchant’s profile
• merchant’s acquiring account is enabled for installments

If you need helping enabling installments contact support@monri.com

Example steps

• Set custom attributes field to

'{"installments_config":{"rules":[{"brand":"visa","min_installments":2,"max_installments":12},{"brand":"master","min_installments":12,"max_installments":24}]}}'

• Submit prepared data
• Enter visa or master card number in card number field
  • Installments selection is updated using rules provided in installments config. If visa is entered installments
    selection is one time payment (jednokratno) and then from 2 to 12 installments.
    If master is entered installments selection is one time payment (jednokratno) and then from 12 to 24
    installments
  • Select desired number of installments
  • Proceed with payment
  • Payment completed
• Enter amex (eg 3704 387472 13977) in card number field
  • installments selection is only one time payment - jednokratno
  • appropriate error message is shown - Card 'amex' not supported
  • payment is disabled

3.3.2 Fields Config

Used to customize installments selection after user’s card number input.

This extension can be used to fulfil contract between merchant and buyer, where buyer can only pay with one of supported card brands (provided in rules list) by selecting installments from min_installments to max_installments defined in installments config.

Types:

• FieldsConfig
  • type = object
  • properties
    • fields
      • type = Array<FieldConfig>
      • description = includes one or more field configs
• FieldConfig
  • type = object
  • properties
    • name
      • type = string
      • description = one of ch_email,ch_full_name
    • readonly
      • type = boolean
      • description = true or false. Field is readonly for input only if initial value is provided and valid

Fields config example:

{
   "fields_config":{
      "fields":[
         {
            "name":"ch_email",
            "readonly": true
         },
         {
            "name":"ch_full_name",
            "readonly": true
         }
      ]
   }
}

Usage example

Example steps

• Set custom attributes field to

'{"fields_config":{"fields":[{"name":"ch_email","readonly":true},{"name":"ch_full_name","readonly":true}]}}'

• Submit prepared data
• Inputs for email and full name (if provided) are readonly

3.4 Request Restriction: Rules

Currently Rules functionality is in BETA phase. If you are interested in using custom rules please contact us at support@monri.com

To limit payment with rules simply provide comma separated list of rules for the payment.
An example would be: rules=rule-id-1,rule-id-2,rule-id-3

Transaction is declined if one of rules is not satisfied.

3.5 Request Additional Information: Custom Parameters

Merchant can also send custom parameters/variables if needed. Those parameters will be passed back in redirect (callback) after approved authorization. Just pack all the data you wish to send in JSON format and submit that under custom_params variable.

3.6 Response: Overrides

Use the following parameters to override set endpoints that are enabled in merchant’s profile:
NOTE: Success and Cancel overrides will only work if original endpoints are enabled and set

3.7 Response: WebHooks (Callback mechanism)

{
  "event": "transaction:approved",
  "payload": {
    "id": 996660,
    "acquirer": "xml-sim",
    "order_number": "0d4546c748b9c4f",
    "order_info": "Monri Test",
    "amount": 100,
    "currency": "EUR",
    ...
 }

3.8 Form: Visual Changes

The visual appearance of the merchant form can be customized through the merchant’s profile. These customizations are divided into two main categories:

1. UI Customization Settings – Adjust the visual elements of the form (e.g., colors, layout, branding).
2. Customized Translations – Modify the text displayed on the form to match the desired language or terminology.

Note: The V3 version of the form also includes an option to select different form sizes for improved layout flexibility.

3.8.1 V2 Form (legacy)

UI Customization Settings

• Order info color
• Order info label color
• Submit button color
• Order info value color

Customized Translations

• Language
• Amount field title
• Store name title
• Order number title
• Pay button caption

3.8.2 V3 Form

UI Customization Settings

• Order info color
• Order info label color
• Submit button color
• Order info value color

Customized Translations

• Language
• Amount field title
• Store name title
• Order number title
• Pay button caption

Form Size
Possible options:

• Default/Standard Form
• Form without user data
• Card data, amount and order number
• Card data only
• Logo, header and card data
• Form with user and payment type

3.9 Additional Module: Customers

The Customers Module was developed to address a merchant's need for a streamlined process of storing customer data, eliminating the complexity of handling it manually.

This module introduces advanced functionality and should be considered only after the integration logic is fully understood, due to its complexity and dependencies.

For detailed usage instructions and implementation guidelines, please refer to the official documentation:
👉 Customers Module

3.10 Additional Module: Discounts

Discounts module is developed for the need to calculate different discounts before authorization is initiated.

4. Variable Reference

Please refer to Variables - names lengths and formats

5. Additional Features

• Demo:
  See a live demonstration of the redirect payment flow here: Demo Redirect.

• Email Notifications:
  Optionally, email notifications can be sent to both the merchant and the buyer upon a successful purchase. These notifications, along with custom email templates, can be configured within your merchant account settings.