Technical Implementation Guide

Transcription

März 2015
Datatrans eCom
Technical Implementation Guide
For Universal Payment Page (UPP)
V 8.43
03.03.2015 CRY
Datatrans AG, Stadelhoferstrasse 33, CH - 8001 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch
1 / 41
To guarantee a proper implementation of the Datatrans Payment Solution make
sure to read the following documents carefully:
 General Information
 Technical Implementation Guide
Please use only the latest version of these documents. Both are available at
http://www.datatrans.ch/en/Payment-solutions/Technical-information/
03.03.2015 CRY
2 / 41
Table of contents
1
INTRODUCTION
8
1.1 ABOUT THIS DOCUMENT
1.2 RESTRICTIONS AND REGULATIONS
1.2.1 RECOMMENDATIONS
1.2.2 FORBIDDEN EXPRESSIONS IN PARAMETER VALUES
1.2.3 FORBIDDEN PARAMETER NAME
1.2.4 OTHERS
1.2.5 SPECIAL CHARACTERS
1.2.6 UNDOCUMENTED FEATURES
1.2.7 SERVICE- AND RETURNURLS
2
AUTHORIZATION
2.1
2.2
2.3
2.3.1
2.3.2
2.3.3
2.4
2.4.1
2.4.2
2.5
2.5.1
2.5.2
2.5.3
2.5.4
2.5.5
3
8
8
8
8
8
9
9
9
9
10
DESIGN
PROCESS OVERVIEW
MANDATORY PARAMETERS TO BE SUBMITTED WITH EACH TRANSACTION
HIGHLY RECOMMENDED PARAMETER
OTHER MANDATORY PARAMETERS
MANDATORY PARAMETERS FOR HIDDENMODE
OPTIONAL PARAMETERS
CUSTOMER ADDRESS DETAILS
AVAILABLE PAYMENT METHODS
AUTHORIZATION RESPONSE
SUCCESSFUL AUTHORIZATION
FAILED / UNSUCCESSFUL AUTHORIZATION
CANCELLED PAYMENT PROCEDURE
POST URL FEEDBACK
PAYMENT PAGE RESPONSE CODES
XML SETTLEMENT AND STATUS REQUESTS
10
10
10
11
11
11
12
13
14
15
15
16
16
17
17
18
3.1 XML SETTLEMENT REQUEST
3.1.1 PROCESS OVERVIEW
3.1.2 MANDATORY PARAMETERS
3.1.3 OPTIONAL PARAMETERS
3.1.4 XML SETTLEMENT RESPONSE
3.2 XML STATUS REQUEST
3.2.1 PROCESS OVERVIEW
3.2.4 XML STATUS RESPONSE
3.2.5 MEANING OF ERROR CODES
3.2.6 MEANING OF RESPONSE (STATUS) CODES
4
SPECIALTIES ABOUT DIFFERENT PAYMENT METHODS
03.03.2015 CRY
18
18
18
18
19
19
20
20
20
20
21
21
22
3 / 41
4.1 AVS - ADDRESS VERIFICATION SERVICE
4.2 CREDITPASS ELV (ELEKTRONISCHES LASTSCHRIFT VERFAHREN)
4.3 CURABILL
4.4 DELTAVISTA
4.5 PAYSAFECARD
4.6 MFGROUP CHECKOUT
4.6.1 MANDATORY PARAMETERS FOR CREDIT CHECK (MFA)
4.6.2 OPTIONAL PARAMETERS FOR CREDIT CHECK (MFA)
4.6.3 OPTIONAL PARAMETERS FOR AUTHORIZATION (MFG)
4.6.4 MFGROUP SPECIFIC RESPONSE PARAMETERS (MFA)
4.6.5 MFGROUP EASY INTEGRATION (PAYMENT METHOD MFX)
4.7 PAYPAL
4.7.1 REFERENCE TRANSACTIONS
4.7.2 LINE ITEMS
4.7.3 PAYPAL EXPRESS CHECKOUT
4.7.4 ADDITIONAL PAYPAL SPECIFIC PARAMETERS
4.8 POSTFINANCE ALIAS
4.8.1 PROCESS STEPS:
4.9 PAYOLUTION
4.10 ADUNO SURPRIZE
4.10.1 ADUNO SURPRIZE SPECIFIC RESPONSE PARAMETERS
4.11 MIGROS BANK PAYMENT
4.11.1 MANDATORY REQUEST PARAMETERS
4.11.2 OPTIONAL REQUEST PARAMETERS
4.11.3 RETURN PARAMETERS
4.12 SWISSCOM EASYPAY
4.12.2 SETTLEMENT
4.12.3 CREDIT
4.13 SWISSBILLING
4.13.1 ADDITIONAL MANDATORY REQUEST PARAMETERS
22
22
22
23
23
23
24
24
24
24
25
25
26
26
26
27
27
27
27
28
28
28
29
29
30
30
30
30
30
30
31
31
31
31
31
5
ALIAS
32
6
SECURITY OPTION
32
6.1 DATA TRANSFER ENCRYPTION
6.2 DIGITAL SIGNATURE
6.2.1 SECURITY LEVEL 0
6.2.4 CREATION OF THE DIGITAL SIGNATURE (VALUE OF PARAMETER SIGN) IN THE REQUEST
6.2.5 SIGN2
7
7.1
TEST PROCEDURE
TEST CREDIT CARDS
03.03.2015 CRY
32
33
33
33
33
34
34
35
35
4 / 41
7.1.1 TEST RULES
7.2 POSTFINANCE
7.3 CREDITPASS ELV (ELEKTRONISCHES LASTSCHRIFT VERFAHREN)
7.4 MYONE
7.5 DANKORT
7.6 PAYPAL
7.7 DELTAVISTA
7.8 MFGROUP CHECKOUT
7.9 ADDRESS VERIFICATION SERVICE
7.10 MAESTRO
7.11 JELMOLI BONUS CARD
7.12 SOFORT ÜBERWEISUNG
7.13 IDEAL
7.14 SWISSBILLING
7.14.1 TEST DATA
7.14.2 TEST RULES
8
8.1
8.2
8.3
8.4
ERROR CODES
35
36
36
36
36
36
37
37
37
38
38
39
39
39
39
39
40
UPP AND XML ERROR CODES
ANTI-FRAUD ERROR CODES
ALIAS ERROR CODES
XML SPECIFIC ERRORS
40
40
41
41
Revision Control
Version
Date
Changed by
7
05.02.2010
Katja Schlegel
7.1
04.03.2010
Katja Schlegel
7.2
09.04.2010
Katja Schlegel
7.3
13.04.2010
Katja Schlegel
7.4
7.5
7.6
12.05.2010
27.06.2010
20.10.2010
Katja Schlegel
Katja Schlegel
Katja Schlegel
7.7
02.12.2010
Katja Schlegel
7.8
7.9
28.12.2010
31.01.2011
Katja Schlegel
Katja Schlegel
8
22.02.2011
Katja Schlegel
8.1
08.03.2011
Katja Schlegel
8.2
28.03.2011
A. Mkrtchyan
8.3
01.04.2011
A. Mkrtchyan
8.4
20.04.2011
A. Mkrtchyan
8.5
05.05.2011
A. Mkrtchyan
Comments / nature of change
2.3.1
Add note about PayPal
2.3.3
Add uppCustomerDetails, new functionality for PayPal
7.9
Add note about PayPal
2.3.1.
Add paymentmethod CashTicket
2.3.2
Note about pos_payment_type
7.5
New test parameters for PostFinance tests
7.14
New payment method SOFORT Überweisung
2.3.1
New payment method SOFORT Überweisung
1.2.3
Restriction in URL endings
1.5.2
Add uppWebResponseMethod
2.3.2
Add uppMobileMode
7.4
Change expiration date on credit cards
4.3
Add new chapter
4.4
Add new chapter
4.5
Add new chapter with Powercard; Vanilla
3.4.1
Add response codes 0, 9, 11, 12, 13 and 30
3.2.1
parameter pmethod is not in use anymore
authorisationCode replaced with uppTransactionId
2.4.1
Add responseCode to list of parameters
2.3.1
Add iDeal to list of payment methods
7.15
Add new chapter - description for iDeal
2.3.2
Remove testOnly parameter
7.2
Remove text with testOnly parameter
3
Updated XML settlement request section,
added XML status re quest service description
2.5
Changed description for PayPal Express Checkout
03.03.2015 CRY
5 / 41
8.5.1
10.05.2011
A. Mkrtchyan
8.5.2
16.06.2011
A. Mkrtchyan
8.6.0
19.08.2011
Oliver Heister
8.6.1
05.09.2011
Oliver Heister
8.7
07.10.2011
Urs Kipfer
8.8
13.12.2011
Oliver Heister
8.9
15.12.2011
Oliver Heister
8.10
8.11
30.12.2011
12.06.2012
Oliver Heister
Oliver Heister
8.12
15.06.2012
Oliver Heister
8.13
22.06.2012
Oliver Heister
8.14
22.08.2012
Oliver Heister
8.15
03.12.2012
Oliver Heister
8.16
07.12.2012
Urs Kipfer
8.17
11.12.2012
Oliver Heiser
8.18
13.02.2013
Oliver Heister
8.19
8.20
06.03.2013
26.03.2013
Katja Schlegel
Urs Kipfer
7.11
4.5.1
3.2.7
7.15
2.4
2.5
4.5
7.11
2.4.1
1.2.5
2.4.2
2.4.1
2.4.1
2.4
4.5
4.5
4.5
4.6
4.7
7.9
8
2.5.1
7.1
2.5.1
*
4.4.1
2.4
2.4.2
2.5.5
2.4.2
*
2.4.2
4.9
Changed acquirers, which support AVS
Removed payment type Vanilla
Added response code 14 (Timeout)
Added restriction about special characters for iDeal
New MFGroup payment methods
New uppCustomerDetails (birthdate, gender, language)
MFGroup specific details
Test process for MFGroup
Remove obsolete parameter cardsqnr
Restrictions on return URLs (ports 80 and 443)
New payment methods
- Reka Card
- iDEAL via SOFORT Überweisung
- PostFinance Card
- PostFinance E-Finance
- Mediamarkt Shopping Card
- Saturn Winner Card
Parameter “pos_payment_type” removed
New Parameter “mfaReference”
New “reqtype” REA (re-authorization)
MFGroup process overview
MFGroup: new input parameter “mfaReference”
new MFGroup specific output parameters
PayPal Reference Transactions
PostFinance Alias
New PayPal test process
New chapter “Error Codes”
authorizationCode is deprecated
Added countries for test cards
removed length of acqAuthorizationCode
correction of spelling errors
Deltavista: added parameter uppCustomerName
Added parameter useTouchUI
Removed deprecated parameter POS
Updated List of error codes
Removed duplicated parameters
Removed http:// URLs
added Payolution payment methods
Payolution details
*
4.6.1
4.6.2
4.6.3
4.6.4
4.2
4.5.1
4.5.4
4.1
4.9
4.9
7.1
2.4
2.4
4.7
4.5.2
4.5.4
New URLs for showcase examples
New parameter names for PayPal Reference Transactions
PayPal line items
PayPal Express Check-Out
Additional PayPal parameters
New chapter “CreditPass”
New parameter value “MFX” for “paymentmethod”
New chapter “MFGroup easy integration”
Parameters for AdressVerificationService
reqtype for Payolution
Standard-Mode for Payolution
Test credit cards: added 06/2015
Added details about uppWebResponseMethod
Added parameter uppReturnMaskedCC
Added missing word “days”.
Add Installment-specific parameters
New Parameter “returnVirtualCardno”
03.03.2015 CRY
6 / 41
8.21
03.06.2013
Oliver Heister
8.22
06.06.2013
Oliver Heister
8.23
19.08.2013
Katja Schlegel
8.24
03.09.13
Katja Schlegel
8.25
12.09.13
Katja Schlegel
8.26
01.10.13
Katja Schlegel
8.27
8.28
8.29
07.10.13
10.10.13
24.10.13
Katja Schlegel
Katja Schlegel
Katja Schlegel
8.30
31.10.13
Katja Schlegel
8.31
19.11.13
Katja Schlegel
8.32
11.12.13
Oliver Heister
8.33
8.33MDP
8.34
8.35
03.03.14
03.03.14
07.03.14
11.03.14
Oliver Heister
Oliver Heister
Katja Schlegel
Katja Schlegel
8.36
31.03.14
Katja Schlegel
8.37
15.09.14
Christoph
Ryser
8.4
15.10.14
Christoph
Ryser
8.41
07.11.14
Peter Sutter
8.42
29.12.14
Christoph
Ryser
8.43
03.03.15
Christoph
Ryser
4.6.2
4.6.2
4.6.2
4.6.3
2.4.2
4.1.1
4.5
4.6.4
7.4
4.3
2.3.2
2.4
2.4
*
8
8.5
4.7.4
1.2.1
4.7.2
2.3.1
2.5.1
8
*
1.2.5
2.4
7.8
7.9
4.2
7.3
4.10
4.11
7.6
2.4
2.4.2
4.2.1
2.4.2
4.12
2.3.3
2.5.1
3.2.4
2.4.2
4.13
7.14
2.4
2.4
2.5.1
2.5.3
7
8
2.4
4.12.2
2.42.4
Changed parameter name “uppCustomerIpAddress”
Added parameter “atOwnRisk”
Added details for parameters “installmentType”, “atOwnRisk”
Added details for parameters “installmentType”, “atOwnRisk”
Added payment method Billpay
Added parameter uppCustomerState
Added note about credits for Installements
Added new parameters uppDisplayShippingDetails and uppForwardCustomerDetails
Add new test credit cards for Visa, MasterCard, Amex
Added Curabill
Add recommendation about Hidden Mode
Add customTheme
Add refno2 and refno3 for ELV
Delete chapters 7.1 – 7.3, replace by dedicated test-account
Information
Add text about error codes
Add chapter
Add pendingPayPal
Add recommendations
Add explanation for PayPal Line items
Move sign-parameter to highly recommended parameters
Add RC 01 and RC02
Add RC 1403
Correct hyperlinks
Add chapter
Add refno2 for Visa/MasterCard (Soft Descriptor)
Add virtualCardno
Add samples for Bad and Unknown Customer
Add restriction (US entity)
Added SEPA paramters for ELV
Added test data for SEPA ELV
Added "Aduno surprize"
Added "Migros Bank Payment"
Update link to PayPal subscription
Add remark for refno2 for sofortüberweisung
Add Billsafe
Add uppElvMandatText
Added Payment Method Swisscom Easypay
Added Swisscom Easypay
correct field type aliasCC
define field type aliasCC
correct field type and description aliasCC
Added Payment Method SwissBilling
Added SwissBilling
Added test data and test rules for SwissBilling
Remove prerequisite for TouchUI
Add parameter uppReturnTarget
Add parameters for dynamic currency conversion (DCC)
Merchant parameters also sent back in case of cancel
Remove Payolution in chapter 7.
Remove 8.5 Other errors
Remove Parameter uppMobileMode
Details for settlement of Swisscom Easypay
Added parmeter merchantAgbLink
03.03.2015 CRY
7 / 41
1 Introduction
1.1
About this document
This document gives you an overview about the implementation of our interface and its parameters and helps you
to implement all the options to process a transaction properly.
* The most common problems with the payment process are doubled or missing transactions.
This kind of problems is in most of the cases the consequence of improper payment process implementation.
We highly recommend reading the document “General Information about the payment process with Datatrans”.
 In description of field types following acronyms are used: N - means numeric value (e.g. 1234), A - means
