Maksu Logo

MaksuPay VPOS Redirection interface

API docs by Redocly

MaksuPay VPOS Redirection interface (5.0)

Download OpenAPI specification:

MaksuPay Support: support@maksupay.com URL: https://maksupay.com

MaksuPay VPOS Redirection endpoint for processing sale, preeuth payments for direct payer integraction on Maksu hosted payment page.

VPOS redirection NVP Payment Request (posted by user browser)

Request Body schema: application/x-www-form-urlencoded
required
version
required
string

Interface version (5)

mid
required
string <= 30 characters

Merchant identifier supplied by MaksuPay eg 200002

lang
string

Language code (ISO 639-1, e.g., en, fi, sv, de)

deviceCategory
string

Browser or device category (optional)

trType
string

Transaction type (1=payment, 2=pre-auth, 8=tokenization)

orderid
required
string <= 50 characters

Merchant’s unique order ID (1..50) ex O1769423467137

orderDesc
string <= 4000 characters

Order description (1..4000 chars)
Recommended and requires for some payment methods is to provide line item desciptions.
Some payment methods may require order line item details and tax details. To send such info use orderDesc or 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, ds-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

orderAmount
required
number <decimal>

Order amount (>0.0 or 0.0 for tokenization)

currency
required
string

ISO 4217 currency code (EUR, USD, etc.)

payerEmail
string <email>

Customer email (strongly required)

payerPhone
string

Customer phone number

billCountry
string

Billing country code (ISO 3166-1 alpha-2)

billState
string

Billing state/province

billZip
string

Billing ZIP/postal code

billCity
string

Billing city

billAddress
string

Billing street address

shipCountry
string

Shipping country (required if weight or dimensions supplied)

shipState
string

Shipping state/province

shipZip
string

Shipping ZIP/postal code

shipCity
string

Shipping city

shipAddress
string

Shipping street address

weight
number <decimal>

Shipping weight in kg (>0; 0.0 for digital goods)

dimensions
string

Package dimensions width:height:depth (e.g., 200:200:200)

addFraudScore
integer

Starting risk score (optional override)

maxPayRetries
integer

Number of retry attempts before returning to merchant

reject3dsU
string
Enum: "Y" "N"

Reject 3DS status U (Y/N)

payMethod
string

Preselect payment method ID (optional)

blockScore
integer
cssUrl
string <uri>

external https:// url of merchant to apply extra CSS syling

confirmUrl
string <uri>

Merchant URL to return user on successful payment

cancelUrl
string <uri>

Merchant URL to return user on failed/canceled payment

extInstallmentoffset
integer

Number of months before first installment (optional)

extInstallmentperiod
integer

Number of installment payments (optional)

extRecurringfrequency
string

Recurring interval in days (optional)

extRecurringenddate
string <date>

Recurring end date (YYYYMMDD)

extRecurringAmtInd
string

1 default fixed amount, 2 variable amount

extXOrderId
string

External customer recognition order ID

extTokenOptions
string

Tokenization request options

extToken
string

Token value (optional)

var1
string <= 4000 characters

Free merchant variable (optional) Also some special attributes can be defined in var fields 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

var2
string <= 4000 characters

Free merchant variable (optional)

var3
string <= 4000 characters

Free merchant variable (optional)

var4
string <= 4000 characters

Free merchant variable (optional)

var5
string <= 4000 characters

Free merchant variable (optional)

var6
string <= 4000 characters

Free merchant variable (optional)

var7
string <= 4000 characters

Free merchant variable (optional)

var8
string <= 4000 characters

Free merchant variable (optional)

var9
string <= 4000 characters

Free merchant variable (optional)

signature
required
string

RSA SHA-256 signature for request integrity

  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.
  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).
publicKeyHash
required
string

Public key hash of merchant public key to be used to validate signature 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
Java example (public key hash calculation)

public static String publicKeySHA256Hash(PublicKey pubKey)  
{  
  return Base64.encode(pubKey.getEncoded());  
}

.NET example for public key hash calulation: 

public static string PublicKeySHA256Hash(RSA rsaPublic)  
{  
  byte[] publicKeyBytes = rsaPublic.ExportSubjectPublicKeyInfo();  
  using (var sha = SHA256.Create())  
  {  
    byte[] digest = sha.ComputeHash(publicKeyBytes);  
    return Convert.ToBase64String(digest);  
  }  
}

