Technical Reference AJAX Payment API - Datatrans

Technical Reference AJAX Payment API Advanced Payment Service

Unified check-out process for 3D Secure and none 3D Secure transactions

Version 1.3

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

1 / 14

Revision control

Version 1.0 1.1

Date 20.02.2012 03.06.2013

Changed by Urs Kipfer Robert Matei

1.2 1.3

07.03.2014 10.03.2017

Katja Schlegel Dominik Mengelt

Comments / nature of change Initial release Step 1: Ajax Payment API - UPP.paymentRequest – aliasCC possible parameter Step 1: Ajax Payment API - Example returnUrl page – Note about same origin policy Step 3a: Authorisation – Notes about how to make the XML HTTP POST call Update old links New Domains

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

2 / 14

Content Process overview .................................................................................................................................................... 4 Important notes ..................................................................................................................................................... 5 Testing ................................................................................................................................................................... 5 Primary and alternate service URLs for XML services ............................................................................................... 5 Step 1: Ajax Payment API ....................................................................................................................................... 6 Importing the library ........................................................................................................................................... 6 UPP.paymentRequest ......................................................................................................................................... 7 UPP.aliasRequest (optional)................................................................................................................................. 9 Step 2: ACS Request (optional) ............................................................................................................................ 10 Step 3a: Authorisation ......................................................................................................................................... 11 XML request: .................................................................................................................................................... 11 XML response (success): ................................................................................................................................... 11 XML Response (error) ....................................................................................................................................... 12 Step 3b: Payment Confirmation ........................................................................................................................... 13 XML request: .................................................................................................................................................... 13 XML response (success): ................................................................................................................................... 13 XML Response (error) ....................................................................................................................................... 14

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

3 / 14

Process overview

Split 3D Secure Process

Check-Out

/

Authorisation

Check-Out Process

Credit Card

Payment Method?

All brands

Step1 UPP.paymentRequest Alias request 3D Secure enrolled?

yes

Step 2 (Optional) ACS Request 3D Secure Password check

Standard Payment Page upStart.jsp

no Step 3a Authorization / Payment Confirmation Request

Step 3b Authorization / Payment Confirmation Request

XML_authorizeSplitEx.jsp

Settlement

External

(Postfinance PayPal)

XML_authorizeSplit.jsp

Settlement Request XML_processor.jsp

(optional, please check technical implementation guide for details)

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

4 / 14

Important notes 

Supported payment methods: Mastercard, Visa, American Express, Diners, PayPal, Swiss PostFinance



This service is not supported by the Datatrans default merchant settings. Please contact the Datatrans support team to get “AJAX Payment API” activated.



Each Datatrans Merchant ID can either be used with the standard payment page or the “AJAX Payment API” process. Once “AJAX Payment API” is activated the standard payment page process is no longer supported on this merchant ID.



For error codes and error messages please refer to the “Technical Implementation Guide”

Testing 

Please use a dedicated Test Merchant ID for testing available from the Datatrans Support Team ([email protected])



Test card numbers are listed on https://www.datatrans.ch/showcase

Primary and alternate service URLs for XML services For all Datatrans XML payment services there is a backup URL available. This backup URL is meant to be used in case the primary URL is not responding for any reason. Please login to the Web Administration Tool on https://admin.sandbox.datatrans.com to find your production service URLs. Primary URL: Backup URL:

https:///upp/jsp/... https:///upp/jsp/...

This works for the following URLs: XML authorization XML settlement XML status request XML 3D Secure status

…/XML_authorize.jsp / …XML_authorizeSplit.jsp …/XML_settlement.jsp …/XML_status.jsp …/XML_3dDirectoryAcs.jsp

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

5 / 14

Step 1: Ajax Payment API Importing the library Test (pay.sandbox.datatrans.com) Production Due to the asynchronous nature of AJAX calls, the general method of returning from a function call is by using a callback function. All API methods of the AJAX Payment API require a Javascript function parameter called “complete”. Upon completion of AJAX call, the “complete” function will be called and passed the argument “response” – a Javascript object containing the response to the call. Example callback: function completeCallback( response ) { alert( "Ajax response status:" + response.status ); };

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

6 / 14

UPP.paymentRequest Syntax: UPP.paymentRequest( params, complete, createFrame ); params complete createFrame

associative array containing request parameters reference to callback function to be called upon completion of the request optional reference to callback function to be called when is3DEnrolled = true; the function should return a reference to the created frame; this frame will be used for starting the 3D Secure process; the minimum size is 390 x 400 pixel

params input:

merchantId, cardNumber (optional: if the payment is done using alias, aliasCC must be sent in-

stead), aliasCC (optional: if the payment is done using card number, cardNumber must be sent instead) , expy, expm, cvv, currency, amount, returnUrl (optional) output (case ok): output (case error):

