Maksu VPOS 3.0 Merchant integration

Redirection version 5, XML/JSON API5 | Revision 1.5 | 11.04.2025

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.

Special data cases

2.7.1. Order items

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

3.2 3D-Secure API

Maksu 3DS Secure API facilitates 3DS 2 authentication via its simple API to utilize 3DS Server services.

Endpoints both XML or JSON:

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

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

Messages structure is identical to Payments API except the functional messages used are different.

Status values in for authentication request responses:

            INITIAL – authentication initialization stage, use ThreeDSMethodContent and include to payment page.

            NOTDSMETHOD – no three ds method for card, continue with authentication flow

            INTDSMETHOD – internal status, authentication in 3ds method (not returned in message)

            INTDSMETHODC – authentication in 3ds method, continue to authentication flow

            INAUTH – internal status that authentication  in porgress (not returned in message)

            REJECTED – authentication failed with reject status “R”

            AUTHFAIL – authentication failed with not authenticated “N” status

            AUTHWALLET – applicable response when wallet date used to check 3ds reuirements,  this status meaning wallet had 3ds cryptogram and not 3ds needed.

            UNAVAILABLE – authentication failed with unavailable “U” status

            CHALLENGE – authentication challenge was requested, use ACS redirect content to redirect user to authentication at issuer ACS.

            COMPLETED – authentication completed with fully authenticated “Y” or attempt “A” astatus.

            ERROR – error found or occurred in processing or validating data.

3.3 Signature calculation with XML API V5.0

Signatures shall be calculated and verified according to documentation https://www.w3.org/TR/xmldsig-core/
Canonicalization method to be used is http://www.w3.org/TR/2001/REC-xml-c14n-20010315
SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig-more#rsa-sha256”
DigestMethod  Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256”
The signed element is Message element referenced with its ID attribute named id.
ID attribute is an attribute which type in schema is defined as xsd:ID.

Messages sent by merchant are signed by merchant private key and verified with merchant certificate public key.
Messages sent by VPOS processor service are signed by service provider private key and validated with service provider provided certificate public key.

The canonicalization method to be used is
http://www.w3.org/TR/2001/REC-xml-c14n-20010315

Note that the XML documents should be handled with namespace aware xml libraries (parser/serializer).
When the Message element is serialized and canonicalized it should contain xmlns namespace attribute.
See from next section XML message with digest/signature example.

Note for XML/JSON API with Three D Secure:
This is 2 step processing at first step merchant should implement 3DS api session as described in  4.2 3D Secure API  and obtain the Three D Secure authentication results from there and then next step is to  fill the corresponding values to XML/JSON API ThreeDSecure element and proceed with XML/JSON api payment request to VPOS.

3.4.1 Using VPOS client side encryption for API messages

Merchants who want to use option of browser RSA card data encryption need to import service provider javascript to their payment page.

Client side encryption java script is to be imported from url like:

Production:

<script type="text/javascript" src="https://pay.eu.maksupay.com/vpos/csescript.js?version=5&mid=1234567&date=201804271539&signature=xxxxx”>

Sandbox:

<script type="text/javascript" src="https://pay.test.maksupay.com/vpos/csescript.js?version=5&mid=1234567&date=201804271539&signature=xxxxx”>
</script>

with following query parameters to authenticate request

Make sure url parameters are properly urlencoded in url and not encoded when calculating signature.
To capture user entered card data merchant needs to create a form with following inputs

<form name=”dummyInputs” action=”https://neversumbit.this/neversumbit.this”>
	  Card number: <input type=”text” id =”card.pan” size=”20” maxlength=”40”/><br/>
	  Expiration <select id=”card.expiryYear”> with year options from now  to now +20 (2018..2038)</select>
	  <select id=”card.expiryMonth”> with month options 01..12</select> <br/>
	  Name on card: <input type=”text” id =”card.holderName” size=”20” maxlength=”40”/><br/>
  CVV2 <input type=”text” id =”card.cvv2” size=”5” maxlength=”5”/>
</form>

Important: inputs and selects must be without name attribute and that form must never submitted to server.
To capture encrypted card data merchant shall call script function

var results=getEncryptedCardData(cvvRequired, nameRequired)

if parameter cvvRequired or nameRequired is false then input of this value is not required)