alphabetic value (e.g. abc), AN means alphanumeric value (e.g. abs123), MM means month (e.g. 03 for March),
YY means year (e.g. 11 for 2011). For example, N8 means a numeric value of length 8 (e.g. 33145687).
 There are also some code examples on http://www.datatrans.ch/showcase/ which are useful for a basic implementation.
1.2
1.2.1
Restrictions and regulations
Recommendations
Please note that we do not recommend using iFrames for external payment methods.
Refer to this chapter for the details which are external payment methods and which are not.
1.2.2
Forbidden expressions in parameter values
Do not use the following expressions in parameter values.
Script
onload
onunload
onclick
ondblclick
onkey
onmouse
onfocus
onblur
onselect
onchange
1.2.3
Forbidden parameter name
Do not use the following expression as parameter name.
03.03.2015 CRY
8 / 41
submit
1.2.4
Others
The payment has to be processed in a visible frame with a minimum size of 390 x 400 pixels.
We do not send parameters back to a return URL that ends with .html or .htm. Please use all other endings.
1.2.5
Special characters
Use ASCII for the reference number. Special characters in the “refno” will be changed as follows:
ä, ö, ü, â, é, è to a, o, u, a, e and so on.
1.2.6
Undocumented features
Please note that undocumented features can be changed or disabled by Datatrans at any time.
We highly recommend implementing your interface to Datatrans according to our specifications to guarantee a
proper payment process.
1.2.7
Service- and returnURLs
All service and return URLs (Post URL, Success URL, Error URL, Cancel URL) are restricted to the ports 80 (http) and
443 (https)
03.03.2015 CRY
9 / 41
2 Authorization
2.1
Design
You can choose between Standard and Hidden Mode. Standard Mode shows the consumer the
Payment Method Selection Page from Datatrans, which can be customized individually in the
Web Admin Tool.
Hidden Mode shows the consumer the payment page programmed by the merchant and skips the Payment
Method Selection Page from Datatrans. There are some additional parameters which have to be used in the Hidden Mode. It is necessary to have a valid SSL certificate if you use the Hidden Mode. But we highly recommend
using an SSL certificate for Standard Mode too.
2.2
Process overview
The UPP interface directs the consumer to the URL of the service provider and posts the parameters.
The final payment transaction response reaches the merchant in two ways:
 Response URL
