Maksu VPOS 3.0
1. Overview
2. Modirum VPOS interface for merchant shop
3. Maksu VPOS payment page
4. XML/JSON API Interface
5. Browser client side card data encryption for XML/JSON api using PSP javascript
6. XML/JSON API plugin example message and signature calculation
7. XML/JSON API example messages
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
Modirum VPOS is a payment application that is designed for processing merchant payments in ecommerce 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 Modirum 3D Secure merchant plugin technology or external payment methods like net payments in shopper local banks and so on. Exact payment methods available should be specified by client.
Modirum VPOS core design enables multiple types of merchant interfaces to be implemented and also the easy to implement default interface and MPI integrated version is provided for reference. 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).
1.1. 1.1. Security notes
VPOS also delivers great level of security. VPOS encrypts card PANs with 3072 BIT RSA public key into dedicated database table, so retrieval of PAN data is only possible with supplied private key (that could be in protected keystore or supplied externally from security devices). Also sensitive data like (card expiration, card holder name, payer phone and payer email) are encrypted in database, default encryption algorithm used for this is 256 bit AES.
VPOS also has a pluggable interface for risk/fraud scoring. Before completing authorization and after transaction 3D secure processing the risk score calculation service is called. The actual implementation of can take account any data (from payment method type, authentication type to user ip address) that is associated with particular transaction. The risk scoring results are also posted back to merchant shop (see the interface description section 2.2 page 7,8). Merchant profiles have option do deny and not authorize transactions starting with specified score.
1.2. Changes recorded:
1.0 26.09.2024 Intitial version of V5 interface documentation
1.1 30.09.2024 – Added 3DS API desciptions
2.0. Intro
Communication between Modirum VPOS and Merchant shopping cart software can be implemented via HTTP post protocol following the specification below.
2.1. Merchant shop request to initiate payment with Modirum VPOS
The following table describes the parameters of the POST from the payment page to VPOS.
Field (HTTP POST parameter) | Required / Optional | Description |
---|---|---|
version | R | Required for interface version 5 |
mid | R | Merchant id supplied (integer number) will be supplied to merchant, max length 30 |
lang | O | lang O Language selection for payment page (ISO 639-1 language code en, fi, sv…) |
trType | R | Transaction type, valid values 1 – payment, 2 – pre authorization (applicable only to card payments only), 8 – tokenization only – perform tokenization no payment. Shall be with orderAmount = 0.0 |
orderid | R | Merchant shop order id provided by merchant shop max length 50 chars (string 1..50) |
orderDesc | R | Order description text (string 1..128) |
orderAmount | R | Order amount (decimal number >0.0 or 0.0 for tokenizer) max length 13 with decimal point (up to 12 numbers) |
currency | R | Order amount currency (string 3 ISO ISO 4217 alphabetic code (EUR, USD)) |
payerName | O | Order payer name, highly reommented, required for some payment flows |
payerEmail | O | Order payer email address (string 1..64), Optional but Strongly recommended. |
payerPhone | O | Order payer phone number, optional but strongly recommended (string..30) |
billCountry | O3DS2 | Billing address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) |
billState | O3DS2 | Billing address state (string..50) recommended Var str 3 3166-2 country subdivision code |
billZip | O3DS2 | Billing address zip code (string..16) |
billCity | O3DS2 | Billing address city (string..64) |
billAddress | O3DS2 | Billing address street (string..100) |
shipCountry | O/R | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) Optional, required when parameter weight or dimensions are present. |
shipState | O/R | Shipping address state (string..50) Optional, required when parameter weight or dimensions are present. Recommended Var str 3 3166-2 country subdivision code |
shipZip | O/R | Shipping address zip code (string..16) Optional, required when parameter weight or dimensions are present. Optional, required when parameter weight or dimensions are present. |
shipCity | O/R | Shipping address city (string..64) Optional, required when parameter weight or dimensions are present |
shipAddress | O/R | Shipping address street (string..100) Optional, required when parameter weight or dimensions are present. |
weight | O | Order shipping weight (kg) if item is shippable and shipping needs to be calculated by VPOS (decimal number >0) max length 12 with decimal point For electronic deliveries send weight=0.0 |
dimensions | O | Order shipping dimensions (mm) in format width:height:depth for example a box 200:200:200 (string..25) can be used for shipping calculation if implemented so |
addFraudScore | O | Incoming starting risk score (integer) max length 12 |
maxPayRetries | O | Maximum payment retries allowed before user is sent back to merchant, overrides specific profile setting if present (integer) max length 2 |
reject3dsU | O | Should 3-D Secure return U status, merchant has option of continuing the transaction without liability shift or reject the transaction. >If this value is true, the transaction will not be accepted. (string 1 Y/N) |
payMethod | O | For pre selection of payment method. Paymethod id , can be used to preselect payment method at merchant site, so user can not select other payment method later (string..20), exact values will depend of implemented methods on service provider side. |
blockScore | O | Optional bloack score parameter that will be used to block the transaction if transaction riskScore reaches this value or above. (Postive Integer number) max length 9 |
cssUrl | O | The absolute or relative (to vpos location on server) url of custom CSS stylesheet, to be used to display payment page styles. (string..128) Note: if absolute and payment page is SSL secured make sure the URL is also SSL secured as browsers will not show unsecured element object warnings. This may be subject of approval |
confirmUrl | R | Confirmation URL where to send payment confirmation in case payment was successful (string..128) |
cancelUrl | R | Cancel url where to send payment feedback in case payment has failed or was canceled by user (string..128) |
extInstallmentoffset | O | Optional. In case installments are supported by the processing system then this parameter of installments can be used to indicate initial offset in months when first payment will be submitted (by acquirer). Applicable for card payments only. Integer max length 3 |
extInstallmentperiod | O/R | Optional, required in case previous parameter is present. In case installments are supported by the processing system then this parameter of installments is to used to indicate number of payments/months the merchant requests for installments. Applicable for card payments only. Value must be >1. Max length 3 Installment parameters and recurring parameters together are not allowed on same request |
extRecurringfrequency | O | Optional. In case recurring payments are supported by the processing system then this parameter can be used to indicate frequency of recurring payments, defines minimum number of days between any two subsequent payments .The number of days equal to 28 is special value indicating that transactions are to be initiated on monthly basis. Applicable for card payments only. Max length 3 |
extRecurringenddate | O/R | Optional, required in case previous parameter is present. In case recurring payments are supported by the processing system then this parameter can be used to indicate date after which recurring ends and no more transactions no more transactions are initiated. The format is YYYYMMDD. Applicable for card payments only. Installment parameters and recurring parameters together are not allowed on same request. |
extXOrderId | O | Optional merchant and acquirer agreed extension for recognizing returning customers with submitting previous successful order id of the merchant recognized customer. If functionality is not enabled for merchant this parameter is silently ignored. |
extTokenOptions | O | Optional merchant and acquirer agreed extension for generating a card token on successful payment. If functionality is not enabled for merchant this parameter is silently ignored. (number string ..3) To request new token value (on new card) first char shall be set to 1 To request auto payment (wo need user enter cvv) with existing token second char shall be 1. To request full auto payment (wo need to do 3d) with existing token third char shall be 1 (in order full auto to work both cvv omit and 3d omit shall be set 1 and allowed in merchant settings). |
extToken | O | Optional merchant and acquirer agreed extension for recognizing tokens of returning customers with submitting previously generated card token. If functionality is not enabled for merchant this parameter is silently ignored. |
var1 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var2 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var3 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var4 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var5 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var6 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var7 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var8 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var9 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
signature | R | Version 4: Message signature to ensure and verify message security and integrity. RSA with SHA2 256 signature of all the field values above concatenated together (see section 2.4). Version 4 available since vpos v 1.2.3 March 30 2017 |
publicKeyHash | O | Optional but highly recommended. The SHA-2 256 base64 hash of X509 encoded public key to verify signature, useful if merchant has multiple public keys in file or in transition from one key to another, so correct public key can be selected for validation |
3DS2– required with some schemes when 3DS2, so strongly recommended to send always.
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.
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.
Field (HTTP POST parameter) |
Required/ Optional | Description |
---|---|---|
version | R | Version 4 available since vpos v 1.2.3 March 2017 |
mid | R | Merchant id supplied (integer number) max length 30 |
orderid | R | Merchant shop order id string max length 50 |
status | R | Payment status (string..16) see section 2.5 payment statuses |
orderAmount | R | Order amount (decimal number >0.0) same as in request |
currency | R | Order amount currency (string 3, ISO ISO 4217 alphabetic code (EUR, USD)) same as in request |
paymentTotal | R | Order amount plus fees and shipping and additional service charges if applicable (decimal number >0,0) Required when payment was a success, can be omitted when payment fails or canceled |
message | O | Optional message (string..128) can provide optional information about payment or error description. |
riskScore | O | Optional information about the possible risk with transaction (integer number) |
payMethod | O | Optional information about payment method used to complete transaction (string 20). Is present only when payment was success |
txId | O | Optional system assigned transaction reference id (integer number) |
paymentRef | O | Optional end payment system reference or approval code. String 1..64 |
shipCountry | O | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) Optional, may be present if returned from wallet |
shipState | O | Shipping address state (string..50) Optional, may be present if returned from wallet |
shipZip | O | Shipping address zip code (string..16) Optional, may be present if returned from wallet |
shipCity | O | Shipping address city (string..64) Optional, may be present if returned from wallet |
shipAddress | O | Shipping address street (string..100) Optional, may be present if returned from wallet |
shipRecipientName | O | Shipping recipient name (string..100) Optional, may be present if returned from wallet |
shipRecipientPhone | O | Shipping recipient phone number (string..35) Optional, may be present if returned from wallet |
extToken | O | If merchant requested tokenization and tokenization enabled then on successful payment token value of card used will be returned. |
extTokenPanEnd | O | If merchant requested tokenization and tokenization enabled then on successful payment last 4 digits of tokenized pan are returned. |
extTokenExp | O | If merchant requested tokenization and tokenization enabled then on successful token payment token expiration is returned in format YYYYMMDD |
extData | O | Optional merchant and acquirer agreed variable type string ..1024 May be encoded and contain subfields in format p1=v1&p2=v2.. (+url encoded value) |
var1 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var2 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var3 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var4 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var5 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var6 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var7 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var8 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
var9 | O | Optional merchant and acquirer agreed free variable type string ..1024 |
signature | R | Version 4: Message signature to ensure and verify message security and integrity. RSA with SHA2 256 all the field values above concatenated together having ; in end of each values . Signed by processor private key. Merchant shall obtain Certificate of processor from service provider. (see section 2.4) |
publicKeyHash | R | The SHA-2 256 base64 hash of X509 encoded public key to verify signature, useful if processor has multiple public keys set up or in transition from one key to another, so correct public key can be selected for signature validation |
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: Since VPOS version 1.1.1 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 “Modirum 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.
Field (HTTP POST parameter) |
Required/ Optional | Description |
---|---|---|
version | R | Version 4 available since vpos v 1.2.3 March 2017 |
mid | R | Merchant id supplied (integer number) |
orderid | R | Original Merchant shop order id |
status | R | Payment status or the recurring child (string..16) see section 2.5 payment statuses |
orderAmount | R | Original Order amount (decimal number >0.0) same as in parent recurring request |
currency | R | Original Order amount currency (string 3, ISO ISO 4217 alphabetic code (EUR, USD)) same as in parent request |
paymentTotal | R | Original Order amount plus fees and shipping and additional service charges if applicable (decimal number >0,0) Required when payment was a success, can be omitted when payment was failed or canceled |
message | O | Optional message (string..128) can provide optional information about payment or error description. |
riskScore | O | Optional information about the possible risk with transaction (integer number) |
payMethod | R | Information about payment method used to complete transaction (string 20). Is present only when payment was success |
txId | R | Original recurring parent system assigned transaction reference id (integer number) |
sequence | R | Sequence number or recurring (parent has sequence number 1, the first recurring child will have sequence number 2, etc) |
seqTxId | R | The sequence transaction unique id in system (Integer) |
paymentRef | O | Optional end payment system reference or approval code. String 1..64 |
signature | R | Version 4: Message signature to ensure and verify message security and integrity. RSA with SHA2 256 digest of all the field values above concatenated together |
publicKeyHash | R | The SHA-2 256 base64 hash of X509 encoded public key to verify signature, useful if processor has multiple public keys set up or in transition from one key to another, so correct public key can be selected for signature validation |
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:
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:
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.
Now export Your certificate to a file that can be sent to service provider:
2.7. 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, sc – 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. Maksu VPOS payment page
Payment page in Maksu VPOS is rendered using XSLT template.
The default template named payment.xsl and additional ones are provided with installation. Also custom vpos artbase location can be configured where custom xsl templates can be located in separate module of VPOS but reachable by VPOS application. Developer of custom XSLT for payment page must be familiar XSLT, XPATH, XML and other WEB technologies such as HTML and JavaScript and CSS.
In depth knowledge of XSLT can be obtained from http://www.w3.org/TR/xslt.
Basic knowledge of XSLT can be found at http://www.w3schools.com/xsl/default.asp
In general merchants do not need their custom payment XSLT developed. Changes in look and feel can be more easily accomplished supplying the custom CSS style sheet that defines the look and feel of payment page such as colors, backgrounds, fonts and even content positioning.
Maksu also has selection of templates to choose from to start with.
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 folder/module of vpos artbase Each CSS style sheet should have named as it can be later recognized to belong to certain merchant or merchants. Once the custom CSS is installed then in VPOS Manager merchant payment profile settings under section General settings field “CSS style sheet (leave blank for default) ” should be filled with the:
CSS URI {artbase]/css/cssaname.css
where {artbase]/css part is the location of CSS files
and cssname.css is the actual file name of the supplied CSS file.
3.1. XSL Templates and sub-templates in payment XSL
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.
3.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
Field/request | Type | Description |
---|---|---|
Request | ||
VPOS | element | XML root element / JSON root { } |
Message | element type Message | Message contents element / JSON Object “message” |
version | attribute, xsi:string | Message version default value “5.0” Required or 2.1 |
id | attribute, xsi:ID | Message unique identifier (values in request and reply messages this must match, also used for lookup signature reference object when validating signature) (“M1234567”) |
lang | attribute, xsi:string(2) | Message attribute to specify context language (Optional) (ISO 639-1 language code en, fi, sv, el, etc..) |
ts | Attribute xsi:dateTime | Approximate time when message was created |
senderId | attribute, xsi:string | In Requestes merchant service account id (merchant number) |
Signature | element ds:SignatureType |
Required if version = 5.0 (only supported version) The xml signature as defined https://www.w3.org/TR/xmldsig-core/ Canonicalization http://www.w3.org/TR/2001/REC-xml-c14n-20010315 SignatureMethod Algorithm=”http://www.w3.org/2001/04/xmldsig-more#rsasha256” DigestMethod Algorithm=”http://www.w3.org/2001/04/xmlenc#sha256″ Requests are signed by merchant private ket and validated with merchant Certificate and responses are signed by processor private key and validated with Processor certificate |
Payment API messages SaleReq, AuthorisationReq, CaptureReq, OriginalCreditReq RefundReq, CancelReq RecurringOperationReq, StatusReq, TokenizationReq, DeTokenizationReq |
element | RequestMessage element depending on request type Equvalent JSON objects: saleReq,authorisationReq, originalCreditReq, refundReq, cancelReq recurringOperationReq, statusReq, tokenizationReq, deTokenizationReq |
merchantId | attribute | Merchant number/identification in VPOS=Message senderId |
OrderInfo | Orderinfo element of request Message / JSON Object orderInfo | |
OrderId | xsi:string AN1..50 | Merchant defined unique order id / JSON string orderId |
OrderDesc | xsi:string AN1..128 | Order description defined by Merchant / JSON string orderDesc |
OrderAmount | xsi:decimal (max 9+3 or 10+2) |
Order amount (decimal number >0.0 and max 12 digits + decimal point) /JSON number orderAmount |
Currency | xsi:string A3 | ISO4217 alphabetic currency code (USD, EUR) / JSON string currency |
PayerName | xsi:string AN1..64 | Order payer full name (string..64) /JSON string payerName |
PayerEmail | xsi:string AN1..64 | Order payer email address (string..64) /JSON string payerEmail |
PayerPhone | xsi:string N1..30 | Order payer phone number, optional but strongly recommended (string..30) /JSON string payerPhone |
Elements Var1..Var9 Var1, Var2, Var3, Var4, Var5, Var6, Var7, Var8, Var9 |
xsi:string AN1..1024 |
Free variable defined by merchant. /JSON strings var1,var2,var3,var4,var5,var6,var7,var8,var9 |
MOTO | xsi:integer N1 | Indicating whether it is a MOTO transaction (1 indicates MOTO) /JSON number moto |
Weight | xsi:decimal | Order shipping weight (kg) if item is shippable and shipping needs to be calculated by VPOS (decimal number >0) and it is supported /JSON number weight |
Dimensions | xsi:string AN1..25 | Order shipping dimensions (mm) in format width:height:depth for example a box 200:200:200 (string..25) can be used for shipping calculation if implemented so /JSON string dimensions |
BillingAddress | xsi:string AN2 | Element of OrderInfo / JSON Object billingAddress |
Country | xsi:string AN2 | Billing address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) /JSON string country |
State | xsi:string AN1..50 | Billing address state (string..50) /JSON string state |
Zip | xsi:string AN1..16 | Billing address zip code (string..16) /JSON string zip |
City | xsi:string AN1..64 | Billing address city (string..64) /JSON string city |
Address | xsi:string AN1..100 | Billing address street (string..100) /JSON string address |
ShippingAddress | element:address | Element of OrderInfo / JSON Object /JSON object shippingAddress |
Country | xsi:string AN2 | Shipping address country code (string 2 ISO 3166-1-alpha-2 code (US, FI, GB)) Optional, required when parameter weight or dimensions are present. /JSON string country |
State | xsi:string AN1..50 | Shipping address state (string..50) Optional, required when parameter weight or dimensions are present. /JSON string state |
Zip | xsi:string AN1..16 | Shipping address zip code (string..16) Optional, required when parameter weight or dimensions are present. Optional, requiredwhen parameter weight or dimensions are present. /JSON string zip |
City | xsi:string AN1..64 | Shipping address city (string..64) Optional, required when parameter weight or dimensions are present. /JSON string city |
Address | xsi:string AN1..100 | Shipping address street (string..100) Optional, required when parameter weight or dimensions are present. /JSON string address |
PaymentInfo | Payment info element of request / JSON Object paymentInfo | |
PayMethod | xsi:string AN1..20 | Card brand VISA, MasterCard others are defined on site valid values are visa for VISA cards, mastercard for MasterCard /JSON string payeMethod |
Card | Element CardData | Object type CardData |
Pan | xsi:string N11..19 | Card number /JSON string cardPan |
ExpDate | xsi:string N4 | Card expiration date in format YYMM /JSON string cardExpDate |
HolderName | xsi:string AN1..24 | Card holder name /JSON string cardHolderName |
C>VV2 | xsi:string N3..4 | CVV2/CVC2 security code from card./JSON string cardCvv2 |
EncData | Xsi:string ..2048 | In case on merchant merchant site user browser RSA card data encryption is used this field contains encrypted card data in form of Base64(RSA(UTF8Bytes(“pn={pan}&ey={exp year}&em={exp month}&c2={cvv2}&cn {cardholdername}”)) Values are urlencoded and with utf-8 char encoding (with javascript encodeURIComponent). This all is handled by server supplied component, merchant just need to forward value as returned to this field content. If this field is present then fields CardPan, CardExpDate, CardHolderName, CardCvv2 must not be bresent /JSON string cardEncData |
Column 1 Value 44 | Column 2 Value 44 | Column 3 Value 44 |
Column 1 Value 45 | Column 2 Value 45 | Column 3 Value 45 |
Column 1 Value 46 | Column 2 Value 46 | Column 3 Value 46 |
Column 1 Value 47 | Column 2 Value 47 | Column 3 Value 47 |
Column 1 Value 48 | Column 2 Value 48 | Column 3 Value 48 |
Column 1 Value 49 | Column 2 Value 49 | Column 3 Value 49 |