customer_uuid supportIntegration 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
• HTTP client library if you need to programmatically manage approved transactions through API
If you don’t have a test merchant account, please contact us at [email protected] 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.
You can find a demo on this link Demo Redirect
WebPay Form is a simple web service; merchant should collect data consisted of buyer’s profile and order info at his site and submit that data to https://ipgtest.monri.com/v2/form using HTTP POST method.
IMPORTANT Parametrize https://ipgtest.monri.com URL, in production mode the subdomain will be different.
After a valid request is made to WebPay service, a payment form is presented to the buyer.
Buyer now fills in the card details and submits the form.
Service issues a request for authorization to acquirer bank and redisplays appropriate message if authorization is declined.
If authorization is approved, a redirect is made back to a merchant site.
NOTICE Buyer stays at our side if transaction is declined, form is redisplayed with appropriate message. There is no means to communicate the failure of transaction to merchant at this point.
Optionally, email messages are sent to merchant and/or buyer to notify both sides of successful purchase. This setting is available under merchant account together with custom email templates for outgoing email message.
Authorization is preferred transaction type for e-commerce. Merchant must capture these transactions within 28 days (or this capture period depends on the bank), in order to transfer the money from buyer’s account to his own. This transaction can also be voided if a buyer cancels the order. Refund can be done after original authorization is captured.
Purchase doesn’t need to be approved; funds are transferred in next settlement between issuer and acquirer banks, usually within one business day. These transactions can be refunded within 180 days.
Approved authorization must be captured for the funds to be transferred form buyer’s card to merchant account. This action can be done through merchant account interface or programmatically through an API call. A lesser amount than an original authorization amount can be captured as well, ie. a merchant can make partial delivery of goods and/or services. Capture must be done within 28 days or it will be automatically voided.
Approved purchases and captures can be refunded within 180 days. This action can be done through merchant account interface or programmatically through an API call. This is required if a merchant cancels the order after transaction is settled, or a buyer is not satisfied with delivered goods and/or services. Refunds can be done with a lesser amount than an original authorization amount.
Approved authorization must be voided within 28 days if merchant cancels the order. This action can be done through merchant account interface or programmatically through an API call.
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:
• Authenticity token is unique merchant identifier, can be found under merchant settings
• Key is a shared secret used to calculate digest value
• Success URL is an URL at the merchant site where a buyer is redirected after approved authorization.
• Cancel URL is an URL at the merchant site where a buyer is redirected if cancel link is clicked at payment form
• Redirect to success URL should be set to true if merchant parses the data carried in redirect to success URL, ie. a listener will wait for this request and update order status.
• Callback URL should be set under merchant profile if the merchant wants us to send POST request message for each approved authorization
IMPORTANT Parametrize these values for API settings, we strongly advice a merchant to have both, testing and production environments.
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)
This request may look 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¤cy=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
Returned digest is calculated as SHA512(key+success_url without digest). You must check for this value at merchant application before updating status of transaction because malicious user can forge this URL.
You can check digest on this link Calculate Digest
Returned digest is calculated using following formula:
digest = SHA512(key + succesURL(without DIGEST))
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¤cy=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¤cy=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
IMPORTANT Success URL should expire after some sensible amount of time or protected using session.
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}"
}
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.
The following variables are interpolated into body of each email template:
• FULL_NAME
• ADDRESS
• CITY
• ZIP
• COUNTRY
• PHONE
• EMAIL
• CARD_ISSUER
• AMOUNT
• ORDER_NUMBER
• ORDER_INFO
• CC_TYPE
• DATE
• SUCCESS_URL
• DOMAIN
Email template to notify the buyer may look like this:
Thank you for your business!
Credit Card Owner: ------------------
name: FULL_NAME
address: ADDRESS, CITY, ZIP, COUNTRY
phone: PHONE email: EMAIL
card issuer: CARD_ISSUER
Order Details: ------------------
order amount: AMOUNT
order number: ORDER_NUMBER
order description: ORDER_INFO
payment type: CC_TYPE
date: DATE
order url: SUCCESS_URL
Please come again!
Store adress: DOMAIN
NOTICE SUCCESS_URL has the same value as URL generated for redirect to success URL after transaction is approved. It should expire after some sensible amount of time or protected using session.
Here are the definitions of variables which are submitted to WebPay form:
| name | length | format | additional info |
|---|---|---|---|
| ch_full_name | 3-30 | alphanumeric | buyer’s full name |
| ch_address | 3-100 | alphanumeric | buyer’s address |
| ch_city | 3-30 | alphanumeric | buyer’s city |
| ch_zip | 3-9 | alphanumeric | buyer’s zip |
| ch_country | 2-3 | alphanumeric | buyer’s country in alpha2, alpha3 letter code or 3 digit ISO numeric code |
| ch_phone | 3-30 | alphanumeric | buyer’s phone |
| ch_email | 3-100 | alphanumeric | buyer’s email |
| customer_uuid | 20 | alphanumeric | An id of a customer. Check documentation how to create a customer. |
| name | length | format | additional info |
|---|---|---|---|
| order_info | 3-100 | alphanumeric | short description of order being processed |
| order_number | 1-40 | alphanumeric | unique identifier |
| amount | 3-11 | integer | amount is in minor units, ie. 10.24 USD is sent as 1024 |
| currency | predefined | alpha | possible values are USD, EUR, BAM or HRK |
| name | length | format | additional info |
|---|---|---|---|
| language | predefined | alpha | used for errors localization, possible values are en, es, ba or hr |
| transaction_type | predefined | alpha | possible values are authorize, purchase, capture, refund, void |
| authenticity_token | 40 | alphanumeric | auto generated value for merchant account, can be found under merchant settings |
| digest | 40 | alphanumeric | 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 | range 2-12 |
| moto | predefined | boolean | possible value is true or false; missing variable is equivalent to false |
| name | length | format | additional info |
|---|---|---|---|
| tokenize_pan_offered | predefined | boolean | 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. |
| supported_payment_methods | predefined | comma separated 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 | tokenize pan without prompting the user |
| tokenize_brands | predefined | comma separated list of card 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. |
| supported_cc_issuers | predefined | comma separated card issuers | provide this value if you want to limit payment to the card to certain issuer(s) |
| rules | predefined | comma separated rules | provide this value if you want to apply custom rules |
| force_installments | predefined | boolean | provide this value if you want to force payment on installments. For more details refer to the force_installments documentation |
| custom_attributes | predefined | valid JSON string | provide this value if you want to customize form behaviour. Refer to the custom attributes section below for more details. |
| success_url_override | predefined | valid HTTPS URL | provide this value if you want to override success URL |
| cancel_url_override | predefined | valid HTTPS URL | provide this value if you want to override cancel URL |
| callback_url_override | predefined | valid HTTPS URL | provide this value if you want to override callback URL |
whitelisted_pan_tokensSimply replace key whitelisted_pan_tokens with a key supported_payment_methods and you are good to go!
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:
3cfb7f1df0ef7ef707ad213e4850219ed4b4553a96a68b6430359d002acdcafdTo limit payment to the card with certain issuer(s) simply provide comma separated list of supported card issuers for payment.
An example would be:
supported_cc_issuers=zaba-hr,ucbm-ba,rba-hr
Transaction is declined if the buyer enters unsupported card (the card issuer is not one of supported issuers).
For full list of supported issuers contact [email protected].
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.
Currently Rules functionality is in BETA phase. If you are interested in using custom rules please contact us at [email protected]
To force payment on installments use force_installments option.
Supported values are: true or 'true'. If you provide false or omit value then default value is false.
Buyer is forced to select one of provided installment options and is unable to pay one-time.
NOTE
Force installments only work if installments are enabled on merchant profile.
An error is raised if you try to force payment on installments for merchant without enabled installments.
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:
visamastermaestrodinersamexjcbdiscoverExample:
tokenize_pan_offered to truetokenize_brands to master,maestro (comma separated values)mastercard or maestro card number in card number field
Save card for future paymentspan_token value is added to success_url if redirect to success url is enabled in merchant profilevisa, diners, discover or amex card number in card number field
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_configfields_configExample:
{
"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
}
]
}
}
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
Array<InstallmentsConfigRule>rulesInstallmentsConfigRule
visa,master,maestro, diners, amexInstallments 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}]}}'
visa or master card number in card number field
visa is entered installmentsone time payment (jednokratno) and then from 2 to 12 installments.master is entered installments selection is one time payment (jednokratno) and then from 12 to 24amex (eg 3704 387472 13977) in card number field
one time payment - jednokratnoCard 'amex' not supportedUsed 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
Array<FieldConfig>FieldConfig
ch_email,ch_full_nametrue or false. Field is readonly for input only if initial value is provided and validFields 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}]}}'
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.
Digest is calculated using following formula:
digest = SHA512(key + order_number + amount +currency)
You can check digest on this link Calculate Digest
With the following example data
• key: 2345klj
• order_number: abcdef
• amount: 54321
• currency: EUR
the digest formula gives a result as follows:
digest = SHA512.hexdigest(2345kljabcdef54321EUR) =>
f71b8c1560bd7511ba2f0307b3823c06dd39042cd77480543e3d7bf9f3eefa6debed252979ba8edc7a82d9f111d90f8e31c1c7ab5af39796b26e59a0b2d7cf98
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.
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>
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 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.
Form will automatically recognize cards which are eligible for payments in installments. Installment range setup will be defined by the merchant-acquirer agreement.
WebPay handles 3-D secure processing for you, this kind of integration doesn’t require any additional programming.
For easier integration we provided a demo client. Turn on the debug mode in API settings under your merchant account to activate the client. A link to client is available upon activation.
Append /success to that link and set as success URL if you want to see how those page could look like.
Custom headers, footer and custom CSS support are currently disabled, due to introduction of new form templates.