The consumer is directed with posted parameters back to the merchant (to the URL of his choice).

Post URL
If a Post URLs is used, parallel to the call of the merchant’s web page, the transaction response is directly sent to the server application of the merchant.
Starting the payment service, the merchant’s application directs the consumer to the service URL (e.g. form action)
and passes all mandatory and optional parameters to the service.
Once the transaction is completed, the consumer is directed back to the return URL of the shop application.
Service URLs:

UTF-8 encoding:

ISO encoding:
2.3
https://payment.datatrans.biz/upp/jsp/upStart.jsp
https://payment.datatrans.biz/upp/jsp/upStartIso.jsp
Mandatory parameters to be submitted with each transaction
* All parameters are case specific
merchantId
amount
currency
refno
N10
A3
AN18
Unique Merchant Identifier (assigned by Datatrans)
Transaction amount in cents or smallest available unit of the currency
Transaction currency – ISO Character Code (CHF, USD, EUR etc.)
Merchant reference number; note: unique value for PayPal; can be defined as
unique value for all other payment methods, too. Please refer to
[email protected] for details.
03.03.2015 CRY
10 / 41
2.3.1
Highly recommended parameter
We highly recommend adding at least the sign level1 to your request.
sign
2.3.2
This parameter may be used according to the merchant’s
security level settings. For details please refer to the chapter
“Security Option”.
Other mandatory parameters
The following parameters either have to be submitted with each transaction or configured / pre-set in the merchant administration tool https://payment.datatrans.biz
successUrl
This parameter represents the URL of the merchant’s shop
application, where the consumer should be redirected to after
a successful transaction
a failed transaction
cancelling the payment dialog
errorUrl
cancelUrl
2.3.3
Mandatory parameters for HiddenMode
paymentmethod
A3
cardno or aliasCC
AN20
expm
expy
hiddenMode
MM
YY
cvv
N4
Payment method code; please refer to chapter 2.4.2 for detailed listing;
this parameter is optional for Standard Mode
Credit card number or alias for credit card number.
Optionally used for PostFinance Alias or for PayPal Reference Transactions
Expiry month of the card
Expiry year of the card
Validates required parameters for hidden mode; sends process to error
page if validation fails; value: “yes”
CVV code (mandatory for initial transactions)
We highly recommend to validate, if the fields are filled our and if they are correct.
(Numeric fields only contain number, alphabetical field only contain letters etc.)
03.03.2015 CRY
11 / 41
2.4
Optional parameters
useAlias
language
A2
Post URL
reqtype
uppWebResponseMethod
Merchant Specific Parameters
useTouchUI
customTheme
AN50
mfaReference
uppReturnMaskedCC
N10
refno2
AN27
Requests the CC alias, this option needs to be activated by Datatrans; value: “yes”
This parameter specifies the language (language code) in which
the payment page should be presented to the cardholder.
The following ISO-639 2 character language codes are supported:
- de (German)
- en (English)
- fr (French)
- it (Italian)
- es (Spanish)
- el (Greek)
- no (Norwegian)
- da (Danish)
This parameter can’t be passed with the HTTPS Post message; it
has to be configured in https://payment.datatrans.biz. For further
details please refer to chapter “Post URL Feedback”.
The request type specifies whether the transaction has to be immediately settled or authorized only. There are two request
types available:
“NOA” authorization only
“CAA” authorization with immediate settlement in case of successful authorization; if “reqtype” is not submitted the transaction
is processed according to the setting in the Web Admin Tool (section “UPP Administration”).
“GET” if the response is wished to be received as a GET. “POST” if
the response is wished to be received as a POST.
Default for “.htm” URLs ist “GET”, for all other endings “POST”.
The merchant can invent and submit any number of own parameters. These parameters are returned to the Success-, Error- and
Post URL. Restrictions:
- The maximum length is limited to 300 characters
- Line brakes are not allowed
"yes" enforces touch mode
"auto" enables touch mode when touch device detected, "no"
disables touch mode
Style Sheet used for TouchUI, please contact Datatrans for further
information.
For payment method “MFA” only (see also chapter 4.5)
“yes” – requests the return of the masked credit card number to
the merchant in field “maskedCC”. See chapter 2.5.1.
For ELV; lines 3 to 4 on the customer invoice
For sofortüberweisung; will be forwarded to reason_2 (visible on
customer invoice), if this value is empty, we will forward the
“refno” and use “Shop reference” as reason_1
03.03.2015 CRY
12 / 41
refno3
virtualCardno
uppReturnTarget
AN27
N19
merchantAgbLink
2.4.1
For Visa/MasterCard (Soft Descriptor);
depending on the acquirer use these restrictions:
Chase Paymentech
AN22
ConCardis
AN17
* Please refer to Datatrans before implementing the
Soft Descriptor.
For ELV only; lines 3 to 4 on the customer invoice
For MFG only, refer to chapter MFGroup
“_top” if return URL should be opened full screen when payment
starts in an iFrame.
An external link to the merchant’s terms and conditions. Will be
displayed above the payment button with the text:
“With your payment you accept our terms and conditions.”
Customer address details
It is now possible to submit customer address details to the Datatrans payment application. These details are
stored in the Web Admin Tool, and they can be searched and viewed under
https://payment.datatrans.biz. All address parameters are optional.
uppCustomerDetails
uppCustomerTitle
uppCustomerName
uppCustomerFirstName
uppCustomerLastName
uppCustomerStreet
uppCustomerStreet2
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
uppCustomerPhone
uppCustomerFax
uppCustomerEmail
uppCustomerGender
uppCustomerBirthDate
uppCustomerLanguage
AN30
AN40
AN40
AN40
AN40
AN40
AN40
A3
AN10
AN40
AN40
AN40
A6
Date
A2
* Pilot parameter, to be submitted with value:
“yes” - if address details are submitted and if the data should be
stored in the Web Admin Tool, or
“return” (only available for PayPal Express Checkout) – if address
details should be returned from PayPal to the merchant.
Title of customer
Name of customer
* First name of customer
* Last name of customer
* Street address
Second street address
* City
* ISO country code (alpha)
* Postal code
Phone number
Fax number
E-mail address
Gender of customer; values: “male” / “female”
Customer date of birth; format: “dd.mm.yyyy” or “yyyy-mm-dd”
Language of customer; values: en, de, fr, it
* With PayPal (Express Checkout) you have the possibility to check if the address that was entered by the customer matches with the address he has registered at PayPal. Use therefore the uppCustomerDetails parameters with
value “return”.
03.03.2015 CRY
13 / 41
2.4.2
Available Payment Methods
Parameter values for “paymentmethod”:
VIS
ECA
AMX
BPY
VISA
MasterCard
American Express
Billpay
BSF
Billsafe
CUR
DIN
DEA
DIB
Curabill
Diners Club / Discover
*iDeal
SOFORT Überweisung
DII
DNK
DVI
ELV
EPS
ESY
JCB
JEL
MAU
MMS
MFA
MFG
MFX
MNB
MYO
PAP
PEF
PFC
PSC
PST
PYL
PYO
REK
SWB
SWC
iDEAL via SOFORT Überweisung
Dankort
Deltavista
German ELV
* EPS Online-Überweisung
*Swisscom Easypay
JCB
Jelmoli Bonus Card
Maestro
Mediamarkt Shopping Card
MFGroup Check Out (Credit Check)
MFGroup Financial Request (authorization)
MFGroup Easy integration
* Moneybookers only with reqtype CAA
Manor MyOne Card
* PayPal
* Swiss PostFinance – PostFinance E-Finance
* Swiss PostFinance – PostFinance Card
* Paysafecard
* CashTicket
Payolution Installments; also see chapter 4.9
Payolution Invoice; also see chapter 4.9
Reka Card
SwissBilling
Saturn Winner Card
Specification to be found here:
http://pilot.datatrans.biz/showcase/doc/Billpay.zip
Specification to be found here:
https://www.datatrans.ch/showcase/authorisation/billsafe
No special characters are allowed in the refno
credits are not possible, unless you have a bank account
at sofortbank
only in Standard Mode available
Refer to chapter MFGroup
* For all external payment methods only the parameter “paymentmethod” is required. card number, expiry date,
and CVV are not supported. These unsupported fields can either be omitted or submitted without value.
03.03.2015 CRY
14 / 41
2.5
Authorization Response
2.5.1
Successful Authorization
This response is sent concurrently to the successUrl and the post URL, which are provided by the merchant.
uppTransactionId
authorizationCode
N18
N9
responseCode
N4
responseMessage
refno
amount
AN18
currency
pmethod
A3
A3
reqtype
acqAuthorizationCode
A3
AN
status
uppMsgType
aliasCC
AN20
maskedCC
sign2
virtualCardno
DccAmount
N19
N
DccCurrency
A3
DccRate
N
Unique transaction identifier
Internal transaction number (deprecated, use acqAuthorizationCode)
Authorization response code
01
successful authorisation
02
successful authorisation without liability shift
Response message text (e.g. TRX AUTHORISED)
Merchant order reference number
Transaction amount in units/cents (the smallest unit of the currency) (e.g. 123.50 = 12350)
Transaction currency
The payment method by which the transaction has been made
(e.g. VIS, ECA...)
NOA or CAA
Authorization code returned by credit card issuing bank (length
depending on payment method)
Constant “success”
Constant “web” for successUrl, “post” for postUrl
Alias for credit card number, for PostFinance or for PayPal Reference Transactions – optional
Masked credit card number – optional
(only returned with alias Request or when uppReturnMaskedCC=”yes”)
Returned only if “sign” has been submitted with authorization (see chapter “Security Options”)
Virtual card number for MFGroup Checkout – optional
DCC amount in home currency chosen by cardholder. In cents or
smallest available unit of home currency
Cardholders home currency – ISO Character Code (USD, EUR
etc.)
Applied exchange rate of DCC provider (e.g. 0.855304)
* DCC parameters returned only if DCC is activated and cardholder has chosen to pay in home currency.
The service always returns all other merchant parameters sent along with the request.
* Response code 02: You will receive a response code 02, if the issuer doesn’t claim liability. In case of a charge
back the merchants will have the liability.
These transactions are declined on default. If you would like to accept transactions with a response code 02,
please modify the configuration in the Web Admin Tool > UPP Administrator.
03.03.2015 CRY
15 / 41
2.5.2
Failed / Unsuccessful Authorization
This response is sent to errorUrl and/or post URL provided by the merchant.
uppTransactionId
errorCode
errorMessage
errorDetail
refno
amount
N18
N7
currency
pmethod
A3
A3
reqtype
status
uppMsgType
acqErrorCode
A3
AN18
N
Error code
(please refer to chapter 8)
Error response message text (example: INVALID VALUE)
Error detail text (example: CARD NUMBER NOT VALID)
transaction amount in units/cents (the smallest unit of the currency) (e.g. 123.50 = 12350)
The payment method by which the transaction has been made
(VIS, ECA...)
NOA or CAA
Constant “error”
Constant “web” for errorUrl, “post” for postUrl
Contains the error code sent by the acquirer
* The service always returns all other merchant parameters sent along with the request.
2.5.3
Cancelled Payment Procedure
If the cardholder decides to cancel the payment process and to return to the shop without payment, the response
is sent back to the cancelUrl.
uppTransactionId
refno
amount
N18
AN18
currency
status
uppMsgType
A3
Transaction amount in units/cents (the smallest unit of the currency) (e.g. 123.50 = 12350)
Constant “cancel”
Constant “web” for cancelUrl
* The service always returns all other merchant parameters sent along with the request.
03.03.2015 CRY
16 / 41
2.5.4
Post URL Feedback
A merchant can collect successful or failed transactions on data-oriented Post URL. This Post URL is used for faceless (server to server) data communication.
* Note that for security reasons the Post URL cannot be submitted as a parameter. It has to be configured in the
merchant’s administration tool (https://payment.datatrans.biz).
The Merchant can choose one of the following options (according to the “Post data format” setting in Web Admin Tool)
 Get pure XML data

2.5.5
Get posted HTML form with all necessary parameters posted into the request.
Payment page response codes
This is an extract from possible error codes. Note that this list is dynamic and not complete.
You find a detailed response message for every transaction in the Web Admin Tool.
It’s not recommended to show the exact error code to the consumer due to fraud risk.
03.03.2015 CRY
17 / 41
3 XML Settlement and Status requests
3.1
XML Settlement request
The merchant application directly connects (server to server via standard socket) to the service URL, writes the
XML document into this connection and reads the XML response documents from there.
URL: https://payment.datatrans.biz/upp/jsp/XML_processor.jsp
3.1.1
Process overview
This interface can be used for the settlement of authorized transactions and for credit notes of settled debit transactions. Transactions due for settlement can be sent as a formatted XML message via an http request to the Datatrans payment application. After the validation of the XML message the merchant application receives back a
status response. The settlement procedure is then performed by the payment application from Datatrans. The
merchant’s shop gets back an XML-formatted message containing all necessary data about the settled transactions.
3.1.2
Mandatory parameters
merchantId
amount
currency
refno
uppTransactionId
3.1.3
AN3
AN18
N18
Unique Merchant Identifier (allocated by Datatrans at merchant
registration process)
Transaction amount in cents (the smallest unit of the currency)
(e.g. 123.50 = 12350)
* Must not exceed the authorized amount!
Transaction currency - ISO character code (CHF)
Original and unique transaction id.
* Is returned with the authorization request!
Optional Parameters
reqtype
transtype
COA – Settlement debit (transtype 05 required) DEFAULT
COA – Settlement credit (transtype 06 required), only for settled
transactions
REF – Submission of acqAuthorizationCode after referral; requires
acqAuthorizationCode; changes status to authorized
REC – Submission of acqAuthorizationCode after decline;
requires acqAuthorizationCode; changes status to settled
STA – Transaction status request; see response codes below
DOA – Transaction cancel request; used for authorization reversal
REA – ** Re-authorization of old transaction
05 – debit transaction DEFAULT
03.03.2015 CRY
18 / 41
sign
errorEmail
AN50
06 – credit transaction
Required for reqtype REF and REC
According to merchant’s security level setting
E-Mail address, one e-mail address can be used
The system sends an e-mail to this address in case of a failed settlement
* Note that all parameters marked as DEFAULT are set with the corresponding default value if they are not present or no value is set.
** reqtype REA has to be submitted with the uppTransactionId returned by the first authorization request; moreover, reqtype REA is only supported for credit card transactions with status “authorized”.
3.1.4
XML Settlement response
The response XML document contains the same parameters as the request document.
Additional parameters returned upon successful settlement are:
responseCode
responseMessage
N4
Settlement response code
Settlement response message text
N7
Error code
Only returned in case of error:
errorCode
errorMessage
errorDetail
Only returned in case of credit:
uppTransactionId
authorizationCode
N18
N9
AN7
Original TransactionId
Original authorization code
Original acquirer’s authorization code returned by acquirer
Complete list of XML Settlement response parameters can be found on Datatrans Showcase webpage:
http://www.datatrans.ch/Showcase/Settlement/XML-Settlement-request/Using-transaction-id/
The meaning of error and response codes is represented in bellow in “Meaning of returned XML codes”
3.2
XML status request
The merchant application directly connects (server to server via standard socket) to the service URL, writes the
XML document into this connection and reads the XML status response from there.
URL: https://payment.datatrans.biz/upp/jsp/XML_status.jsp
03.03.2015 CRY
19 / 41
3.2.1
Process overview
This interface can be used for requesting the status of transaction. After the validation of the
XML message the merchant application receives back a status response. The merchant’s shop gets back an XMLformatted message containing all necessary data about the status of transaction.
3.2.2
merchantId
Unique Merchant Identifier (allocated by Datatrans at
merchant registration process)
At least one of following parameters must be
submitted
uppTransactionId
(preferred one)
authorizationCode
refno
3.2.3
N9
AN18
Original
and
unique
transaction
* Is returned with the authorization request!
Original authorization code
id.
Optional Parameters
reqtype
3.2.4
N18
STA – Standard (default) transaction status request;
STX – extended transaction status request (see XML status response below)
XML Status response
The response XML document returned upon successful settlement contains:
responseCode
responseMessage
N4
Settlement response code
Settlement response message text
N7
Error code
Only returned in case of error:
errorCode
errorMessage
errorDetail
Only returned in case of extended status request (reqtype STX):
uppTransactionId
maskedCC
aliasCC
N18
AN12
AN20
expm
expy
MM
YY
Original TransactionId
Masked credit card number
Alias for credit card number, for PostFinance or for PayPal
Reference Transactions
Expiry month of the card
Expiry year of the card
Complete list of XML Status response parameters can be found on Datatrans Showcase webpage:
03.03.2015 CRY
20 / 41
http://www.datatrans.ch/Showcase/Status/XML-Status-request/Using-transaction-id/
The meaning of error and status codes is represented bellow in “Meaning of returned XML codes”
3.2.5
Meaning of error codes
These codes are returned in XML response if error happened in parameter called errorCode
Error Code
2000
2001
2002
2011
2012
2013
2014
2021
2022
2098
2099
3.2.6
Code Message
Access denied by protocol control
Input document missing
Error building document
Root element invalid
Body element missing
merchantId missing
Element missing
Missing value
Invalid value
Database error
XML processing error
In parameter Error Detail see for:
Name of missing element
XML format error
Unexpected root element of XML document
Attribute ‘merchantId’ in body element missing
Name of element, where value is missing
Name of element that contains invalid value
Meaning of response (status) codes
These codes are returned in XML response in parameter called responseCode
Response Code
0
1
2
3
4
5
6
7
8
9
11
12
13
14
20
21
30
Description
Incomplete transaction
Transaction ready for settlement (trx authorized)
Transaction debit waiting for daily settlement process
Transaction credit waiting for daily settlement process
Transaction declined or other error
Transaction in referral status
cancelled by merchant after successful authorization
cancelled by user (before authorization process)
Authentified (applies for split trx only)
Authentified and authorized (applies for split trx only)
Pending transaction
Timeout
Record not found
Transaction already settled
Multiple one transaction found
03.03.2015 CRY
21 / 41
4 Specialties about different payment methods
4.1
AVS - Address verification service
* For AVS the merchant needs to have an US entity as well as contracts for VISA and MasterCard with either
Worldpay or Chase Paymentech.
Verify the address of your customer with this service.
It can be used on the Web interface and also for an XML request.
4.1.1
merchantId
amount
currency
refno
uppCustomerLastName
uppCustomerStreet
uppCustomerZipCode
uppCustomerCity
Unique Merchant Identifier (allocated by Datatrans at merchant registration
process)
AN3
AN18
AN40
AN40
AN40
AN10
AN40
Transaction currency - ISO 4217 character code (CHF)
Merchants order reference number
First name of customer
Last name of customer
Street address
Postal code
City
Datatrans has to activate the Fraud option, please contact us in advance.
You will receive some return codes which you can decline or accept individually. There options must be set in the
Web Admin Tool.
4.2
CreditPass ELV (Elektronisches Lastschrift Verfahren)
"Old" parameters for ELV:
bankaccount
bankrouting
N10
N8
Bank account number
Bank routing number (“Bankleitzahl”)
New parameters for SEPA ELV:
bankiban
bankbic
elvMandateID
AN34
AN11
AN35
IBAN
BIC (optional)
ID of mandat (optional). If empty the content of refno will be used.
Please note that the fields for SEPA (bankiban, bankbic, elvMandateID) are curently only available on the test system. Please contact the telego! GmbH about the availability on the production system.
03.03.2015 CRY
22 / 41
4.2.1
Optional Parameters
refno2
refno3
uppElvMandatText
AN27
AN27
line 3 on the customer invoice
line 4 on the customer invoice
Default text can be overwritten. No HTML-tags are allowed exept <<BR>>
German ELV transactions can be processed with an integrated credit and address check. The merchant has to
agree with CreditPass (Telego) the test rules. Each test rule is referred to by a “Purchase Type”.
The CreditPass credit check is based on the “uppCustomerDetails” (see chapter 2.4.1).
uppCustomerDetails
PurchaseType
uppCustomerLastName
uppCustomerStreet
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
N1
AN40
AN40
AN40
AN40
A3
AN10
Pilot parameter, to be submitted with value “yes” if address details are
submitted and if the data should be stored in the Web Admin Tool
Purchase Type according to agreement with Telego
Street address
City
ISO country code (alpha)
Postal code
CreditPass transactions can be processed as https form post or as XML authorization requests. Please refer to the
technical showcase page (www.datatrans.ch/showcase) for implementation examples.
4.3
Curabill
merchantId
amount
currency
refno
paymentmethod
AN3
AN18
Unique Merchant Identifier (allocated by Datatrans at merchant registration process)
In the smallest available unit
CUR
Also, there is a Curabill-XML document to be submitted. The content of this document has to be verified with
Curabill. Please contact your contact person at Curabill directly.
For a sample refer to http://www.datatrans.ch/Showcase/Authorisation/Curabill/
4.4
Deltavista
Deltavista is a European service for merchants who accept payments by invoice. This service allows checking the
consumer’s creditworthiness and address.
It requires the same parameters as described in the previous chapters but the parameter values are different.
03.03.2015 CRY
23 / 41
4.4.1
merchantId
amount
currency
refno
paymentmethod
hiddenMode
uppCustomerLastName
uppCustomerStreet
uppCustomerStreet2
uppCustomerCity
uppCustomerCountry
uppCustomerState
uppCustomerZipCode
uppCustomerType
uppCustomerName
AN3
AN18
AN40
AN40
AN40
AN40
AN40
A3
AN40
AN10
A1
AN40
process)
Can be 0
DVI
yes
Street address
House number
City
ISO 4217 country code (alpha)
State, e.g. Californa for USA
Postal code
“P” or “C” (individual person or company)
Name of company (for uppCustomerType “C”)
All requests are visible in the Web Admin Tool.
4.5
Paysafecard
The settlement has to follow the authorization within one hour, except you have a different agreement with
Paysafecard.
4.6
MFGroup Checkout
MFGroup Checkout is a Swiss service for credit check and monthly invoice. It requires the basic parameters according chapter 2. The recommended implementation is the following:
1. Credit Check; if successful a virtual card number is returned; payment method “MFA”
2. Listing of available payment methods; the merchant presents MFGroup Checkout as payment method only if a virtual card number has been returned by the credit check
3. Authorization; authorization process according to chapter 2; payment method “MFG”
Please note that credits for Powerpay Installements are not possible.
4.6.1
Mandatory parameters for Credit Check (MFA)
merchantId
amount
currency
AN3
process)
Can be 0
03.03.2015 CRY
24 / 41
refno
paymentmethod
hiddenMode
uppCustomerLastName
uppCustomerStreet
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
uppCustomerGender
uppCustomerLanguage
4.6.2
AN18
AN40
AN40
AN40
AN40
A3
AN10
A6
Date
A2
Optional parameters for Credit Check (MFA)
uppCustomerPhone
uppCustomerEmail
mfaReference
AN40
AN40
N10
shoppingCartType
AN30
uppCustomerIpAddress
installmentType
AN30
AN30
4.6.3
MFA = credit check Only
MFX = credit check and authorization at once (see chapter 4.5.4)
Yes
Street address and house number
City
Postal code
Gender of customer; values: “male” / “female”
Customer date of birth; format: “dd.mm.yyyy” or “yyyy-mm-dd”
Language of customer; values: en, de, fr, it
Phone number
E-mail address
Customer reference in MFGroup system; returned by the first
MFA request of a customer; helps to identify the existing account
and credit limit of the customer
Merchant can agree with Intrum Justitia to send them types of
shopping carts, to prevent misuse of their online-shop. MFGroup
just forwards the values sent in this field to Intrum.
optional, customers IP-address
The fields that are necessary to offer paying on installments to the
customers are the following: <installmentNumber>, <installmentAmount>, <installmentFees>, < installmentInterests>. We will
send those fields in the response if the field <installmentType> is
i.e. “4in12”, which means 4 payments in 12 months.
Merchant need special agreement for this option with MFGroup.
This parameter has to be sent for MFA and MFG.
Optional parameters for Authorization (MFG)
installmentType
AN30
atOwnRisk
AN30
The fields that are necessary to offer paying on installments to the
customers are the following: <installmentNumber>, <installmentAmount>, <installmentFees>, < installmentInterests>. We will
send those fields in the response if the field <installmentType> is
i.e. “4in12”, which means 4 payments in 12 months.
Merchant need special agreement for this option with MFGroup.
This parameter has to be sent for MFA and MFG.
This field gives the merchant the possibility to take the risk for
some transactions, especially when the <amount> is higher than
the <mfaAvailableCredit> of the customer. Please consider, that
the merchant has to be authorized by MFGroup first, to do
“atOwnRisk”-transactions.
03.03.2015 CRY
25 / 41
The MFGroup credit check can be submitted as XML authorization request or https Post redirect. Please refer to
[email protected] to get more information about the XML process.
All requests are visible in the Web Admin Tool.
4.6.4
MFGroup specific response parameters (MFA)
mfaAvailableCredit
mfaMaximalCredit
mfaReference
mfaCreditRefusalReason
mfaResponseCode
errorDetail
installmentNumber
installmentAmount
installmentFees
installmentInterests
4.6.5
the credit of the customer currently available for purchases
the maximum credit available for this customer
the customers reference in MFGroup system which can be saved and used to retrieve the customer and his account for further purchases; to be submitted with all
subsequent transactions of the same customer
contains the result of the credit check, which is “null” in case of success
response code from MFGroup
is returned in error case, only; values:
- “unknown address”: customer is unknown / was not found
- “other”: request was declined because of some not communicated reason
and does therefore not receive credit
The number of installments the customer using the payment on
installments has to pay
The amount of each installment the customer has to pay (including installment fees
and installment interest), amount in the smallest available unit
The amount of fees included in the installments, amount in the smallest available
unit
The amount of interests included in the installments, amount in the smallest available unit
MFGroup easy integration (payment method MFX)
With the standard integration of the MFGroup monthly invoice the credit check and the authorization request
have be processed in two separate steps. However, it’s also possible to process both steps in one single request.
The transaction has to be submitted either in hidden mode or standard mode. The only difference is that “paymentmethod” has to be submitted with value “MFX”.
In this process, there is in most cases no need to get the MFGroup virtual card number. However, if the merchant
needs it anyway, it can be obtained with the submission of the following parameter:
returnVirtualCardno
virtualCardno
4.7
to be submitted with value “yes”; returns the MFGroup virtual cardnumber
returned to success URL with virtual card number as value
PayPal
Please note the following restrictions:
IIt’s not possible to process PayPal transactions in an Iframe
IIPayPal authorizations expire within 30 days; older transactions can’t be recovered
03.03.2015 CRY
26 / 41
4.7.1
Reference Transactions
This option allows to process recurring transactions as a back-end process without user authentication. It is therefore suitable for monthly subscription billing or mobile applications with one click check-out.
1. Authorization / Customer Registration
Payment Page authorization request according to chapter 2 with additional parameter
“useAlias”=”yes”
2. Recurring Transactions via payment page (UPP)
Payment page request in hidden mode according to chapter 2 with the additional parameter
“aliasCC”; the value is the billing agreement ID returned by the customer registration process
3. Recurring Billing via XML authorization request
XML request according to sample on http://www.datatrans.ch/Showcase/Authorisation/XMLAuthorisation/
4.7.2
Line Items
With this feature the shopping cart items can be submitted to PayPal; they will then be displayed in the PayPal
check-out page.
Parameters:
ITEMAMT
TAXAMT
SHIPPINGAMT
L_NAMEn
L_AMTn
L_Numbern
L_Descn
L_QTYn
L_TAXAMTn
N
N
N
AN20
N
N
AN20
N
N
Header: total amount of all items (L_AMT0 * L_QTY0) + (L_AMT1 * L_QTY1) + ....)
Header: total tax amount in cents (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 *
L_QTY1) + ...
Header: total shipping fees excluding tax
Line item: name
Line item: price per items in cents
Line item: article number
Line item: description
Line item: number of items
Line item: tax amount
The parameter “amount” is calculated from ITEMAMT + SHIPPINGAMT + TAXAMT
n stands for the number of items, starting with 0. E.g. L_NAME0=Wine, L_NAME1=Whiskey, etc.
4.7.3
PayPal Express Checkout
PayPal Express Checkout is a good way to make the check-out process more convenient for the shopper and to
get PayPal advanced seller protection. Please refer to PayPal for more information about Express Check-Out.
For the technical implementation please refer to this chapter of this document.
4.7.4
Additional PayPal specific parameters
imageURL
URL
URL for image to be displayed in the PayPal check-out page
03.03.2015 CRY
27 / 41
cpp-cart-border-color
PayPalAllowNote
Hex Code
yes / no
uppForwardCustomerDetails
uppDisplayShippingDetails
yes/no
yes/no
pendingPayPal
yes
4.8
PayPal border color; to be submitted as hex color code
Defines wether the text field for merchant notification should be
visible for the shopper
Regulates wether the customer details are forwared to PayPal or not
Regulates wether the shipping details are displayed or not (note
uppForwardCustomerDetails and uppDisplayShippingDetails set
“no” if the shipping details should not be shown on the PayPal
page.
This parameter will be returned, only if the PayPal transaction is in a
pending status. Pending means that the transaction coundl’t be
confirmed by PayPal.
PostFinance Alias
This option allows to process recurring transactions as a back-end process without user authentication. It is therefore suitable for monthly subscription billing or mobile applications.
4.8.1
Process steps:
1. Authorization / Customer Registration
Payment Page authorization request according to chapter 2 with additional parameter
“useAlias”=”yes”
2. Recurring Transactions via payment page (UPP)
Payment page request in hidden mode according to chapter 2 with the additional parameter
“aliasCC”; the value is the alias (“aliasCC”) returned by the customer registration process
3. Recurring Billing via XML authorization request
XML request according to sample on http://www.datatrans.ch/Showcase/Authorisation/XMLAuthorisation/ with <aliasCC>
4.9
Payolution
Mandatory parameters for Payolution invoice (paymentmethod PYO) and Payolution installments (paymentmethod
PYL)
merchantId
amount
currency
refno
paymentmethod
uppCustomerLastName
uppCustomerStreet
uppCustomerStreet2
uppCustomerCity
N10
AN3
AN18
AN40
AN40
AN40
AN40
AN40
process)
Transaction amount in cents or smallest available unit of the currency
PYO / PYL
Street address
house number
City
03.03.2015 CRY
28 / 41
uppCustomerCountry
uppCustomerZipCode
uppCustomerEmail
reqtype
uppCustomerDetails
uppCustomerType
A3
AN10
AN40
A1
Postal code
E-mail address
“NOA” authorization only
“CAA” authorization with immediate settlement in case of successful authorization
yes (if the customer data should be stored in the Web Admin Tool) / no
P (Person) or C (Company)
Optional parameteters for Payolution invoice (paymentmethod PYO) and Payolution installments (paymentmethod
PYL)
Date
uppCustomerName
uppCustomerAirlineDeparture
uppCustomerAirlineRoute
uppCustomerAirlineFlightNumber
uppCustomerAirlineBookingCode
uppCustomerAirlineFrequentFlyer
hiddenMode
AN40
AN40
AN40
AN40
AN40
AN40
Customer date of birth; format: “dd.mm.yyyy” or “yyyy-mm-dd”.
Mandatory for B2C transactions only.
Name of company (for uppCustomerType “C”)
2012-12-30 17:00
VIE,MUC,LHR
OS1234,LH1234
yes
4.10 Aduno surprize
Aduno surprize is a loyality system from Aduno Gruppe.
4.10.1 Aduno surprize specific response parameters
adunoAmtAuthOriginal
N
amount
N
adunoTotalDiscountAmount
adunoLoyDisclMsg
adunoCampaignText
adunoCampaignSummaryText
N
AN1024
AN1024
AN1024
adunoLoyRefNum
AN16
adunoLoyResltMsg
adunoLoyReslt
adunoPtAvail
adunoPtEarn
adunoPtPrev
AN1024
N5
N9
N9
N9
Original transaction amount in cents or smallest available unit
of the currency
New transaction amount in cents or smallest available unit of
the currency
Sum of all discounts
Used for disclaimer texts for sales slips.
Campaign text (either confirmation or the decline message)
Campaign summary text that can be used on the POS receipt (validity)
Unique reference number provided by the Loyalty system. Used as
reference and matching criteria for Loyalty transactions.
Contains the explanation text to the adunoLoyReslt
Loyalty result code, which indicates the result of a loyalty request.
Used to show to the cardholder the remaining points.
Used to show to the cardholder the points earned in a transaction.
Used to show to the cardholder his point balance before the cur-
03.03.2015 CRY
29 / 41
adunoPtRedeem
rent loyalty transaction.
Used to show to the cardholder the points redeemed in a transaction.
N9
4.11 Migros Bank Payment
Migros Bank Payment is a cardless payment method from Migros Bank with direct debit during payment process
and payment authorization by smartphone.
4.11.1 Mandatory request parameters
merchantId
amount
currency
refno
AN3
AN18
process)
In the smallest available unit
4.11.2 Optional request parameters
paymentmethod
mdpUserId
useAlias
mdpAlias
A3
A18
A3
A18
"MDP"
Username of registered MDP customer.
"yes" (if an alias should be requested)
needed if a payment shall be processed as an alias payment
4.11.3 Return parameters
mdpAlias
txnMbRefNo
A18
A18
Alias (if requested by merchant and confirmed by the customer)
Migros Banks unique transaction reference
number
4.12 Swisscom Easypay
Easypay is a carrier billing service from Swisscom. The amount of the purchase will be charged to the consumer’s
monthly invoice from Swisscom or in case consumer has a mobile prepaid the amount will be debited on the prepaid credit balance.
Consumer will be redirected to an external webpage from Swisscom to confirm the payment. Easypay can be
used with practically all mobile end devices: mobile phones and smartphones. All consumers with a Swisscom SIM
card (subscription or prepaid) can use Easypay without any registration.
easyPaymentInfo
AN50
This value is displayed on the external Swisscom webpage, in the notifica-
03.03.2015 CRY
30 / 41
tion SMS, in the Swisscom customer center and on the consumer‘s bill.
If parameter is not submitted, the value from parameter refno will be taken.
If parameter is submitted without value, an error will occure on Swisscom
webpage.
(A-Za-z0-9_- )
easyTitle
AN25
easyDescription
AN100
Title of the content/product. Will be displayed on external webpage from
Swisscom.
(A-Za-z0-9_- )
Description of the content/product. Will be displayed on extern webpage
page from Swisscom.
(Any character except: ‘<’, ‘>’, ‘&’ )
4.12.2 Settlement
Deferred Settlement is technically possible.We recommend to authorize with immediate settlement (reqtype =
“CAA”) or with a separate settlement request immediately after successful authorization. An authorization can
not be settled after 00:59 of the next day. . To settle a smaller amount as initialliy authorized is not possible.
4.12.3 Credit
A previously authorised and settled transaction can be refunded. Refunding a transaction with multiple credits (i.e.
1 x settled transaction of CHF 100 / 2 x credit of CHF 50) is not supported for Easypay. However, it's possible to
refund a partial amount (i.e.CHF 50).
4.13 SwissBilling
SwissBilling is an external provider who handles invoicing to consumers and their payments.
4.13.1 Additional mandatory request parameters
uppCustomerLastName
uppCustomerStreet
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
uppCustomerPhone
uppCustomerEmail
AN40
AN40
AN40
AN40
A3
AN10
AN40
AN40
Date
First name of consumer
Last name of consumer
Street address
City
ISO country code (alpha)
Postal code
Phone number
E-mail address
Consumers date of birth; format: “dd.mm.yyyy” or “yyyy-mm-dd”
taxAmount
uppCustomerId
N
AN
Total VAT amount for this purchase
Identifiert for a consumer
03.03.2015 CRY
31 / 41
uppCustomerLanguage
A2
uppCustomerStreet2
uppShippingDetails
AN40
yes/no
uppShippingFirstName
uppShippingLastName
uppShippingStreet
uppShippingStreet2
uppShippingZipCode
uppShippingCity
uppShippingCountry
uppArticle_1_Id
uppArticle_1_Name
uppArticle_1_Description
uppArticle_1_PriceGross
uppArticle_1_Quantity
uppArticle_1_Tax
uppArticle_1_TaxAmount
uppArticle_1_Type
AN40
AN40
AN40
AN40
AN10
AN40
A3
AN
AN
AN
N
N
N
N
AN
Language of consumer; values: de, fr, it
If parameter is not submitted, de is default.
Street address
If “yes” all shipping parameters are mandatory except uppShippingStreet2
remains optional.
First name of recipient
Last nameof recipient
Street address of recipient
Street address of recipient
Postal code of recipient
City of recipient
ISO country code (alpha) of recipient
Identifier for the product
Name of the product
Other information related to the product
Product unit price including VAT
Quantity of product
VAT rate for this product
VAT amount for this product
Value “goods” specifies that products shall be shipped.
Information for multiple products can be submitted by adding additional parameters for article. The names of the
additional parameters for articles are defined as: uppArticle_2_Id, uppArticle_2_Name, etc.
Datatrans provides also a technical interface to check (“pre-screening”) if SwillBilling is eligible for a consumer.
Please refer to Datatrans Support ([email protected]) for XML-examples.
5 Alias
PCI Security Standards do no longer allow the storing and processing of credit card numbers and CVVs on the
merchants system. In some situations though, it is necessary to have the card information on the merchants system. You will therefore use the alias.
The system generates for every card number one alias. The CVVs must still not be stored and processed by the
merchants system.
The alias can be used in Standard and Hidden Mode and is requested with the parameter useAlias=yes.
6 Security Option
6.1
Data transfer encryption
The entire data transfer between the merchant's shop application and the Datatrans payment application is secured by the secure SSL protocol.
03.03.2015 CRY
32 / 41
6.2
Digital signature
The security elements are described on https://payment.datatrans.biz.
* With the activation of the security feature the request parameter "sign” becomes mandatory!
6.2.1
Security level 0
The data transmission is not secured.
6.2.2
Security level 1
The data transmission is secured by sending of the parameter sign which must contain a merchant-specific control
value (constant). This value is generated in the merchant administration tool https://payment.datatrans.biz. Note
that with every change of this value (which is possible at any time), the interface accepts the current value only!
6.2.3
Security level 2
The data transmission is secured by sending the parameter sign, which must contain a digital signature generated
by a standard HMAC-MD5 hash procedure and using a merchant-specific encryption key. The HMAC key is generated by the system and can be changed at any time in the merchant administration tool
https://payment.datatrans.biz.
*

