Introduction to WSPayAuto

WSPayAuto integration method provides merchants with a complete solution for secure credit card authorization.
WSPayAuto contains the complete functionality that satisfies technical and safety requirements.

Generating encrypted signature in order to prevent unwanted data exchange
3D Secure authentication in accordance to 3DS 2.1
Secure connection through TLS 1.2 protocol

To implement WSPayAuto, merchant must be PCI DSS compliant!

Prerequisites

After the merchant fills in an application form and registers with WSPay, the parameters which are needed for implementation will be provided:

URL endpoints - list of endpoints needed for communication
Shop ID - unique identification of merchants shop on WSPay
Secret key - key used for generating signature

Secret key must be kept in secrecy to protect the merchants privacy.

Implementation

In order to process payment using WSPayAuto merchant must submit HTML form inside HTML document using HTTP POST method.
After successful or unsuccessful transaction WSPayAuto will, depending on the status of transaction, redirect customer to URL defined by merchant using HTTP POST method.

HTML form data parameters

List of parameters that must to submited to WSPayAuto.

ShopID	ShopID represents unique identification of merchants shop on WSPay. ShopID is received from WSPay after signing the request for using WSPay service.
ShoppingCartID	ShoppingCartID represents unique identification of transaction in merchants system. It must be unique. In case there is already a successful transaction with the same ShoppingCartID, that ID cannot be used again for future transactions. ShoppingCartID should not contain any character different from: Letters: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz Numbers: 0123456789 Special characters: _-. ShoppingCartID maximum length is 255 characters.
Version	Version parameter represents version of WSPay form to be used. For successful communication 2.0 must be used.
TotalAmount	TotalAmount is amount for which the customer will be charged, expressed in agreed currency. TotalAmount parameter must be formatted without decimal separator character where last two digits represent minor units. Example 1 Number: 3.650,35 TotalAmount: 365035 Example 2 Number: 27.650,00 TotalAmount: 2765000
ReturnURL	ReturnURL represents HTTPS address where the customer will be redirected after successful or unsuccessful transaction. WSPayAuto redirects to page defined in ReturnURL parameter and returns parameters based on transaction.
ReturnErrorURL	ReturnErrorURL represents HTTPS address where customer will be redirected in case of communication error.
Signature	Represents a signature created from string formatted from following values in a following order using SHA512 algorithm: ShopID SecretKey ShoppingCartID SecretKey TotalAmount SecretKey Signature generator, available at signature.wspay.info, can be used to test signature validity.
CreditCardName	Name of card brand that is used for this transaction. List of possible values can be found here.
CreditCardNumber	Credit card number. Credit card number must be validated before sending it to WSPay in a following way: Credit card number must be validated by Luhn Algorithm Credit card number must be validated by regular expression.
ExpirationDate	Credit card expiration date. Format: YYMM
CardVerificationData	Credit card control number. In case when credit card does not have control number this parameter should be empty.
DateTime	Date and time of transaction. Date format: YYYYMMDDHHmmSS
PaymentPlan	Value of PaymentPlan is a field that contains two subfields. Every subfield has two digits. First subfield represents number of payments, and second subfield represents the grace period. Examples: "0000" - no payment plan (installments are not allowed), only payment at once. "0600" - payment through 6 installments and without grace period. "0602" - payment through 6 installments, first installment postponed for 2 months. If parameter is not sent - customer will be able to pay in installments only if the merchant has agreed installment payments with the bank, and if his credit card allows him to choose installments.
BrowserLanguage	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `navigator.language` property.
BrowserJavaEnabled	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `navigator.javaEnabled()` property.
BrowserColorDepth	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `screen.colorDepth` property.
BrowserScreenHeight	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `screen.height` property.
BrowserScreenWidth	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `screen.width` property.
BrowserTimezoneOffset	Sending correct value reduces the chance that 3D secure authentication will be required for paying customer. This parameter is mandatory because of new 3D secure regulations. This parameter is received from client browser using `new Date().getTimezoneOffset()` property.
CustomerFirstName	Customer first name.
CustomerLastName	Customer last name.
CustomerAddress	Customer street address.
CustomerCity	Customer city.
CustomerZIP	Customer postal code.
CustomerCountry	Customer country represented in “ISO 3166-1 alpha-2” two letter country code.
CustomerPhone	Customer phone number.
CustomerEmail	Customer e-mail address.

Note that some credit card processors may decline payment if customer data contains diacritic letters so we recommend replacing these parameters with their pairs.
Example: Šš -> Ss, Öö -> Oo

