WebPay

LightBox implementation

Content

Overview

The Lightbox approach uses an <iframe> to embed the payment page as an overlay to your online shop.

When the Lightbox Mode is invoked, the merchants online shop is darkened out and the payment page appears as a floating element on top.

Integration

The simple integration uses a <script> tag inside your payment form to render the purple Lightbox button. Upon completion of the Checkout process, Lightbox submits your form to your server, passing along a transaction_response and any elements your form contains.

You can find a demo on this link Demo Lightbox

Transaction response input contains JSON stringified transaction response received as payment processing result. Example:

{
  "id":164091,
  "acquirer":"integration_acq",
  "order_number":"yYiM5TYKTU",
  "amount":100,
  "currency":"HRK",
  "outgoing_amount":100,
  "outgoing_currency":"HRK",
  "approval_code":"901199",
  "responseCode":"0000",
  "responseMessage":"approved",
  "reference_number":"000002833738",
  "systan":"164090",
  "eci":"06",
  "xid":null,
  "acsv":null,
  "cc_type":"visa",
  "status":"approved ",
  "created_at":"2019-05-23T15:31:44+02:00",
  "transaction_type":"purchase",
  "enrollment":"N",
  "authentication":null,
  "pan_token":null,
  "issuer":"xml-sim"
}

When adding the following code to your page, make sure that the form submits to your own server–side code within the action attribute:

<form action="your-server-side-code" method="POST">

<script src="https://ipgtest.monri.com/dist/lightbox.js" class="lightbox-button"
    data-authenticity-token=""
    data-amount="100"
    data-currency="USD"
    data-order-number=""
    data-order-info="Lightbox example"
    data-digest=""
    data-transaction-type="purchase"
    data-ch-full-name="Test"
    data-ch-zip="Test"
    data-ch-phone="Test"
    data-ch-email="[email protected]"
    data-ch-address="Adresa"
    data-ch-city="Grad"
    data-ch-country="Croatia"
    data-language="en">
</script>

</form>

Digest is calculated using following formula:

digest = SHA512(key + order_number + amount + currency)

With the following example data

the digest formula gives a result as follows:

digest = SHA512("2345kljbcdef54321EUR") # resulting with "f71b8c1560bd7511ba2f0307b3823c06dd39042cd77480543e3d7bf9f3eefa6debed252979ba8edc7a82d9f111d90f8e31c1c7ab5af39796b26e59a0b2d7cf98"

You can check digest on this link Calculate Digest

Data Parameters

Buyer’s profile

name length format lightbox-key additional info
ch_full_name 3-30 alphanumeric data-ch-full-name buyer’s full name
ch_address 3-100 alphanumeric data-ch-address buyer’s address
ch_city 3-30 alphanumeric data-ch-city buyer’s city
ch_zip 3-9 alphanumeric data-ch-zip buyer’s zip
ch_country 2-3 alphanumeric data-ch-country buyer’s country in alpha2, alpha3 letter code or 3 digit ISO numeric code
ch_phone 3-30 alphanumeric data-ch-phone buyer’s phone
ch_email 3-100 alphanumeric data-ch-email buyer’s email

Order details

name length format lightbox-key additional info
order_info 3-100 alphanumeric data-order-info short description of order being processed
order_number 1-40 alphanumeric data-order-number unique identifier
amount 3-11 integer data-amount amount is in minor units, ie. 10.24 USD is sent as 1024
currency predefined alpha data-currency possible values are USD, EUR, BAM or HRK

Processing data

name length format lightbox-key additional info
language predefined alpha data-language used for errors localization, possible values are en, es, ba or hr
transaction_type predefined alpha data-transaction-type possible values are authorize, purchase, capture, refund, void
authenticity_token 40 alphanumeric data-authenticity-token auto generated value for merchant account, can be found under merchant settings
digest 40 alphanumeric data-digest SHA512 hash generated from concatenation of key, order_number, amount and currency as strings; key can be found under merchant settings
number_of_installments 1-2 integer data-number-of-installments range 2-12
moto predefined boolean data-moto possible value is true or false; missing variable is equivalent to false

Additional info

name length format lightbox-key additional info
tokenize_pan_offered predefined boolean data-tokenize-pan-offered if true and merchant has secure vault active (tokenization enabled) then save card for future payments will be shown to customer. If customer decided to save the card and transaction is approved we’ll provide pan_token which you can store on your side.
whitelisted_pan_tokens predefined comma separated pan tokens data-whitelisted-pan-tokens DEPRECATED, check migration guide
supported_payment_methods predefined comma separated payment methods data-supported-payment-methods provide this value if customer decides to pay with previously saved card(s) or with new card. If this value is provided and valid (card not expired, token valid etc) then only cvv input will be shown on the payment form. All other information (masked pan, expiry date etc) will be pre filled. Multiple tokens can be sent (separated by comma). In that case, the user will have an option which payment method to use.
tokenize_pan predefined boolean data-tokenize-pan tokenize pan without prompting the user
tokenize_brands predefined comma separated list of card brands data-tokenize-brands provide this value if you want to limit card tokenization to card brand(s). Multiple brands can be sent (separated by comma). Refer to tokenize brands section below.
custom_attributes predefined valid JSON string data-custom-attributes provide this value if you want to customize form behaviour. Refer to the custom attributes section below for more details.

Migrating from data-whitelisted-pan-tokens

Simply replace key data-whitelisted-pan-tokens with a key data-supported-payment-methods and you are good to go!

