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 service you will need:
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/ba-hr/login with login and password provided.
WebPay Direct 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.
notice More on REST at http://en.wikipedia.org/wiki/Representational_state_transfer.
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.
Here are the variables and their definitions used when generating XML documents for API calls:
| name | lenght | 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 | 3-30 | alphanumeric | buyer's country |
| ch_phone | 3-30 | alphanumeric | buyer's phone |
| ch_email | 3-100 | alphanumeric | buyer's email |
| name | lenght | format | additional info |
|---|---|---|---|
| pan | 14-19 | integer | valid card number |
| cvv | 3-4 | integer | optional for Maestro cards; must be not set for MOTO transactions |
| expiration_date | 4 | numeric (YYMM) | this value can not be in the past |
| name | lenght | 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 | lenght | format | additional info |
|---|---|---|---|
| ip | 7-15 | alphanumeric | valid IPv4 address |
| 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 or void |
| authenticity_token | 40 | alphanumeric | autogenerated value for merchant account, can be found under merchant settings |
| digest | 40 | alphanumeric | SHA1 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 | alpha | possible value is true or false; missing variable is equivalent to false |
| skip_three_ds | predefined | alpha | possible value is true or false; missing variable is equivalent to false. If set to true 3DS is skipped! |
| force_three_ds | predefined | alpha | possible value is true or false; missing variable is equivalent to false. If set to true 3DS is forced! |
| merchant_initiated_transaction | predefined | alpha | possible value is true or false; missing variable is equivalent to false |
| sca_exemption | predefined | alpha | possible value are LVP (Low value payment), TRA (Transaction Risk Analysis), RP (Recurring Payment), MIT (Merchant-Initiated Transaction), UTT (Unattended transit terminal), ASO (Authentication Service Outage) |
| cit_id | predefined | alpha | Inital customer initiated transaction id from card schemas |
Purchase doesn't need to be approved, funds are transfered in next settlement between issuer and acquirer banks, usually within one business day. These transactions can be refunded within 180 days.
This message has the same structure as authorization request XML document, only difference is in transaction_type tag which has purchase value now. Response has identical structure as authorization response and all response fields should be treated in the same way.
notice purchase message can be refunded within 180 days.
Approved authorization must be captured in order to transfer the funds form buyer's card to merchant. This action can be done through merchant account interface or programatically through an API call. A lesser amount than original authorization amount can be captured, ie. a merchant can make a partial delivery of goods and/or services. Capture must be done within 28 days or will be automatically voided.
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.
important Parametrize https://ipgtest.monri.com URL, in production mode the subdomain will be different.
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>
where digest is calculated the same way as for authorize or purchase messages.
Response has identical structure as authorization response and all response fields should be treated in the same way.
notice capture message can be refunded within 180 days.
Approved purchases and captures can be refunded within 180 days. This action can be done through merchant account interface or programatically through an API call. This is required if merchant cancels the order after transaction is settled, or buyer is not satisfied with delivered goods and/or services. Refunds can be done with lesser amount than original authorization amount.
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 authorization response and all response fields should be treated in the same way.
Approved authorization must be voided within 28 days if merchant cancels the order. This action can be done through merchant account interface or programatically through an API call.
Void messages are POST-ed to 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.
Response has identical structure as authorization response and all response fields should be treated in the same way.
To send a request with installments, number-of-installments tag is added to authorize or purchase XML document. This number depends on merchant's setting in acquiring bank, it's value is a number between 2 and 12
To send a request for moto transaction, moto tag is added to authorize or purchase XML with true value.
If your merchant account has active 3-DS flag under it's settings, all incoming authorize and purchase requests will be processed as 3-D Secure transactions. For cards not enrolled in 3-DS, a regular authorize or purchase response will be returned.
If the card is enrolled, a 3-DS check will occur and appropriate response is returned which may look like this:
<?xml version="1.0" encoding="UTF-8"?>
<secure-message>
<id type="integer">505</id>
<acs-url>https://visatest.3dsecure.com/mdpayacs/pareq</acs-url> <pareq>eJxVUV1TwjAQ/CsMr47NR0s/mCMzRR7EoQ4C+srUcELRtpA2Av/epLa...</pareq>
<authenticity-token>7465c9ab97defa1501ed0e680b3a0b4b88937c17</authenticity-token>
</secure-message>
Client should parse a HTTP body from above example response and extracts acs-url, pareq and authenticity-token values. They are POST-ed through buyer's browser to ACS server at acs-url as follows (this example use javascript to automatically submit the form):
<!DOCTYPE html>
<html>
<head>
<title>3D Secure Verification</title>
<script language="Javascript">
function OnLoadEvent() { document.form.submit(); }
</script>
</head>
<body OnLoad="OnLoadEvent();">
Invoking 3-D secure form, please wait ...
<form name="form" action="acs-url" method="post">
<input type="hidden" name="PaReq" value="pareq">
<input type="hidden" name="TermUrl" value="term-url">
<input type="hidden" name="MD" value="authenticity-token">
<noscript>
<p>Please click</p><input id="to-acs-button" type="submit">
</noscript>
</form>
</body>
</html>
where acs-url, pareq and authenticity-token are substituted with appropriate extracted values.
Buyer will POST the result of 3-D secure identity check from ACS server to term-url at merchant side through his browser. Following data is captured at merchant's term-url:
notice Merchant should implement a listener at term-url that captures response from issuer's ACS server.
The 3-D secure processing is done and merchant now issue a new request to https://ipgtest.monri.com/pares to finish the transaction. Example of such request may look like this:
<?xml version="1.0" encoding="UTF-8"?>
<secure-message>
<MD>7465c9ab97defa1501ed0e680b3a0b4b88937c17</MD>
<PaRes>eJzNmGuvosyygP/KZPZHMy93lYmzkuaOCnJH+LLDTe6ggoD8+t3qrDXrnUxO3rO/nENigKK6urq76qm2N1Z2TR ...</PaRes>
</secure-message>
notice authenticity-token from WbPay is submitted to ACS server in variable MD; then is sent back again to WebPay as MD variable.
WebPay will return response as would for a regular authorize or purchase request messages. Only difference is that eci, xid, acsv, enrollment and authentication fields are now populated in response XML according to 3-DS rules.
Here is the list of response codes and their description: