DISCLAIMER

Maksu disclaims all warranties and conditions with regard to the Products described in this document or other Maksu products, including all warranties and conditions of merchantability, whether express, implied or statutory, fitness for a particular purpose, title and non-infringement.

Maksu Development does not warrant that the Product shall satisfy customers’ specific requirements, or that copies of the Product other than those provided or authorized by the Maksu shall possess functional integrity. Also, Maksu makes no warranties with respect to the fitness and operability of modifications not made by Maksu

Maksu makes no warranties as to the accuracy of the information in this document. The information is based on the knowledge and information available in the time of issue and is subject to change without any notice.

LIABILITY

In no event shall Maksu be liable for any loss or damage to revenues, profits or other incidental, indirect and consequential damage of any kind, resulting from use of Product or Product’s performance.

CONTACT
Any enquiries relating to this document should be directed to:

Maksu GMBH
Millennium Tower, 23rd and 24th Floor,Handelskai 94-96
AT-1200 Vienna
AUSTRIA
E-mail: support@Maksupay.com

1.0. Overview

Maksu VPOS is a payment application that is designed for processing merchant payments in e-commerce environment. The inputs to VPOS are requests from merchant shopping solution and from there the payment process is controlled by VPOS until the payment has completed successfully or failed and the information will be sent back to merchant shopping solution.

The payment methods available will depend on area application will be used and which are necessary for the client business model. It could have enabled credit and debit card payments that are also integrated with

Integration with 3D Secure server technology or external payment methods like net payments in shopper local banks and so on. Exact payment methods available should be specified by client and setup.

Maksu VPOS core design enables multiple types of merchant interfaces to be implemented and also the easy to implement secure default interface.

Merchants can easily attach their look and feel to payment pages by supplying their own custom CSS stylesheet.

This document describes newest version 5.0 of interfaces to date based on RSA SHA256 signature security (5.0).

Payment services provide by Maksu include but not limited to following option:

• MasterCard, VISA, American Express (ask availability), GooglePay™, ApplePay™,
• 3D-Secure and many local payment methods by banks and wallets in Europe and elsewhere.

1.1. Security notes

VPOS merchant interface delivers great level of security. Messages are signed and verified with 3072 bit RSA Keys. Client side encryption also uses 3072 bit RSA public key to encrypt cardholder and PAN in user browser..

1.2. Changes recorded:

1.0 26.09.2024 Intitial version of V5 interface documentation
1.1 30.09.2024 – Added 3DS API desciptions
1.2 23.12.2024 – Some content fixes
1.3 28.01.2025 – orderDesc, var1..9 lengths to 4000 supporting items.
1.4 25.03.2025 – Using GooglePay™ with Maksu API, small API naming adjustments.
1.5 11.04.2025 – Document structure changes, Sandbox and production endpoints.

2.0. Intro

Communication between Maksu VPOS and Merchant shopping cart software can be implemented via HTTP post protocol following the specification below.

2.1. Merchant shop requests to initiate payment with Maksu VPOS

Endpoints:

Production: https://pay.eu.maksupay.com/vpos/shophandler
Sandbox: https://pay.test.maksupay.com/vpos/shophandler

The following table describes the parameters of the POST from the payment page to VPOS.

If extension parameters extInstallmentoffset, extInstallmentperiod are present and valid then the request in considered an installment payment (parent).

If extension parameters extRecurringfrequency, extRecurringenddate are present and valid then the request in considered an recurring payment (parent).

All parameters in the post must be in form default encoding (application/x-www-form-urlencoded) and form must be submitted with utf-8 encoding.

form.action="{supplied vpos service url}"
form.method="POST"
form.enctype="application/x-www-form-urlencoded"
form.accept-charset="UTF-8"

2.2. VPOS return message POST to inform merchant shop about payment success or failure.

The following table describes the parameters of the POST from VPOS back to merchant shop.

Note: When payment is success the message is returned to url provide by merchant confirmUrl parameter in request. If payment fails or is canceled the message is returned to cancelUrl parameter provided in merchant request.

Note2: There is also available configurable option that server sends in background delayed  (5..120 seconds) independent confirmation message (copy of redirection confirmation) to merchant server without user browser interaction as sometimes user browser may fail to reach back to merchant site. So it is recommended that merchant systems are prepared to handle multiple confirmations for same order properly due this feature and also possible user browser reloads, back buttoning etc. Background confirmation http request can be identified by having user-agent header set to value “Maksu VPOS”