Processing payment

In order to process payment using WSPayAuto, merchant must submit HTML form inside HTML document using HTTP POST method.

Example HTML form:

<form action="[Provided by WSPay]" method="POST">
    <input type="hidden" name="ShopID" value="MYSHOP">
    <input type="hidden" name="ShoppingCartID" value="78">
    <input type="hidden" name="Version" value="2.0">
    <input type="hidden" name="TotalAmount" value="17,00">
    <input type="hidden" name="ReturnURL" value="https://myshop.com/return">
    <input type="hidden" name="ReturnErrorURL" value="https://myshop.com/error">
    <input type="hidden" name="Signature" value="23455eaf0029bac73613eb00d5242dcf2a5e39fa8d65b26905974dcf61bfbccdaaf0963d79dd73adae117ef108378a2b661faaba5c5ff4c33935fae13fad90a7">
    <input type="hidden" name="CreditCardName" value="VISA">
    <input type="hidden" name="CreditCardNumber" value="78">
    <input type="hidden" name="ExpirationDate" value="2603">
    <input type="hidden" name="CardVerificationData" value="988">
    <input type="hidden" name="DateTime" value="20211019133000">
    <input type="hidden" name="PaymentPlan" value="0000">
    <input type="hidden" name="BrowserLanguage" value="en-US">
    <input type="hidden" name="BrowserJavaEnabled" value="false">
    <input type="hidden" name="BrowserColorDepth" value="24">
    <input type="hidden" name="BrowserScreenHeight" value="1080">
    <input type="hidden" name="BrowserScreenWidth" value="1920">
    <input type="hidden" name="BrowserTimezoneOffset" value="-60">
    <input type="hidden" name="CustomerFirstName" value="John">
    <input type="hidden" name="CustomerLastName" value="Doe">
    <input type="hidden" name="CustomerAddress" value="Street address 10">
    <input type="hidden" name="CustomerCity" value="City">
    <input type="hidden" name="CustomerZIP" value="51000">
    <input type="hidden" name="CustomerCountry" value="HR">
    <input type="hidden" name="CustomerEmail" value="john@doe.com">
    <input type="hidden" name="CustomerPhone" value="0986543210">
    <input type="submit" value="Pay">
</form>

Redirecting customer

After successful or unsuccessful transaction WSPayAuto will, depending on the status of transaction, redirect customer to URL defined by merchant using HTTP POST method.

List of parameters that WSPayAuto returns to merchant is defined below.

ApprovalCode, Success and Signature represent three most important parameters for successful transaction process.
If the transaction was successful - ApprovalCode parameter will not be empty, Approved will be 1 and returned Signature parameter will match the signature generated on merchant side.

ShoppingCartID	Unique identification of transaction in merchants system.
WsPayOrderId	Unique identification of transaction in WSPay system.
ApprovalCode	Transaction approval code.
Approved	In case of successful transaction value of Approved parameter will be 1.
TotalAmount	Amount charged to customer. TotalAmount parameter will be formatted without decimal separator character where last two digits will represent minor units.
DateTime	Date and time of transaction. Date format: YYYYMMDDHHmmSS
CreditCardName	Name of credit card brand which customer used for this transaction. List of possible values can be found here.
MaskedPan	Masked credit card number used for this transaction.
PaymentPlan	Number of installments and deferred payments chosen by customer.
Partner	Processor which has processed the transaction. List of possible values can be found here.
STAN	Alphanumeric field that indicates the sequence of transaction.
ECI	Electronic Commerce Indicator - result of 3D Secure authentication.
XID	Transaction ID provided by 3D Secure provider.
CAVV	Card authentication verification value provided by 3D Secure provider.
UCAF	Universal cardholder authentication field provided by 3D secure provider.
CustomerFirstName	Customer first name.
CustomerSurname	Customer last name.
CustomerAddress	Customer street address.
CustomerCity	Customer city.
CustomerZIP	Customer postal code.
CustomerCountry	Customer country.
CustomerPhone	Customer phone number.
CustomerEmail	Customer e-mail address.
ErrorMessage	In case of successful transaction value of ErrorMessage parameter will be empty.
Signature	Represents a signature created from string formatted from following values in a following order using SHA512 algorithm: ShopID SecretKey Success SecretKey ApprovalCode SecretKey Merchant must validate signature to make sure that request is originating from WSPayAuto. Signature generator, available at signature.wspay.info, can be used to test signature validity.

Tokenization