With every change of the key, the interface accepts signature based on the current key only!

The key is delivered in hexadecimal format, and it should also be stored in this format.
But before its usage the key must be translated into byte format!

“sign2” is only returned in success case
03.03.2015 CRY
33 / 41
6.2.4
Creation of the digital signature (value of parameter sign) in the request

translate HMAC key from hex to byte format

create string to be signed by concatenating of parameters
- merchantId
- amount
- currency
- refno
in exactly this order and without separators

sign the string using HMAC-MD5 procedure based on merchant’s HMAC key

translate signature from byte to hex format and associate it as value with parameter sign
 Refer to Datatrans Support ([email protected]) for PHP-examples.
6.2.5
Sign2
The system signs the response similarly to the way the merchant does.
It passes the signature back to the merchant in parameter “sign2”, which is created in the same way as the parameter sign. There is one difference: the signed string contains the parameter “uppTransactionId” instead of
the reference number “refno”. We recommend checking the response signature.
For an even higher security level, it’s also possible to generate an alternative key for the “sign2” parameter.
With this feature “sign2” is created with a different key. To enable it the option “
Use another key for sign2 generation” has to be activated in UPP Admin in the menu “Security”.
As an option it is also possible to sign XML settlements. To enable this feature in UPP Admin, go to
“Security” and activate “Use signature also with settlements”.
* Once the signature validation for settlement is activated, the parameter “sign” will be validated with each XML
settlement request.
03.03.2015 CRY
34 / 41
7 Test Procedure
For test porposes you need a dedicated test account. The test account is only working in the test environment and
with test credit cards. For ordering a test account, please refer to
https://www.datatrans.ch/en/Payment-solutions/Overview-of-services/Test-account/.
Please find test samples here: www.datatrans.ch/showcase
7.1
Test credit cards
In order to test the error handling of the e-shop application the developer has to use our test card numbers which
create dedicated error messages depending on the authorized amount:
Card type
Card number
Expiration Date
CVV
Country Test rule
Support 3D
Visa
4242424242424242 12/2015 or 06/2015 123
CHE
With limit
No
Visa
4900000000000086 12/2015 or 06/2015 123
USA
Without limit Yes
Visa
4900000000000003 12/2015 or 06/2015 123
USA
Without limit Yes
MasterCard 5404000000000001 12/2015 or 06/2015 123
RUS
With limit
Yes
MasterCard 5200000000000007 12/2015 or 06/2015 123
MYS
Without limit No
MasterCard 5200000000000080 12/2015 or 06/2015 123
MYS
Without limit Yes
Amex
375811111111115
12/2015 or 06/2015 1234
With limit
No
Amex
375000000000007
12/2015 or 06/2015 1234
Without limit Yes
Amex
375811111111123
12/2015 or 06/2015 1234
Without limit No
Diners
36168002586009
12/2015 or 06/2015 123
With limit
Diners
36167719110012
12/2015 or 06/2015 123
Without limit JCB
3569990010030442 12/2015 or 06/2015 123
With limit
JCB
3569990010030400 12/2015 or 06/2015 123
Without limit AirPlus
122000200924770
12/2015 or 06/2015
CHE
With limit
AirPlus
192072420096379
12/2015 or 06/2015
CHE
Without limit -
7.1.1
Test rules
The following test rules apply for all cards with limit (see column “Test rule”):
Amount / amount range
<= 90.-> 90.— and <= 100.—
> 100.— and <= 110
> 110.--
Error message
Transaction authorized
Transaction declined (i.e. insufficient limit, bad expiry date)
Referral
Card blocked (lost or stolen)
* Note that all card numbers only work in our test environment! Productive cards cannot be processed on the test
account.
03.03.2015 CRY
35 / 41
7.2
PostFinance
PostFinance does no longer provide any test card numbers.
For tests you can use a productive PostFinance card number on your test account (Pilot application). The amount
will not be charged on your card.
7.3
CreditPass ELV (Elektronisches Lastschrift Verfahren)
Test option for German ELV available upon request.
"Old" parameters for ELV:
bankaccount
bankrouting
1234512345
12345678
5432154321
12345678
Restriction
if > 90.00  declined
no restriction
New parameters for SEPA ELV:
IBAN
BIC
DE85123456781234512345 AGIDDEFF
7.4
Restriction
if > 90.00 
declined
MyOne
Test option for MyOne available upon request.
Card number:
6004520200668702072
Expiration year:
2015
Expiration month:
12
CVV:
123
The same test rules apply for MyOne as for the test credit cards.
7.5
Dankort
Card number:
Expiration year:
Expiration month:
CVV:
7.6
5019994000124034
14
12
747
PayPal
There is no generic test account provided by PayPal. However, it’s possible to create a sandbox account on
http://developer.paypal.com.
Important steps:
- Create a new seller account and set the country to Germany
- Assign password and add to “notes”
- Add account balance of max. 9999.—
03.03.2015 CRY
36 / 41
Then set all API permissions according to the PDF document
https://www.datatrans.ch/userobjects/4421_3509_Paypal_Anleitung_EN_V3.4.pdf
They need to be assigned manually!
As “Third Party Permission Username” please use “info_api1.datatrans.ch”.
Please find below a more detailed documentation from PayPal. Note that this document is only available in German. https://www.paypalobjects.com/webstatic/de_DE/downloads/erstellen_eines_paypal_sandbox_accounts.pdf
Please send the PayPal user name (e-mail address) [email protected]. Datatrans needs this information in
order to add PayPal to the merchant’s dedicated test account.
* Note that – before going live - PayPal doesn’t work in a frame, you have to use the full window for a PayPal
transaction. Authorized PayPal transactions expire within 30 days. Please contact PayPal if you wish to re-authorize
a payment which is older than 30 days.
7.7
Deltavista
uppCustomerLastName
uppCustomerStreet
uppCustomerStreet2
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
uppCustomerType
7.8
Returns “green”
Returns “red”
MFGroup Checkout
uppCustomerLastName
uppCustomerStreet
uppCustomerCity
uppCustomerCountry
uppCustomerZipCode
uppCustomerGender
uppCustomerLanguage
uppCustomerEmail
7.9
Johnny
Good
Bad
Test Street
13
Test City
CHE
8000
P
Good
Customer
via Streccione 2
Lugano
CH
6900
male
it
1980-01-01
[email protected]
Bad
Customer
via paradiso 5
Locarno
CH
6600
male
it
1.2.1980
[email protected]
Unknown
Customer
via castello 4
Bellinzona
CH
6500
male
it
1.3.1980
[email protected]
Address Verification Service
Preconditions
 The merchant has the general Fraud Monitor enabled