uppTransactionId, status, maskedCC, is3DEnrolled, aliasCC, ACSURL (optional) uppTransactionId, status, errorCode, errorMessage, errorDetail

Example call: UPP.paymentRequest( { merchantId: "1100002469", cardNumber: "4900000000000003", expy: "15", expm: "12", cvv: "123", currency: "CHF", amount: 100, returnUrl: "https://pay.sandbox.datatrans.com/upp/ajax/sample-merchantreturn-page.html" }, completeCallback, frameCallback );

Example return from call: {"uppTransactionId":"120130101550766769","status":"success", "maskedCC":"490000xxxxxx0003","is3DEnrolled":false,"aliasCC":"70119122433810042"}

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

7 / 14

Example createFrame callback: function frameCallback() // using jQuery { // create iframe and add it to document var iframe = $("").attr( "id", "paymentIFrame" ) .width( 550 ).height( 400 ); // append to html document $("#frameHolder").append( iframe ); return iframe[0]; };

Example returnUrl page: Note: In most cases this example code has to be copied as is in a publicly accessible URL on merchant’s site from where the Ajax process is started, as required by the Same origin policy (http://en.wikipedia.org/wiki/Same_origin_policy) resume //notify the parent frame that the api call finished parent.UPP.resume( window );

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

8 / 14

UPP.aliasRequest (optional) Note: This request can be used instead of the UPP.paymentRequest if there is only an Alias to be created

UPP.aliasRequest (params, complete): params

associative array containing request parameters

complete

reference to callback function to be called upon completion of the request

params input:

merchantId, cardNumber

output (case ok):

status, maskedCC, aliasCC

output (case error):

status, errorCode, errorMessage, errorDetail (optional)

Example call: UPP.aliasRequest( { merchantId: "1100002469", cardNumber: "4242424242424242" }, completeCallback); Example response from successful call: {"status":"success","maskedCC":"424242xxxxxx4242","aliasCC":"70119122433810042"} Example response from error call: {"status":"error","errorCode":1004,"errorMessage":"Invalid card number"}

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

9 / 14

Step 2: ACS Request (optional) This process is only applicable in the following cases: - createFrame is not used in UPP.paymentRequest - credit card is 3D Secure enrolled Service URL: https://pay.sandbox.datatrans.com/upp/jsp/3D_submit_ACS.jsp

Parameters to be sent in the browser as HTTPS post request: Parameter

Value

Description / Sample

uppTransactionId

UPP Transaction ID

Return value from UPP.paymentRequest; sample: 100824134345589348

merchantId

Merchant ID

Merchant identification assigned by Datatrans; sample: 1000011011

amount

Transaction amount

Amount in cents

currency

Transaction currency

3 letter ISO currency code; sample: CHF

returnUrl

URL which has to be called after 3D Secure process

errorUrl (optional)

URL which has to be called after failed 3D Secure process

expy

Expiry year of card

Format: mm

expm

Expiry month of card

Format: yy

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

10 / 14

Step 3a: Authorisation This process is mandatory for all credit card transactions. Service URL: Backup service URL:

https:///upp/jsp/XML_authorizeSplitEx.jsp https:///upp/jsp/XML_authorizeSplitEx.jsp

This is a server to server HTTP POST call. The request XML can be sent either: a) as POST body, using HTTP header “Content-type: text/xml” b) as POST request parameter named “xmlRequest”, using HTTP header “Content-type: application/x-wwwform-urlencoded”

XML request: 120130101550766769 100 EUR

A successful call will return ’s attribute status=”accepted” and ’s trxStatus=”response” as well as a new element containing the responseCode. A responseCode equal to “01” or “02” indicates an authorized transaction.

XML response (success): 120130101550766769 100 EUR 01 Authorized 806547411 171806 490000xxxxxx0003 10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

11 / 14



XML Response (error) 120130101550766769XX 100 EUR

2022 invalid value uppTransactionId

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

12 / 14

Step 3b: Payment Confirmation This process is mandatory for all PayPal and Postfinance transactions. Service URL: Backup service URL:

https:///upp/jsp/XML_authorizeSplit.jsp https:///upp/jsp/XML_authorizeSplit.jsp

XML request: 120130101550766769

XML response (success): 120130101550766769 01 Authorized 806547411 171806 490000xxxxxx0003

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

13 / 14

XML Response (error) 120130101550766769XX

2022 invalid value uppTransactionId

10.08.17 DME Datatrans AG, Kreuzbühlstrasse 26, CH - 8008 Zürich, Tel. +41 44 256 81 91, Fax +41 44 256 81 98, www.datatrans.ch

14 / 14