technical reference ajax payment...
Post on 03-Aug-2020
0 Views
Preview:
TRANSCRIPT
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
10.08.17 DME 2 / 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
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
10.08.17 DME 3 / 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
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 4 / 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
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?
10.08.17 DME 5 / 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
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
(support@datatrans.ch)
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
10.08.17 DME 6 / 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
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 );
};
10.08.17 DME 7 / 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
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"}
10.08.17 DME 8 / 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
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>
10.08.17 DME 9 / 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
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 10 / 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
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
10.08.17 DME 11 / 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
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):
<authorizationSplit version="1">
<body merchantId="1100002469" status="accepted">
<transaction refno="1234567" trxStatus="response">
<request>
<uppTransactionId>120130101550766769</uppTransactionId>
<amount>100</amount>
<currency>EUR</currency>
</request>
<response>
<responseCode>01</responseCode>
<responseMessage>Authorized</responseMessage>
<authorizationCode>806547411</authorizationCode>
<acqAuthorizationCode>171806</acqAuthorizationCode>
<maskedCC>490000xxxxxx0003</maskedCC>
10.08.17 DME 12 / 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
</response>
</transaction>
</body>
</authorizationSplit>
XML Response (error)
<authorizationSplit version="1">
<body merchantId="1100002469" status="error">
<transaction refno="123456" trxStatus="error">
<request>
<uppTransactionId>120130101550766769XX</uppTransactionId>
<amount>100</amount>
<currency>EUR</currency>
</request>
<error>
<errorCode>2022</errorCode>
<errorMessage>invalid value</errorMessage>
<errorDetail>uppTransactionId</errorDetail>
</error>
</transaction>
</body>
</authorizationSplit>
10.08.17 DME 13 / 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
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" ?>
<authorizationSplit version="1">
<body merchantId="1100002469">
<transaction refno="1234567">
<request>
<uppTransactionId>120130101550766769</uppTransactionId>
</request>
</transaction>
</body>
</authorizationSplit>
XML response (success):
<authorizationSplit version="1">
<body merchantId="1100002469" status="accepted">
<transaction refno="1234567" trxStatus="response">
<request>
<uppTransactionId>120130101550766769</uppTransactionId>
</request>
<response>
<responseCode>01</responseCode>
<responseMessage>Authorized</responseMessage>
<authorizationCode>806547411</authorizationCode>
<acqAuthorizationCode>171806</acqAuthorizationCode>
<maskedCC>490000xxxxxx0003</maskedCC>
</response>
</transaction>
</body>
</authorizationSplit>
10.08.17 DME 14 / 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
XML Response (error)
<authorizationSplit version="1">
<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>
</authorizationSplit>
top related