The merchant has an acquirer which supports AVS, e.g. Worldpay or Chase Paymentech
03.03.2015 CRY
37 / 41

uppCustomerStreet and uppCustomerZipCode are submitted to UPP
Card number:
Expiration year:
Expiration month:
CVV:
4900000000000011 and 5200000000000015
2015
12
123
The following rules apply
amount<=500
500<amount<=1000
1000<amount<=1500
1500<amount<=2000
2000<amount<=2500
2500<amount<=3000
3000<amount<=3500
3500<amount<=4000
4000<amount<=4500
4500<amount<=5000
5000<amount<=5500
5500<amount<=6000
6000<amount<=6500
6500<amount<=7000
7000<amount<=7500
7500<amount<=8000
8000<amount<=8500
8500<amount<=9000
9000<amount<=9500
9500<amount<=10000
10000<amount<=11000
11000<amount
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
Authorized
-50
-59
-42
avsResult=A
avsResult=B
avsResult=C
avsResult=D
avsResult=E
avsResult=G
avsResult=I
avsResult=M
avsResult=N
avsResult=O
avsResult=P
avsResult=R
avsResult=S
avsResult=U
avsResult=W
avsResult=X
avsResult=Y
avsResult=Z
Declined
Declined / referral
Declined / card blocked
7.10 Maestro
Test option for Maestro available upon request.
Card number:
6759000000000018 and 6759000000000026 (with limit)
Expiration year:
2015
Expiration month:
12
CVV:
123
The same test rules apply for Maestro as for the test credit cards.
7.11 Jelmoli Bonus Card
Test option for Jelmoli Bonus Card available upon request.
03.03.2015 CRY
38 / 41
Card number:
60045110000000008 and 60045110000000016 (with limit)
Expiration year:
2015
Expiration month:
12
CVV:
123
The same test rules apply for Jelmoli Bonus Card as for the test credit cards.
7.12 SOFORT Überweisung
Test data for CHF
Bank Routing:
Account number:
PIN:
00000
any value
any value
Test data for EUR
Bank Routing:
Account number:
PIN:
88888888
any value
any value
* Frames are not supported, only full browser windows.
7.13 iDeal
iDeal does not provide any test data, and cannot be tested in the test environment.
* The refno of the merchant will be forwarded as purchase_id to iDeal. The field size of purchase_id is limited to
16AN, and has to be unique. Special characters are not supported!
7.14 SwissBilling
7.14.1 Test data
uppCustomerLastName
uppCustomerStreet
uppCustomerStreet2
uppCustomerCountry
uppCustomerCountry
uppCustomerZipCode
Johnny B.
Normal/Bad/Good
Limmatquai
55
CH
Zurich
8001
7.14.2 Test rules
uppCustomerLastName
Normal
Bad
Good
amount
<= 9000
> 9000
Transaction declined
03.03.2015 CRY
39 / 41
8 Error Codes
There is no final list of error codes. Please note that we do not recommend showing the exact error code or
error message to the buyer. Instead, we recommend distinguishing between technical errors and errors sent from
the issuer.
8.1
1001
1002
1003
1004
1006
1007
1008
1009
1010
1012
1403
8.2
UPP and XML error codes
required parameter missing
format of parameter is not valid
value not found
card number is not valid
card expired
access denied by sign control
access disabled by admin
merchant paym.method init error
action not allowed (not applicable transaction status)
duplicate settlement request
transaction declined without any further reason
Anti-fraud error codes
3001
3002
3003
3004
3005
3006
IP address declined by global fraud mgmt.
IP address declined by merchant fraud mgmt.
CC number declined by global fraud mgmt.
CC number declined by merchant fraud mgmt.
IP address declined by group fraud mgmt.
CC number declined by group fraud mgmt.
3011
3012
3013
3014
3015
3016
3021
3022
3023
3024
3025
3031
3041
3051
3061
3071
declined by merchant fraud mgmt. - TRX per IP
declined by group fraud mgmt. - TRX per IP
declined by merchant fraud mgmt. - TRX per CC
declined by group fraud mgmt. - TRX per CC
declined by merchant fraud mgmt. - AMOUNT per CC
declined by group fraud mgmt. - AMOUNT per CC
declined by country filter - Unknown BIN/Country
country declined by country filter
declined by country verification - uppCustomerCountry missing
declined by country verification - country does not match
country declined by group country filter
declined due to response code 02
declined due to postPage response error
declined due to country verification check
declined due to unique refno check
declined due to AVS check
03.03.2015 CRY
40 / 41
8.3
-885
-886
-887
-888
-889
-900
-999
8.4
2000
2001
2002
2011
2012
2013
2014
2021
2022
2031
2041
2042
2043
2044
2051
2097
2098
2099
Alias error codes
CC-alias update error
CC-alias insert error
CC-alias does not match with cardno
CC-alias not found
CC-alias error / input parameter(s) missing
CC-alias service is not supported
General error
XML specific errors
access denied by protocol control
no input document
error building document
root element invalid
body element missing
merchantId missing
element missing
missing value
invalid value
offline authorization not allowed
3D-Directory request not started
3D-Directory request not finished
3D-ACS process not started
3D-ACS process not finished
initialization UPP record not found
internal error
database error
xml processing error
03.03.2015 CRY
41 / 41

Technical Implementation Guide

Transcription

Similar documents

Private Label Card Management Software

HOW TO GET STARTED TO BE iPAY88 MERCHANT

Validated Parking at Autopark at Gallery Mall

PCI Compliance Instructions

PCI Compliance Instructions

CreditDebit Card Dispute Form

winter vacation work class six english u and c

Membership Registration Form 2015