in return of function call merchant receives an  object with properties.
If exists element ‘cardEncData’ in result object (results[‘cardEncData’] then inputs were considered valid by format  and encryption was successful and merchant shall take this value and proceed to XML api payment in server side. Optionally results[‘cardType’] contains information about card type detected.

If merchant system captures inputs independently then it can use equivalent method encryptCardData with parameters passed independently of input means

var results=encryptCardData(cardPan, cardExpiryYear, cardExpiryMonth, cardCvv2, cardHolderName, 	cvvRequired, nameRequired)

Or if its used with combination of existing token from tokenization and only CVV need to be captured can be used function

var results=encryptCVVOnly(cardCvv2);

In case of input or other errors merchant can extract following error from result using keys/properties and display them user if needed

errorPan		(value "Card number must be number with length 12..19")
		errorExpiryYear
		errorExpiryMonth
		errorCvv2
		errorHolderName
		errorCardEncData 	in case of encryption error.
		errorDebug		error details in case of encryption error.

3.4.2 Browser client side card data encryption for API messages with included PSP iframe

In case security is first priority then even more recommended approach is that merchant site includes iframe with card input fields from service provider. Such iframe content is on browser level protected from data mining by javascripts on merchant site by purpose or by site compromise. In that case merchant may be exmpt of full PCI-DSS requirements (verify with Your PSP or auditor) and integration is performed as follows:

On merchant site payment page where is desirable place for card data entry merchant include client script with iframe

<script type="text/javascript" src="https://pay.test.maksupay.com/vpos/csescript.js">     </script>
<iframe id="vpos-cseiframe" style="display: inline-block;" width="480" height="110"
src="https://pay.test.maksupay.com/vpos/cseiframe.html?version=5&mid=1234567&date=201804271539&signature=xxxxx”> </iframe>

Url parameters are exactly the same as when including javascript in section above.
Note: iframe only contains input fields and selects, no buttons. Button must be on merchant site and then call function

getEncryptedCardDataFromIframe(cvvRequired, nameRequired,callbackFunction);

This callback function is called with parameter results in section 5.0 above
For example

function myCallBackFunction(results)
{
	  if (results[‘cardEncData’]!=null)
		{
			document.getElementById(“cardEncData”).value=results[‘cardEncData’];
			document.getElementById(“payform”).submit();
		}
  else
		{ alert(“Card data not valid”);  }
}

3.5. Payments with GooglePay™

Merchants who want to include GooglePay buttons on their self hosted payment pages must ensure they are familiar with GooglePay and adhere Google Pay Web brand guidelines, those guides are available at following Google pages:

• https://developers.google.com/pay/api/web/overview
• https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist
• https://developers.google.com/pay/api/web/guides/brand-guidelines

To enable GooglePay functionality, Maksu account manager configures this option on merchant account.

1. Including GooglePay button on Your payment page.
To include GooglePay button to Your own hosted payment page use a iframe tag with src url set as follows:

1. Set http header Cross-Origin-Opener-Policy for Your page displaying GooglePay when loaded to value “unsafe-none”

Note: If not set iframed GooglePay button is unable to open GooglePay window!

2. Add iframe element with id “vpos-GooglePay” this is where GooglePay button will be rendered

Production:

<iframe id="vpos-GooglePay" 	src=”https://pay.eu.maksupay.com/vpos/googlepay.html?	version=5&mid=1234567&date=202503251539&signature=xxxxx” ></iframe>

Sandbox:

<iframe id="vpos-GooglePay" 	src=”https://pay.eu.maksupay.com/vpos/googlepay.html?	version=5&mid=1234567&date=202503251539&signature=xxxxx” ></iframe>

Make sure url parameters are properly urlencoded in URL and not encoded when calculating signature.

then include VPOS client JS libaray and intialize with order info and callback function that will return You wallet payload once user wallet session is ended successfully.
This payload You need to put to payment API messages into PaymentInfo.WalletInfo

<script type="text/javascript" src="https://pay.eu.maksupay.com/js/vposclient.js"> </script>
<script>
	function myEndWalletSession(data)
	{
		document.getElementById(“myWalletData”).value=data;
	 }
</script>
<script>
  VPOSClientJS.initWalletSession(orderInfo, options, function(data) {
	myEndWalletSession(data);
	}
   );
</script>

Order info obect need to be following properties
orderId – the unique order id
orderTotal – total price of order
currency – the currency used for orderTotal.
Options:
backgroundColor – default white, html colors (iframe background color)
buttonColor – default black, possible values: black, white
buttonType – default order, possible values: buy, checkout, donate, order, pay, plain, subscribe
buttonRadius – value 0…100 default 18 (for rounded corners)

Additionally Maksu defaults (required) are for BillingAddressParameters
format: FULL, phoneNumberRequired: true
Values for gateway and gatewayMerchantID are preset in Maksu iframed button as necessary to render service.
Values for card networks are preset in Maksu iframed button as necessary to render service, currently visa and mastercard

Example how button will render by default :

3DS flow applicability:

To determine if particular GooglePay interactions are already having 3ds cryptogram or needs 3DS performed before payment, send the wallet data in , ThreeDSMethodReq AuthenticationReq, if its PAN_ONLY then authentication api returns infomration needed to continue on normal 3DS flow, if it contained 3ds cryptogram (authenticated when added to wallet) then those requests return status AUTHWALLET and no 3DS flow needed.

Example payment message with GooglePay data:

<VPOS xmlns="http://www.modirum.com/schemas/vposxmlapi5" xmlns:ns2="http://www.w3.org/2000/09/xmldsig#"><Message id="M1743011079509" senderId="200002" ts="2025-03-26T17:44:39.510Z" version="5.0"><SaleReq merchantId="200002"><OrderInfo orderId="O1743011041215"><OrderDesc/><OrderAmount>1.25</OrderAmount><Currency>EUR</Currency></OrderInfo><PaymentInfo payMethod=""><WalletInfo status="success" walletId="GooglePay"><data>{"apiVersion":2,"apiVersionMinor":0,"email":"a#@#.com","paymentMethodData":{"description":"Mastercard •••• 6199","info":{"assuranceDetails":{"accountVerified":true,"cardHolderAuthenticated":false},"billingAddress":{"address1":"Kikerpuu tee 23","address2":"1","address3":"","administrativeArea":"Harjumaa","countryCode":"EE","locality":"R##e","name":"A## K##","postalCode":"76","sortingCode":""},"cardDetails":"6199","cardNetwork":"MASTERCARD"},"tokenizationData":{"token":"{\"signature\":\"MEUCIQDLxhEeZsHJXZys3snPERbbqwRIBPIqg9Za4OLaQ6iQmwIgXLAY28bg5jyAr3ixz5CFTpOIrrvMSMqd6oyuf5/8vSM\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgvYC0f4nzc2dYPztRprz5xp05rO14JERLqJv+s1VC2j3WS8BPhBbKDLzXeyyk/4IfC5//dyjVs7rZqA2gpnl0g\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1743701176433\\\"}\",\"signatures\":[\"MEQCIAMiksS7CGNuMZdMK35bzVxlLQW6sfOrAnbpNGIYEf5PAiALCJKgMSqXwsX01mcshH/megyVopWNmJj018o9JdIalw\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"VagPck6LnMg3P9JgMCy3X9paF+oIK7jQXMhB7F6YdUBCqGqgQsZMR/HBCH98xI2V36qKoAoVsJ9EwtbmMlNLl8aJ4dCgDVL8eC0RZyQ0/Q3ni2b7hhmqgOp3lhG8BFp/tAS+1xjCTpHuicp3PYScn0+ThlF11JTXSDvlnOnsHmvgIU0zsjsmqIA2nWoknkymWm+blcoLg8xL1y6mPQH2vozsFUILD+FEP3Z4G1OvYY1B1nSLh+cuMDbMArrts8hIJ4AkD6SnIDv/geG84Hsq13HuEqmtTLr/FQ9t0oV7l1q17/QjLKIaDO0CDL8E+s4QkoRo4a2JrQJrvMARdhLXp7e33sqWetheVzLtbbDiZmcdl+SNXb2MZLCZp0oGQ9jR/MbulmNmKJJhid6zaHlMKZXGn9k4nwGknTyVvD9JFSU1swXbCL6W+/L4IxVJVCT1KLa3G3nCd/HtjMAHrTIKfDMit6UmeDIeE2Dc5ig82BfUAYtrXaJBCBjEvsH/CxgrZf17R0rP3dvBHo8/IX0o8VPOKN+Z2y/bUGps5PbboH1Tajy3iQ\\\\u003d\\\\u003d\\\",\\\"ephemeralPublicKey\\\":\\\"BHDdZhxJuVIiIVQ1IaaLog2A4klvb6TxE+A5mgoZJ9PwF0vzQRUSngKDUbkMc01RDFpiOqA29nNbzf0/g3FZFSU\\\\u003d\\\",\\\"tag\\\":\\\"U9YJF3SipZgRroqe8rawj47slyztum5T2bq9MznfsAM\\\\u003d\\\"}\"}","type":"PAYMENT_GATEWAY"},"type":"CARD"}}</data></WalletInfo><PayerEmail>u@#.com</PayerEmail><PayerIpAddress>192.168.8.98</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="#M1743011079509">
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
<ds:DigestValue>yNOUFFamCz7Rt/C8S0XwkHLQuM+PQmb5rRWAX24jexo=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>
KRMTTbeHbKOK3v6bPPKyGLkdKQr/GszdTZvIHVszyw2DD1oXssaeaVLsFWpYWxQX985xohU3QniF
fHtT92ux1EkFWTSBedA/D2I0AXZCbMnS6lEN0JYfZg7EgwdPDyzjjCuTRqbiswbCQiLf/LSytyNr
JlCT6nUvhMcmw52Eyiz+JMmiwjiKGUtNwz008elGSUOeZYUVJsWdGX0EXeK4WDpgi1MuofbRGMtV
DSYIWNxHov50fgdjPUyws+uiNW4ALuS1oNH2wbZJUiKaD1+b364+WT6B3Ge6oYobfQfLAA2Voz1t
mru5YUkBe1DBhN/c6Y1keG94JwAT5n5Elp1ijw==
</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>

3.6. Payments with ApplePay™

This functionality becomes available Q2/2025

3.7.1 XML Signature calculation example

Example code:

import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;

import org.apache.xml.security.keys.KeyInfo;
import org.apache.xml.security.keys.content.X509Data;
import org.apache.xml.security.keys.content.x509.XMLX509Certificate;
import org.apache.xml.security.signature.XMLSignature;

public class Signer
{
	public byte[] sign(VPOS root, PrivateKey prik, java.security.cert.X509Certificate[] crts) throws Exception
	{
		org.w3c.dom.Document dom = apis.marschalToDOM(root);
		// apis.normalizeDOM(dom); dom nomralization is very slow using instead 	
		// msg.setIdAttribute("messageId", true);
		Element vpos = dom.getDocumentElement();
		XMLSignature xmlsigAp = new XMLSignature(dom, null,
				"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
				"http://www.w3.org/TR/2001/REC-xml-c14n-20010315");

		Element sigel = xmlsigAp.getElement();
		vpos.appendChild(sigel);

		Element msg = (Element)vpos.getFirstChild();
		// setting id attribute instead of dom normalization
		msg.setIdAttribute("id", true);
		xmlsigAp.addDocument("#" + msg.getAttribute("messageId"), null,
			"http://www.w3.org/2001/04/xmlenc#sha256", null, null);

		for (int i = 0; crts != null && i < crts.length; i++)
		{
			xmlsigAp.addKeyInfo(crts[i]);
		}
		xmlsigAp.sign(prik);
		ByteArrayOutputStream bos = new ByteArrayOutputStream(4096);
		TransformerFactory transfac = TransformerFactory.newInstance();
		Transformer trans = transfac.newTransformer();
		trans.setOutputProperty(OutputKeys.OMIT_XML_DECLARATION, "no");
		trans.setOutputProperty(OutputKeys.INDENT, "no");
		trans.setOutputProperty(OutputKeys.ENCODING, "utf-8");

		DOMSource source = new DOMSource(dom);
		trans.transform(source, new StreamResult(bos));
		return bos.toByteArray();
	}
}

3.7.2. Signature calculation with JSON API V5.0

For JSON messages signature is calculated using whole JSON content as POSTED and signature is sent in http header X-Payload-Signature
Example first part inficates signature algorithm then semicolon as delimiter and then signture value in base64 encoding:

X-Payload-Signature = RSA-SHA256;EOZfZG2oFjOXFX9CeFdn1hU1qu7w0dj9Dxdwk/0vlB+Hc6lPBD2l1FLZY4DT1+7vEFr9GGysitTUkmHAjO/nHNUrwNJ3mvN94YZnvbtLpqFkCjhxDapHPVRkOhTAjZ1HkwmN2SJraVgs5MUo7oHymkvfp5FS5RRZLcpV7ibPMzIj4S2YzWKf0s/LkwWNHHESsbCDqaTNbUcny+uDAidRyUdYdx5HlQX27uOIvCmDJNOyXThy14XZAuf3URaaXNVJn+M9qPb9vpQ99gkOReDNL6H5rRjOUcFPm2SMR94i00mkOWPld/fcFAMHVlHL+oFTV8o0uQLL2FIPzWf7MciQy/FLAKoRfXWtkP04tYECmfYkQjIQfDrGVhiL8dOUNWqmzbvQoNdV/d3ZlUI9r/MVOtM74I/qTiR5CAg8z8c0fT8snWMlhJdm5nKBMVZ1oDAl+BcH7CCpej+QZQRHgtFS3qvGFtMG61cmrSuShc237xuHrRqFXHAviVcSvlLAVbIR

Also heade X-Sender-ID is recuired and needs to be value of Your merchanrt account id.
In response messages from Maksu X-Sender-ID contains subject of signing serticate.

Example X-Sender-ID headers
Merchanrt sending
X-Sender-ID: 123123

Maksu sending in response or notification:
X-Sender-ID: C=AT ST=VN, L=Vienna,O=MaksuPay,OU=E-COM Signer,CN=MaksuPay E-COM Signer 2024-01

X-Sender-ID header value must be identical to Message senderId field if not message is rejected.

Example code calculating signatrure for JSON messages.:

Lets assume that you have already json content as bytes, merchant id and private key and certificate objects then:

public HashMap<String.String>
	signJSON(byte[] json, String mid, PrivateKey pkikKey,
		java.security.cert.X509Certificate crt)
	{	
		HashMap<String.String> headers=new java.util.HahsMap<>();
		headers.put("X-Sender-ID", mid);

		byte[] pubKey=crt.getPublicKey().getEncoded()));
		MessageDigest mdigest = MessageDigest.getInstance("SHA-256");		byte[] digestResult = mdigest.digest(toUtf8Bytes(data));
		String pubKeyHash=Base64.encode(digestResult,0);
		headers.put("X-Public-Key-Hash", pubKeyHash)

		Signature sg = Signature.getInstance(“SHA256withRSA”);
		sg.initSign(pkikKey);
		sg.update(json);
		byte[] sigBytes = sg.sign();
		String sigStr = Base64.encode(sigBytes, 0);
		headers.put("X-Payload-Signature", "RSA-SHA256;"+sigStr);

	return headers;
	}