WSPayAuto tokenization allows customers to save credit card information in order to have simpler checkout in the future.
Tokenized credit card is saved on merchants side where it can be used for faster checkouts or for charging customer credit card.

Getting token data

Tokenization is carried out by sending additional "IsTokenRequest" parameter along with the other WSPayAuto form data parameters needed for processing payment using WSPayAuto.

IsTokenRequest	This parameter will tell WSPayAuto to tokenize credit card that will be used in transaction. Parameter must have value: 1

After successful transaction, WSPayAuto will redirect customer to ReturnURL with three additional parameters

Token	Unique identifier that represents tokenized credit card.
TokenNumber	Last 4 digits of the credit card.
TokenExp	Credit card expiration date. Format: YYMM

Payment using token

There are two possible ways to process payment using token after credit card has been tokenized:

WSPayAuto payment using token
Direct payment using token

WSPay will provide additional ShopID that will be used for payment using token.

Who and when can use which method?

There are two main distinctions regarding payment with tokenized card: Customer Initiated Transactions (CIT) and Merchant Initiated Transactions (MIT).

Customer Initiated Transactions are transactions where customer is the one who initiates transaction with saved card.
For example, customer chooses to pay with saved card in checkout process on merchants web shop.

Merchant Initiated Transactions are transaction where merchant submits a transaction with previously saved card without the customer participation.
For example, recurring payment, incremental payment or direct payment.

Transaction type	Merchant in EEA	Merchant outside EEA
CIT	Must use "WSPayAuto payment using token"	May use any method
MIT	Will use "Direct payment using token"	Will use "Direct payment using token"

We recommend using “WSPayAuto payment using token” for all Customer Initiated Transactions since it provides more convenience for merchants in the means of chargeback.

Note that Maestro card requires 3D Secure authentication for every transaction so it cannot be processed using “Direct payment using token” method.

WSPayAuto payment using token

WSPayAuto payment using token is carried out by sending "Token" and "TokenNumber" parameters instead of "CreditCardName", "CreditCardNumber" and "ExpirationDate".

Token string	Unique identifier that represents tokenized credit card. This parameter is received as a result of a previous tokenization process.
TokenNumber string	Last 4 digits of the credit card. This parameter is received as a result of a previous tokenization process.

Direct payment using token

In order to process direct payment using token - request object in JSON format must be sent using HTTP POST to endpoint that will be provided by WSPay.

Request:

{
    "Version": "2.0",
    "ShopID": "MYSHOPTOK",
    "ShoppingCartID": "78",
    "Token": "237038b3-761f-4bf7-a107-a18efa84dde0",
    "TokenNumber": "2152",
    "PaymentPlan": "0000",
    "TotalAmount": "1700",
    "DateTime": "20190722115807",
    "CustomerFirstName": "John",
    "CustomerLastName": "Doe",
    "CustomerAddress": "Address 10",
    "CustomerCity": "City",
    "CustomerZIP": "51000",
    "CustomerCountry": "HR",
    "CustomerPhone": "0911111111",
    "CustomerEmail": "john@doe.com",
    "Language": "HR",
    "Signature": "4a2b4246db90ed60eff677a60fd139f50e09c3e19d14a1503921c70780b912cf04fd44a7b3b6bd3376e4089891a2600aef5aade8979ec546a2ad2bac5d7f8daa"
}

Response:

{
    "WsPayOrderId": "dd9ec33a-0638-47d0-b17a-5de403ae3a3d",
    "ShoppingCartID": "78",
    "CustomerFirstName": "John",
    "CustomerLastName": "Doe",
    "CustomerAddress": "Address 10",
    "CustomerCity": "City",
    "CustomerZIP": "51000",
    "CustomerCountry": "HR",
    "CustomerPhone": "0911111111",
    "CustomerEmail": "john@doe.com",
    "ECI": null,
    "XID": null,
    "CAVV": null,
    "UCAF": null,
    "MaskedPan": "377500*******1234",
    "CreditCardName": "MVISA",
    "PaymentPlan": "0000",
    "ApprovalCode": "610990",
    "ErrorMessage": null,
    "Approved": "1",
    "TotalAmount": "1700",
    "STAN": "38419",
    "ActionSuccess": "1",
    "TransactionDateTime": "20181231233202",
    "Partner": "Pbz",
    "Signature": "4be89181861d5c9759a5032bbadfd4c4f07c0a90b4001155ddfbabb74512fdcb3927f9226c14d1235a9bcd9a6e4d7723289cb55d3bf2863f9519e32c28c7b3d9"
}