Supported Payment Methods

Usually deprecating useful existing functionality comes with reward!

Now it’s possible to set card + saved_card option thus enabling buyer to select one of saved card or rather enter a new card.

Simply replace whitelisted_pan_tokens with supported_payment_methods and you are free to add card option to previously saved cards.

Setting supported payment method as:
supported_payment_methods:3cfb7f1df0ef7ef707ad213e4850219ed4b4553a96a68b6430359d002acdcafd,card

will result in:

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:

Example:

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:

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
      }
    ]
  }
}
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:

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

If you need helping enabling installments contact [email protected]

Example steps

'{"installments_config":{"rules":[{"brand":"visa","min_installments":2,"max_installments":12},{"brand":"master","min_installments":12,"max_installments":24}]}}'
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:

Fields config example:

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

Usage example

Example steps

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

Custom variables

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

Transaction management through API

WebPay API for capture/refund/void is a REST web service and you will need a HTTP client library (like cURL - http://curl.haxx.se). All API calls are XML documents POST-ed over HTTPS to our test server at https://ipgtest.monri.com

IMPORTANT Parametrize https://ipgtest.monri.com URL, in production mode the subdomain will be different.

An example of such call using cURL from command line may look like this:
curl -H “Content-Type: application/xml” -H “Accept: application/xml” -k -i -d request_xml https://ipgtest.monri.com/action

where request_xml is a XML document that contains data necessary for transaction processing and https://ipgtest.monri.com/action is an URL that responds to certain API call.

IMPORTANT Accept and Content-Type headers must be set to application/xml for all message types.

Capture

After an authorization is successfully made, a capture call must be done to settle that authorization.
Capture XML document is POST-ed to https://ipgtest.monri.com/transactions/:order_number/capture.xml where
:order_number has a value from original authorization.

Document example for capture message may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
    <amount>54321</amount>
    <currency>EUR</currency>
    <digest>e64d4cd99367f0254ed5296d38fad6ce87d3acab</digest>
    <authenticity-token>7db11ea5d4a1af32421b564c79b946d1ead3daf0</authenticity-token>
    <order-number>11qqaazz</order-number>
</transaction>

Digest is calculated in the following way:
digest = SHA1(key + order_number + amount + currency)

You can check digest on this link Calculate Digest

NOTICE Node names are dasherized version of corresponding variable names, ie. underscores are replaced with dashes.

If all values pass validations at our side, transaction is send to the bank and response is returned. That response may look like this:

 {
	:connection=>"close",
	:date=>"Tue, 25 Oct 2011 01:18:37 GMT",
	:location=>"https://ipgtest.monri.com/transactions/845",
	:content_type=>"application/xml; charset=utf-8",
	:cache_control=>"no-cache",
	:x_ua_compatible=>"IE=Edge",
	:x_runtime=>"1.475305", :transfer_encoding=>"chunked"
}

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
    <id type="integer">845</id>
    <acquirer>rogach bank</acquirer>
    <order-number>abcdef</order-number>
    <amount type="integer">54321</amount>
    <response-code>000</response-code>
    <approval-code>38860</approval-code>
    <response-message>authorization OK</response-message>
    <reference-number>898951263</reference-number>
    <systan>83704</systan>
    <cc-type>visa</cc-type>
    <status>approved</status>
    <transaction-type>capture</transaction-type>
    <created-at type="datetime">2011-10-25T03:18:38+02:00</created-at>
</transaction>

New transaction is generated - 201 Created HTTP status code, and it’s location is set in appropriate HTTP header. A client then must parse a body from HTTP response and extract all values from that XML document. Transaction is approved only and if only status is set to approved. All other fields are standard data carried over payment networks. If issuer declines a transaction, status flag is set to decline. In a case of an error, the flag will be set to invalid.

IMPORTANT Do not rely on any output variable except status to determine success of capture.

NOTICE We highly recommend to our merchants to keep a whole response string and to save all parsed values for easier troubleshooting during the integration phase and production later on. The quality of our support depends on availability of these information.

In case of invalid request, service will also return a response with
406 Not Acceptable HTTP status code and XML document in its body. Each offended variable will be printed out along with brief explanation what went wrong. That response may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>Digest is invalid</error>
</errors>

Refund

Purchase and capture messages can be refunded within 180 days. Request XML for this transaction_type is identical to capture example, but now the document is POST-ed to https://ipgtest.monri.com/transactions/:order_number/refund.xml, where
:order_number has a value from original purchase or capture.
Response has identical structure as capture response and all response fields should be treated in the same way.

Void

Void messages are POST-ed to https://ipgtest.monri.com/transactions/:order_number/void.xml, where
:order_number has a value from original message (authorization, capture, purchase or refund). They have identical structure as capture or refund messages.
Response has identical structure as capture response and all response fields should be treated in the same way.

##3D Secure
WebPay handles 3D secure processing for you, this kind of integration doesn’t require any additional programming.

Email notifications

Service can notify merchant and buyer upon successful purchase. Merchant can use this message to track pending transactions and buyer can keep them as reference.
Both can be customized under your merchant account.

Callback

You can set your callback URL under your merchant profile data if you want us to send a POST request with all the transaction parameters for each approved transaction.
POST request is sent to your endpoint in JSON format.
We expect HTTP 200 OK status response code to terminate the job, otherwise we’ll send the data periodically until we re-ceive 200.
Here is a list of parameters included in callback request:

{
   "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}"
}