3.8. XML API example messages

XML Examples

Please see XML message samples

SaleReq
https://testtools.maksupay.com/vpostests/examples/SaleReq.xml

and SaleRes
https://testtools.maksupay.com/vpostests/examples/SaleRes.xml

Cancel/Void
Request
https://testtools.maksupay.com/vpostests/examples/CancelReq.xml

Response
https://testtools.maksupay.com/vpostests/examples/CancelRes.xml

3.9. JSON API Example messages

JSON Examples:

Please see JSON message samples

saleReq
https://testtools.maksupay.com/vpostests/examples/saleReq.json

and saleRes
https://testtools.maksupay.com/vpostests/examples/saleRes.json

Cancel/Void
Request
https://testtools.maksupay.com/vpostests/examples/cancelReq.json

Response
https://testtools.maksupay.com/vpostests/examples/cancelRes.json

4. Maksu VPOS payment page

Payment pages in Maksu VPOS is rendered using XSLT template.
Typically merchants can select from Maksu developed templates most applicable version and if needed develop a customized CSS file for accommodated look and feel.

Custom CSS style sheets when supplied by merchant should also be reviewed by technical maintainer of the solution and then the style sheet can be installed into vposart modules once validated.

On special cases its also possible to develop merchant custom XSLT template, but this need to be on case by case basis and need to pass though validation and manual review.

4.1. XSL Templates and sub templates overview in payment XSL

Rendering starts from

<xsl:template match="/">
		<xsl:call-template name="page"/>
</xsl:template>

Then template page is rendering and calling one of the sub templates
<xsl:template name="page">
	        <xsl:template name="paymentPage">
	        <xsl:template name="errors">
	        <xsl:template name="payform">

Template named page is rendered first and it renders general page layout and calls appropriate sub template depending on the actions what are performed.
the sub template named “paymentPage” is rendering the payment page part where user is selecting payment method and enters card data. This is in general the only sub template to be modified if custom payment page is needed.
The sub template “errors” is only called if system or application level unrecoverable error occurs.
The sub template “payform” renders invisible redirection forms that user does not see normally and they are submitted automatically by javascript.

Other sub templates are used to render specific parts of content. and are individually called by sub templates whenever applicable.