Responses

Request samples

Content type
application/x-www-form-urlencoded
<form id="maksuPay" action="https://pay.test.maksupay.com/vpos/shophandler" method="post"> <input type="hidden" name="version" value="5"/> <input type="hidden" name="mid" value="200002"/> <input type="hidden" name="trType" value="1"/> <input type="hidden" name="orderid" value="JAVA1769423467137"/> <input type="hidden" name="orderDesc" value="My Items"/> <input type="hidden" name="orderAmount" value="1.29"/> <input type="hidden" name="currency" value="EUR"/> <input type="hidden" name="payerName" value="Uncle Sam"/> <input type="hidden" name="payerEmail" value="user@host.com"/> <input type="hidden" name="payerPhone" value="+434120151"/> <input type="hidden" name="billCountry" value="AT"/> <input type="hidden" name="billState" value="WN"/> <input type="hidden" name="billZip" value="1200"/> <input type="hidden" name="billCity" value="Vienna"/> <input type="hidden" name="billAddress" value="Strasse 25-1"/> <input type="hidden" name="confirmUrl" value="https://developer.maksupay.com:443/maksusdkjava/return"/> <input type="hidden" name="cancelUrl" value="https://developer.maksupay.com:443/maksusdkjava/return"/> <input type="hidden" name="signature" value="TYo7Pe6TX3hTX7cAaeTBYHS17dCCizX4EpE0VFCBBUBG5k7jAENRWVmv7pyipjBG/nf73rAx2660HiFAUQzcH4lpDanKkmXpXnA1FrXlpbZdW1FLoGVCO6NKujgueruai0ki1hw8nvwJ8dEpxfWUwyLv0YDt08xeIeJPknqOY1nWFHbVzeEjR0rcjM9p+sDEH5ExE94oxsHFqlJirnqDWzjQbaDfL2aO/anLCX58akOpznxuLlo7s75JN6Z0/vuc5MpZpOkjjlcWtB/yI/GdkjjKffhgWbArOIsVgoF0XuSRa7UZZfsy/HboZf4JzUOoX8xOCMgyqP24p45F71WulA=="/> <input type="hidden" name="publicKeyHash" value="IPooODW/mVydXfF2OCLUY5H+a+um8uVnzQcAUmn6Lgk="/> </form>

Response samples

Content type
application/x-www-form-urlencoded
version=5&mid=200002&orderid=JAVA1769423467137&status=CAPTURED&orderAmount=1.29&currency=EUR&paymentTotal=1.29& message=OK&riskScore=0&payMethod=mastercard%3AGooglePay&txId=145407&paymentRef=270324&shipCountry=DE&shipZip=80636&shipCity=Munich& shipAddress=Erika-Mann-Stra%C3%9Fe+33&shipRecipientName=German+User&extData=panEnd%3D0368& signature=S5hGFuZd9XsU%2BU%2BK2NsWg4D%2BYIQXt4gXpqRfwMx2g5zQfrwPNbY5q2atFSVLcRvY%2F5uWJjAxIzEwdptVPrjRRoQytTrG1p7tn0kEY5PdhO6fcGfexytHNSq9lyT2%2FbDsF6EtgVtKTsRurTKUeKyv9zYDZQit9akAglbr2l6D%2BiaUPSAw4TEEJrYlNzi7PJX5IOka1UI7jsQS0x%2BDCCPFAQQ9lJvlcqhAKeWPzF6vM3kZUrvj67t3IjlC44RO2oFBFsju8KkMK7Z9WvqFZmf2PPs6Ki91xZ5MeJ2iAG9dFEhSdfknjh5gZHeNV59auQ0XtSAwuH9wYunM4Kr3nQklMD7HwzuSsEf6PvMNND5aNXgu3Zbzc%2BdDYKPlovISihzYFu%2FxXBSzdEO2leXrT1Q%2BzBBiaPJyDliv%2BKzBc23oD9TPK7slCukkOuAuj41aIPjbmJnAhBVGuiPuiJiEvg7BjSD9%2Bl2BioLvCYRfgVjsumiV3Jq7dG85a9SlED5IY3J5& publicKeyHash=BecEjchDmUWaq9EPUiP%2Bb7kVFbjQWT9ksMJrRgVbChE%3D