2.3. Recurring notification POST

The following table describes the parameters of the direct POST from VPOS back to merchant shop (recurring notifications url) in case of scheduled recurring child is processed by VPOS server.

2.4. Calculation of the Signature

The signature in the incoming POST and in the return POST is calculated by the following rule.

1. Concatenate all the values of all the possible non empty fields listed in the table, the same order as parameters are listed in table and having ; at the end of each added field. If a parameter is omitted or empty nothing is concatenated.

Version 5:

2. Calculate RSA with SHA2-256 signature of step 1 (using of UTF-8 char encoding when converting
string to bytes) using Your private key.
3. Return the signature
4. Encode signature bytes with Base64 encoding signature=base64(RSA with SHA2-256( utf8bytes(value1;value2;…;value n;) ) )

Note: ‘;’ is separator between values concatenated and at the end of last value.
If optional value is missing or empty do not add any value and no separator as well.
Never implement the signature calculation in browser using javascipt or similar as this way you expose your private key to the world. Only implement it ins server side executed code as (jsp/servlet/asp/php etc).

2.5. Payment statuses in response message

AUTHORIZED, CAPTURED – payment was successful (accept order)
CANCELED – payment failed, user canceled the process (deny order)
REFUSED – payment failed, payment was denied for card or by bank (deny order)
REFUSEDRISK – payment failed, payment was denied for card by risk score (deny order)
ERROR – non recoverable system or other error occurred during payment process (deny order)
COMPLETED – tokenization only completed successfully

2.6.1 With openssl

Its just possible to do all in one line:

openssl req -x509 -newkey rsa:3072 -sha256 -keyout merchantkey.pem -out merchantcert.pem -days 365 -subj "/C=EE/ST=My State/L=my City/O=Company Name/OU=7711223/CN=www.mysite.com"

The output file merchantcert.pem need to be sent to service provider to install with Your merchant account so Your messages will be validated with public key in Your certificate.

C – is two letter country code
L – locality eg. city where you are located.
OU – is recommended to fill with Your merchant number with service provider.
O – shall be your company full or public name.
CN – is recommended (not required as with server certificates) to be your website name
rsa:keysize is recommended to be 2048 or 3072 bits for foreseeable future and validity days up to 1460 days (4 years), ask service provider if it has specific policy or requirements.

Use necessary measures to protect your private key in generated file merchantkey.pem.

Converting private key to PKCS8 format handleable by java:

openssl pkcs8 -topk8 -in merchantkey.pem -inform PEM -outform PEM -out merchantkey-p8.pem -nocrypt

2.6.2 With java keytool
With java keytool private key remains in keystore and cannot be extracted unless special software is used. So Your software shall operate directly with this keystore then.

keytool -genkey -keyalg RSA -sigalg SHA256withRSA -dname "CN=www.mysite.com,OU=7711223,O=Company Name,L=My City,S=My State,C=EE" -keysize 3072 -validity 1460 -alias mykey2025  -storetype PKCS12 -keystore mykeystore.p12 -keypass strongPassKey -keystore mycerts.p12 -storepass strongPass

Now export Your certificate to a file that can be sent to service provider:

keytool -exportcert -alias mykey2025 -file merchantcert.pem.cer -storetype PKCS12 -keystore mycerts.p12 -storepass strongPass -rfc

2.6.3 Maksu backoffice

Maksu backoffice for merchants also has tool to generate merchant signing keys with few clicks.

In merchant main page click “Generate” button to generate new signing private key and public key to be stored in Your Maksu account to verify Your signed messages.

2.7.1.  Special data cases

Some payment methods may require order item and tax details. To send such info use var1..va9 fields in format, then use prefix “items:” and values is JSON array of item objects, for example as follows

