Technical Reference AJAX Payment...

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

Technical Reference

AJAX Payment API

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

Version 1.3


Revision control

Version Date Changed by Comments / nature of change

1.0 20.02.2012 Urs Kipfer Initial release

1.1 03.06.2013 Robert Matei 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

1.2 07.03.2014 Katja Schlegel Update old links

1.3 10.03.2017 Dominik Mengelt New Domains


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


Process overview

Split 3D Secure Process

Credit CardAll brands

External(Postfinance

PayPal)

Ch

ec

k-O

ut / A

uth

orisa

tio

nS

ettle

me

nt

yes

no

Check-Out Process

Step 2 (Optional)ACS Request

3D Secure Password check

Step1UPP.paymentRequest

Alias request3D Secure enrolled?

Step 3aAuthorization / Payment

Confirmation RequestXML_authorizeSplitEx.jsp

Settlement RequestXML_processor.jsp

(optional, please check technical implementation guide for details)

Standard Payment PageupStart.jsp

Step 3bAuthorization / Payment

Confirmation RequestXML_authorizeSplit.jsp

Payment Method?


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” pro-

cess. 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: https://<production-url>/upp/jsp/...

Backup URL: https://<production-backup-url>/upp/jsp/...

This works for the following URLs:

XML authorization …/XML_authorize.jsp / …XML_authorizeSplit.jsp

XML settlement …/XML_settlement.jsp

XML status request …/XML_status.jsp

XML 3D Secure status …/XML_3dDirectoryAcs.jsp

https://admin.sandbox.datatrans.com/showcase/doc/Technical_Implementation_Guide.pdf

mailto:[email protected]

https://www.datatrans.ch/showcase

https://admin.sandbox.datatrans.com/


Step 1: Ajax Payment API

Importing the library

Test (pay.sandbox.datatrans.com)

<script type="text/javascript"

src="https://pay.sandbox.datatrans.com/upp/ajax/static/jquery-

1.7.min.js"></script>

<script type="text/javascript"

src="https://pay.sandbox.datatrans.com/upp/ajax/api.js?merchantId=1100002469"></s

cript>

Production

<script type="text/javascript" src="https://<production-url>

/upp/ajax/static/jquery-1.7.min.js"></script>

<script type="text/javascript" src="https://<production-

url/upp/ajax/api.js?merchantId=XXXXXXXXXXX"></script>

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 “com-

plete”. Upon completion of AJAX call, the “complete” function will be called and passed the argument “re-

sponse” – a Javascript object containing the response to the call.

Example callback:

function completeCallback( response )

{

alert( "Ajax response status:" + response.status );

};


UPP.paymentRequest

Syntax:

UPP.paymentRequest( params, complete, createFrame );

params associative array containing request parameters

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

createFrame optional reference to callback function to be called when is3DEnrolled = true; the func-

tion 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): uppTransactionId, status, maskedCC, is3DEnrolled, aliasCC,

ACSURL (optional)

output (case error): 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-merchant-

return-page.html" },

completeCallback, frameCallback );

Example return from call:

{"uppTransactionId":"120130101550766769","status":"success",

"maskedCC":"490000xxxxxx0003","is3DEnrolled":false,"aliasCC":"70119122433810042"}


Example createFrame callback:

function frameCallback() // using jQuery

{

// create iframe and add it to document

var iframe = $("<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)

<!DOCTYPE html>

<html>

<head><title>resume</title></head>

<body>

<script type="text/javascript">

//notify the parent frame that the api call finished

parent.UPP.resume( window );

</script>

</body>

</html>

http://en.wikipedia.org/wiki/Same_origin_policy


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"}


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; sam-

ple: 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


Step 3a: Authorisation

This process is mandatory for all credit card transactions.

Service URL: https://<production-url>/upp/jsp/XML_authorizeSplitEx.jsp

Backup service URL: https://<production-backup-url>/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-www-

form-urlencoded”

XML request:

<?xml version="1.0" encoding="UTF-8" ?>

<authorizationSplit version="1">

<body merchantId="1100002469">

<transaction refno="1234567">

<request>

<uppTransactionId>120130101550766769</uppTransactionId>

<amount>100</amount>

<currency>EUR</currency>

</request>

</transaction>

</body>

</authorizationSplit>

A successful call will return <body>’s attribute status=”accepted” and <transaction>’s trxStatus=”response” as

well as a new <response> element containing the responseCode. A responseCode equal to “01” or “02” indi-

cates an authorized transaction.

XML response (success):


<body merchantId="1100002469" status="accepted">

<transaction refno="1234567" trxStatus="response">

<request>




</request>

<response>

<responseCode>01</responseCode>

<responseMessage>Authorized</responseMessage>

<authorizationCode>806547411</authorizationCode>

<acqAuthorizationCode>171806</acqAuthorizationCode>

<maskedCC>490000xxxxxx0003</maskedCC>


</response>

</transaction>

</body>


XML Response (error)


<body merchantId="1100002469" status="error">

<transaction refno="123456" trxStatus="error">

<request>

<uppTransactionId>120130101550766769XX</uppTransactionId>



</request>

<error>

<errorCode>2022</errorCode>

<errorMessage>invalid value</errorMessage>

<errorDetail>uppTransactionId</errorDetail>

</error>

</transaction>

</body>



Step 3b: Payment Confirmation

This process is mandatory for all PayPal and Postfinance transactions.

Service URL: https://<production-url>/upp/jsp/XML_authorizeSplit.jsp

Backup service URL: https://<production-backup-url>/upp/jsp/XML_authorizeSplit.jsp

XML request:

<?xml version="1.0" encoding="UTF-8" ?>


<body merchantId="1100002469">

<transaction refno="1234567">

<request>


</request>

</transaction>

</body>


XML response (success):


<body merchantId="1100002469" status="accepted">

<transaction refno="1234567" trxStatus="response">

<request>


</request>

<response>

<responseCode>01</responseCode>

<responseMessage>Authorized</responseMessage>

<authorizationCode>806547411</authorizationCode>

<acqAuthorizationCode>171806</acqAuthorizationCode>

<maskedCC>490000xxxxxx0003</maskedCC>

</response>

</transaction>

</body>



XML Response (error)


<body merchantId="1100002469" status="error">

<transaction refno="123456" trxStatus="error">

<request>

<uppTransactionId>120130101550766769XX</uppTransactionId>

</request>

<error>

<errorCode>2022</errorCode>

<errorMessage>invalid value</errorMessage>

<errorDetail>uppTransactionId</errorDetail>

</error>

</transaction>

</body>


Date post:	03-Aug-2020
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

Technical Reference AJAX Payment...

Documents