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