items:[{“t” :”p”, “n” :”Dennis ball”, “c” : “1234001”, “q” : 2 , “qu” : “pcs”,“up” : 100, “tp” : 200, “tt” : 36, “tr” : 2200},
{“t” :”st”, “n” :”VAT 22%”, “c” : “vat22”, “q” : 1 , “qu” : “%”,“up” : 2200, “tp” : 36, “tt” : 36, “tr” : 2200]

Fields:
t – means type :
p – physical, d-discount, sf -shipping fee, st – sales tax, d – digital , g – giftcard, sc – store credit,
s – surcharge, su – subscription
n – means product name
c – means product code
q – means quantity
qu – means quantity unit eg pcs or m etc
up – unit price eg 100 (in cents, includes tax)
tp – total price eg 200 (in cents includes tax)
td – optional total discount amount (in cents)
tt – total tax (eg vat included)
tr – tax rate eg tax prsentage 2200 means 22%
if type=sc
spi – subscription interval (“DAY” “WEEK” “MONTH” “YEAR”)
sbic – subscription interval count

Recurring control:
rcauto:false
if merchant wants self submit executions of recurring payments instead of auto scheduling can submit this flag in
var1..var9

Mail telephone order:
moto:true
If merchant wants to initiate mail telephone order instead of ecommerce then can submit this flag in var1..var9

3. XML/JSON API Interface

The XML/JSON API interface plugin makes possible that merchants with their own payment pages hosted in their system to use e-commerce services provided by VPOS using XML or JSON messaging.

XML/JSON Messaging is using request real time and response messages in the same request/response cycle. In request message merchant provides payment and order info and in response messages VPOS indicates the result of the action performed. By default the merchant should receive the response message within 30 seconds maximum.

Root element of request and response messages is VPOS

Current version of XML/JSON API is 5.0

The request message general structure:

<VPOS xmlns="http://www.modirum.com/schemas/vposxmlapi5" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
	<Message id="M1727355916647" senderId="200002" ts="2024-09-26T13:05:16.647Z" version="5.0">
		<SaleReq merchantId="200002">
			<OrderInfo orderId="O1727355899011">
				<OrderDesc />
				<OrderAmount>1.25</OrderAmount>
				<Currency>EUR</Currency>
			</OrderInfo>
			<PaymentInfo>
				<PayMethod>visa</PayMethod>
				<Card>
					<Pan>4016360000000010</Pan>
					<ExpDate>2712</ExpDate>
					<CVV2>756</CVV2>
					<HolderName>John Smith</HolderName>
				</Card>
				<PayerEmail />
				<PayerIpAddress>172.29.0.1</PayerIpAddress>
			</PaymentInfo>
		</SaleReq>
	</Message>
	<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
		<ds:SignedInfo>
			<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
			<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
			<ds:Reference URI="#M1727355916647">
				<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
				<ds:DigestValue>NuDrebbMO7lzCWN5pypq5pLde9huVxRYUrOzu0UGNJE=</ds:DigestValue>
			</ds:Reference>
		</ds:SignedInfo>
		<ds:SignatureValue>
rCgl9cFMYDsbro2acdbTCme0n4OK2cDTQxbug7ZHI5R1Nveyu1mb+h8aOZAm6Jhn2rc3OJeD3Qky
QMQ7QRKzCD4HQIPwpaBoI4Kk6PFwwk3aD/s9+WWfeJQVpZnRqcDZOlKdeoMvrHj6PYSBqGUIKtT2
/tKw6ygwcvnX5SBiVO5gZo4DReY8f+GOOBlLfqNFHtyVG+HTUATagpKzEiQBLlDuVsWksGkN5jk+
oFwoYlev8qB2f4niQEKFcT/KN16WszVlkVnRVcJvl8u7IGKhTv7wfzqnb/AXbf/Qq7n1uAioLbLF
RE25mHVt6z1138xkX6rlBbeQ4D/HU8SZSiXaDg==
		</ds:SignatureValue>
		<ds:KeyInfo>
			<ds:X509Data>
				<ds:X509Certificate>
MIIDxzCCAq+gAwIBAgIUDBt1MUWfMQnotsdXcrZ387CY4oQwDQYJKoZIhvcNAQELBQAwczELMAkG
A1UEBhMCRUUxCzAJBgNVBAgMAkhNMRAwDgYDVQQHDAdUYWxsaW5uMRMwEQYDVQQKDApNYWtzdSB0
ZXN0MQ8wDQYDVQQLDAYyMDAwMDIxHzAdBgNVBAMMFnZwb3N0ZXN0cy5tYWtzdXBheS5jb20wHhcN
MjQwNDMwMTE1NDA5WhcNMjgwNDI5MTE1NDA5WjBzMQswCQYDVQQGEwJFRTELMAkGA1UECAwCSE0x
EDAOBgNVBAcMB1RhbGxpbm4xEzARBgNVBAoMCk1ha3N1IHRlc3QxDzANBgNVBAsMBjIwMDAwMjEf
MB0GA1UEAwwWdnBvc3Rlc3RzLm1ha3N1cGF5LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC
AQoCggEBAL81CItSrfk12TTOviXKXy+YQXker6UkpzTDf2ekzGpzA56fbZGgNnweby/RvZ2yGlSn
KoInWl0oZ8vLHDXXMpsdnAqL8MwOvbVN0otRTZ1W36Ca65e/0l2kTDwjTtl9CHaIYxN3F9vq9dlA
Y3euGpb0O6gBzGxCr2XIxHoGadB5vEfX9bfMYgswXYWOFxsAEu+lS4uo8bVa+L9reH0cU6aRbfMw
rzdSvUn/KazECN2VIXD7QPckkV8tksrj0hB38yMa188iU9vpZ1oePS662tQRkxjAsm4LcM4/3w18
Y/ky0emEWn14p/Yza0IWY1L04SrCEH4EPWKRSzy+RQixLT0CAwEAAaNTMFEwHQYDVR0OBBYEFMYo
d11iUYfyLbLd4HnF3tJwVkVlMB8GA1UdIwQYMBaAFMYod11iUYfyLbLd4HnF3tJwVkVlMA8GA1Ud
EwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAEB5FYdHlSDdrHdAJIsZMN1IuSDthH8dE1tv
HBZ5krHwwpXLBNMiyUaFC4G/f07dXpz9lRhgL25nMOM5mCHVCfTZ/FFTMaJdQi4yZcS9hZjkZwqp
pGp0+G8tGhI/bPW8n4tFnk1HK0FN9/d2jv1qqsWaIUdpHed7uz5OXMkzDdPjb8eO/QjfnJBHN+rm
z1UPvGN0cWATBNkbLiHkWvVM94Z+gVJGv9CnJCdn6xMD5O6uhkYn51LRYTb/yAyuyKhl9mY43U3G
A+/5r2UXQ3Ec8dhNNxvhr1WkQb0Hvuw6vpTf4BRy5MH/ermH5BJpFDoDNpJYUiSl+lxvCctsfNjJ
Xwo=
				</ds:X509Certificate>
			</ds:X509Data>
		</ds:KeyInfo>
	</ds:Signature>
</VPOS>

The response message general structure:

<VPOS xmlns="http://www.modirum.com/schemas/vposxmlapi5" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#">
	<Message id="M1727355916647" senderId="C=EE,ST=HM,L=Tallinn,O=ChaosPay,OU=E-COM Signer,CN=ChaosPay E-COM Signer 2024-01"
		ts="2024-09-26T13:05:17.101Z" version="5.0">
		<SaleRes errorCode="SE" orderId="O1727355899011" status="ERROR" txId="0">
		<Description>Unexpected system error id 1727355917065</Description>
		</SaleRes>
	</Message>
	<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
		<ds:SignedInfo>
			<ds:CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315" />
			<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
			<ds:Reference URI="#M1727355916647">
				<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
				<ds:DigestValue>Dbg+Kja0oQcSwTlThv9UeZzpTrzA9FmGsjik+EHh0Fs=</ds:DigestValue>
			</ds:Reference>
		</ds:SignedInfo>
		<ds:SignatureValue>
rFhOMahqaMNDKcoAb5xf4QmXMDkUKvk2oeUmWI3A2NKnEIjafs3kA51/38i92GhT1+KRtR8qJKmd
qrytSqdNCr3CwYdhlGB2RyZrUE/zhSHUxWXFqrpFVH+Ikb4EYJ2ytakDrG7XzMdyJu9YKMsnakHB
W6xXyRJkC/P3b90R6myaQJRFJemGXGu75wJ/R+qmF6S5V/eRS2l18YuNX/3qMtINWQNALPfftxLQ
0ZKKNwT44XIU1GspK8jevPXmV52JkvSE+3uGu3a5t7RD8/7jgOgHa4yNeT7Zbe5OrCLlZsoW6Ypg
yyVmipG8UEH+h9lhSWIDn/+oeRO6BckuDKZL8FWxuFrA/GUdfWqbnznNrrA30jQEFhRrxVgGhN6g
PFnEgXPwUSvQLuYcNXryTR3wT3Ndi+Wsc3hvlfl4Ah6HbZMmu5S9m/+5AIqb6lDxsB4AGxDBi7UG
3jVswAq1uK0zGZPiPPtQGJ/J8wQ1tmJCx1Bb9ssESEQneYfRC1txM01f
		</ds:SignatureValue>
		<ds:KeyInfo>
			<ds:X509Data>
				<ds:X509Certificate>
MIIEczCCAtsCBGWfmh4wDQYJKoZIhvcNAQELBQAwfjEmMCQGA1UEAxMdQ2hhb3NQYXkgRS1DT00g
U2lnbmVyIDIwMjQtMDExFTATBgNVBAsTDEUtQ09NIFNpZ25lcjERMA8GA1UEChMIQ2hhb3NQYXkx
EDAOBgNVBAcTB1RhbGxpbm4xCzAJBgNVBAgTAkhNMQswCQYDVQQGEwJFRTAeFw0yNDAxMTEwNzM0
NTRaFw0yODAxMTAwNzM0NTRaMH4xJjAkBgNVBAMTHUNoYW9zUGF5IEUtQ09NIFNpZ25lciAyMDI0
LTAxMRUwEwYDVQQLEwxFLUNPTSBTaWduZXIxETAPBgNVBAoTCENoYW9zUGF5MRAwDgYDVQQHEwdU
YWxsaW5uMQswCQYDVQQIEwJITTELMAkGA1UEBhMCRUUwggGiMA0GCSqGSIb3DQEBAQUAA4IBjwAw
ggGKAoIBgQDI/pOZUHHlatYS/MV0i+xEMQE96tVFdRdbBesVa1P4Y1eiXITdvz5+8c2LEiBbYY6J
If4AHst0PuFlJSCYPBalEWNJTQCFOw09fHY9D3qhPoIixOM7WD46PGxbwU+Ld9y5ZfNthg+HBQ+F
OUCVcmXZ/id51FoyldValPlyjzea/5ydNhukfxIKG4zsDOa5Nn/EP2sS17MSMtTeDQbNT75asLTP
CURueVXDgAZDwTD4J3uGER4hxMAw/ybd32X0PA+MCMmNAUuLkWI1Y6SpRGELr8yFTnIYrvsFuoPM
qToLklq+E7YoJlWrDgdDXc3rGW5fu+Rk1NPRw8G6+tulkA416u2lOX5LaQkcA8ZQ3ZFHVegw7XUf
NmMycw2ofKTS5HA3nMwG4Ajr441PefTel0tKnX3qIJkBeBBTsUN+tPH7eZwz++Diru/oi435UFLg
zKdxfMc/KvjoEFw5nI1P2PZmKXnLfZbhqWxanKADzL1MRhrjCWJNo//B6puJasGDgoUCAwEAATAN
BgkqhkiG9w0BAQsFAAOCAYEAPTN5kuS/I6nsE5jBIr7zaxV7UM+ooSEdzFme6A83VvBIxJztyLMr
7kYJX6NQFbCSjIWdFs9uppKqW19VdutAhPrtLZHohdrWKHtEQOVppuarU8pNp2+MR5CAW9FmbJww
QAvh5BwJfmgIOUC+WZ5CCR5KEdPcizJwQV3j8iddysEyrdAUYetE/unZv291JtvpmTJpGu9nnb/r
cCLqbfCT/3mdxQ+idYvGCSKbEkPYfnlWm3rK9Z+BnRqsMHxmteDYlB6EHdNLzOzf/N3IKkwxrtld
Cm5VLx2XbvpP40vBs48yny++I+4aa2dhMAJNlg4YMtB1fRbJI7A9IBxWRuNQwX1wAX6mnyOF3loO
+KlCV5jezX7TjA97GTrSR0O4Zr0w3S1D4/dDctnlnOfQlE3/sFyTmzjwNoMzgBxhlhcRU6Tohb27
HJDV0yJRb27dX9SowapkUIKYhJ+zAxkWaIU3uHPAOiWp73e7p5yPCvRoYjZZDlKyGi1l2iOh+iGk
B3rI
				</ds:X509Certificate>
			</ds:X509Data>
		</ds:KeyInfo>
	</ds:Signature>
</VPOS>

The general error message structure (returned in case request: message was unparseable or unvalidatable)

<VPOS>
	   <Message version="5.0" id="12345">
		<ErrorMessage>
			<ErrorCode></ErrorCode>
			<Description></Description>
			<OriginalXML></OriginalXML>
		</ErrorMessage>
   </Message>
</VPOS>

The exact xml bindings are defined in xsd schema.

https://pay.test.maksupay.com/vpos/xsd/VPOS5.xsd

Description of request and response message elements and fields and their usage:

Note JSON messages are identical to XML except element attributes are then JSON objects and properties respectively. Also JSON messages missing Signature object as this is sent in http headers and calculated over message body being posted

3.1. Payments API

Endpoints both XML or JSON:

Production: https://pay.eu.maksupay.com/vpos/vposapi

Sandbox: https://pay.test.maksupay.com/vpos/vposapi

Table of field requirements depending on messages:

R – required, O-optional, C-conditional

StatusRequest/StaturResponse

O¹  – if supported feature then fields may not need to be present if not supported then the fields are required. Availability of this option shall confirmed with system administrator (Your customer support). If values not sent then whole PaymentInfo element shall be excluded from message.

R² and O² –  If system supports and merchant is set tp participate in returning customer recognition extension then if merchant already has a successful order with a card with this customer and the card is still valid and customer chooses to make this next order with same card and the days and amounts between orders are in certain limits then merchant may send ExtXOrderId instead of CardPan. In such case if validations are passed system automatically uses pan from previous specified order. Recommended maximum period between previous order and next returning customer extension order could be 6 months (180 days).

R³ if acquirer/processor has set up so then PayMethod may be omitted. Default required and recommended.

Currently supported operations:

AuthorisationReq                     -make a pre authorization

CaptureReq                              – capture a pre authorization

RefundReq                               – make refund

SaleReq                                   – make a payment

CancelReq                               – make reversal for an unsettled transaction

RecurringOperationReq           – with operation Cancel, cancel recurring master scheduling

RecurringNotification – Optional message posted to merchant if a recurring child is executed on server, merchant does not need to send response XML to this on accept merchant server should respond with http status code 200/OK or in case merchant does not recognize the transaction 406/Not Acceptable or 400/Bad Request if the message format is invalid. Server just acknowledges the response code and performs no additional actions based on merchant response code.

StatusReq                            – query transaction status

TokenizationReq                – tokenize a card to token

DeTokenizationReq                       – de tokenize a token back to card date

Error code values:

Filled in case status is ERROR  with following values

M1 – Invalid merchant id

M2 – Authentication failed (wrong password or digest or signature)

SE – System error (message contains error id, system or configuration error to be investigated)

SD – Service disabled (service disabled)

XE – Invalid XML/JSON request not parseable or does not validate

I0 – Invalid or unsupported request

I1 – Message contains invalid data item or missing required item

I2 – Message contains invalid installment parameters

I3 – Message contains invalid recurring parameters

I4 – Message contains invalid or mismatching card data

I5 – Message contains invalid expiration date card data

I6 – Selected payment method does is not supported or not matching the payment card

O1 – Operation is not allowed because logic is violated or wrong amounts

O2 – Original transaction is not found to perform operation.

May be also filled in case of status is REFUSED

with acquirer network supplied ISO response code

4.0. Intro

The XML/JSON API interface plugin makes possible that merchants with their own payment pages hosted in their system to use e-commerce services provided by VPOS using XML or JSON messaging.

XML/JSON Messaging is using request real time and response messages in the same request/response cycle. In request message merchant provides payment and order info and in response messages VPOS indicates the result of the action performed. By default the merchant should receive the response message within 30 seconds maximum.

Root element of request and response messages is VPOS

Current version of XML API is 5.0

The request message general structure:

The response message’s general structure:

The general error message structure (returned in case request: message was unparseable or unvalidatable)

The exact xml bindings are defined in xsd schema.
https://pay.test.maksupay.com/vpos/xsd/VPOS5.xsd

Description of request and response message elements and fields and their usage:
Note JSON messages are identical to XML except element attributes are then JSON objects and properties respectively. Also JSON messages missing Signature object as this is sent in http headers and calculated over message body being posted.

4.1 Payments API