Transaction management

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)

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:

• HTTP status code: 201 - Created

• HTTP headers:

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

• HTTP body:

<?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.