Authorize

Authorize transactions which are alrady authenticated.

If you processed authentication only through either Secure Fields or 3D API, this API can be called to authorize the amount against your acquiring contract.

  • This service requires basic authentication. The password can be found in the Web Admin Tool under UPP Administration > Security > Server-to-Server services security.

  • Make sure to use our 3D Secure enabled test credit cards here.

1. Add acquirer to your account

You can choose from a list of Supported Acquirer and contact us at setup@pci-proxy.com

For this feature, you need an existing acquiring contract.

2. Authorize a stored card

post
Authorize

https://api.sandbox.datatrans.com/upp/jsp/XML_authorize.jsp
Authorize transactions which are alrady authenticated.
Request
Response
Request
Headers
Authorization
required
string
Basic MTAwMDAxMTAxMTpYMWVXNmkjJA== see Setup
Content-Type
required
string
API consumes application/xml; charset=UTF-8
Body Parameters
merchantId
required
string
Your unique account id at PCI Proxy (e.g. 1000011011)
refno
required
string
Your unique reference number (AN20)
amount
required
string
Transaction amount in smallest unit (e.g. 123.50 = 12350)
currency
required
string
Transaction currency - ISO character code (e.g. EUR)
aliasCC
required
string
Credit card token (AN20)
aliasCVV
optional
string
CVV token (base64)
expm
required
integer
Expiration month (MM)
expy
required
integer
Expiration year (YY)
eci
required
string
eci parameter of 3D object returned in /v1/transactions/{transactionId} call
xid
required
string
xid parameter of 3D object returned in /v1/transactions/{transactionId} call
cavv
required
string
cavv parameter of 3D object returned in /v1/transactions/{transactionId} call
enrolled
required
string
directoryResponse parameter of 3D object returned in /v1/transactions/{transactionId} call
status_3d
required
string
authenticationResponse parameter of 3D object returned in /v1/transactions/{transactionId} call
version_3d
required
string
threeDSVersion parameter of 3D object returned in /v1/transactions/{transactionId} call
sign
required
string
Your security sign - see Setup
reqtype
optional
string
NOA - Authorisation only (default) CAA - Authorisation and settlement
Response
200: OK
Transaction successfully authorized

In test mode, only test credit cards are allowed.

Examples

Reserve amount (authorize)
Charge amount (auth+settle)
Reserve amount (authorize)

To reserve an amount, simply send an authorization request with an amount (amount=1000):

Reserve
curl -X POST \
https://api.sandbox.datatrans.com/upp/jsp/XML_authorize.jsp \
-H 'Authorization: Basic MTEwMDAxNzc4OTpueG9ndnJPdGJScFhIUTFB' \
-d '<authorizationService version="4">
<body merchantId="1100017789">
<transaction refno="bsc-test">
<request>
<amount>1000</amount>
<currency>EUR</currency>
<aliasCC>520000RIVWAS0080</aliasCC>
<expm>12</expm>
<expy>21</expy>
<aliasCVV>PxZw66K5Ssq3RKZWL_JHLOTO</aliasCVV>
<parameters_3d>
<eci>02</eci>
<xid>MDAxOTA4MDkxNjMzMDkzNTUwMDQ=</xid>
<cavv>OTkxOTA4MDkxNjMzMTYwNTUwMzY=</cavv>
<enrolled>Y</enrolled>
<status_3d>Y</status_3d>
<version_3d>2.1.0</version_3d>
</parameters_3d>
<sign>190411090116949280</sign>
</request>
</transaction>
</body>
</authorizationService>'
Response (successful)
<authorizationService version='4'>
<body merchantId='1100017789' status='accepted'>
<transaction refno='bsc-test' trxStatus='response'>
<response>
<responseCode>01</responseCode>
<responseMessage>Authorized</responseMessage>
<uppTransactionId>190809164624026430</uppTransactionId>
<authorizationCode>624066431</authorizationCode>
<acqAuthorizationCode>164624</acqAuthorizationCode>
<maskedCC>520000xxxxxx0080</maskedCC>
</response>
</transaction>
</body>
</authorizationService>
Response (insufficient limit)
<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='2'>
<body merchantId='1000011011' status='accepted'>
<transaction refno='123abc' trxStatus='error'>
<request>
<amount>9100</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>NOA</reqtype>
</request>
<error>
<errorCode>1403</errorCode>
<errorMessage>declined</errorMessage>
<errorDetail>Declined</errorDetail>
<uppTransactionId>180413160820154027</uppTransactionId>
<acqErrorCode>50</acqErrorCode>
<returnCustomerCountry>CHE</returnCustomerCountry>
</error>
</transaction>
</body>
</authorizationService>
Response (card blocked)
<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='2'>
<body merchantId='1000011011' status='accepted'>
<transaction refno='123abc' trxStatus='error'>
<request>
<amount>12000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>NOA</reqtype>
</request>
<error>
<errorCode>1404</errorCode>
<errorMessage>card blocked</errorMessage>
<errorDetail>Declined - card blocked</errorDetail>
<uppTransactionId>180413161144544837</uppTransactionId>
<acqErrorCode>42</acqErrorCode>
<returnCustomerCountry>CHE</returnCustomerCountry>
</error>
</transaction>
</body>
</authorizationService>
Charge amount (auth+settle)

To charge a stored card, simply send an authorization request with reqtype=CAA:

Charge
curl https://api.sandbox.datatrans.com/upp/jsp/XML_authorize.jsp \
-H "Content-Type: application/xml" \
-d '<?xml version="1.0" encoding="UTF-8" ?>
<authorizationService version="2">
<body merchantId="1000011011">
<transaction refno="123abc">
<request>
<amount>1000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>CAA</reqtype>
</request>
</transaction>
</body>
</authorizationService>'
Response (successful)
<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='2'>
<body merchantId='1000011011' status='accepted'>
<transaction refno='123abc' trxStatus='response'>
<request>
<amount>1000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>CAA</reqtype>
</request>
<response>
<responseCode>01</responseCode>
<responseMessage>Authorized</responseMessage>
<uppTransactionId>180413160338192663</uppTransactionId>
<authorizationCode>338242664</authorizationCode>
<acqAuthorizationCode>160338</acqAuthorizationCode>
<maskedCC>424242xxxxxx4242</maskedCC>
<cardnumber>4242424242424242</cardnumber>
<returnCustomerCountry>CHE</returnCustomerCountry>
</response>
</transaction>
</body>
</authorizationService>%
Response (insufficient limit)
<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='2'>
<body merchantId='1000011011' status='accepted'>
<transaction refno='123abc' trxStatus='error'>
<request>
<amount>9100</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>CAA</reqtype>
</request>
<error>
<errorCode>1403</errorCode>
<errorMessage>declined</errorMessage>
<errorDetail>Declined</errorDetail>
<uppTransactionId>180413161627985895</uppTransactionId>
<acqErrorCode>50</acqErrorCode>
<returnCustomerCountry>CHE</returnCustomerCountry>
</error>
</transaction>
</body>
</authorizationService>
Response (card blocked)
<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='2'>
<body merchantId='1000011011' status='accepted'>
<transaction refno='123abc' trxStatus='error'>
<request>
<amount>12000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
<reqtype>CAA</reqtype>
</request>
<error>
<errorCode>1404</errorCode>
<errorMessage>card blocked</errorMessage>
<errorDetail>Declined - card blocked</errorDetail>
<uppTransactionId>180413162049417343</uppTransactionId>
<acqErrorCode>42</acqErrorCode>
<returnCustomerCountry>CHE</returnCustomerCountry>
</error>
</transaction>
</body>
</authorizationService>

Additional return parameter

If the authorization was successful, you will additionally receive the following parameter:

Parameter

Type

Description

responseCode

N2

01 or 02 for a successful transaction

responseMessage

Authorisation response message text

uppTransactionId

N18

Unique transaction identifier assigned by Datatrans

authorizationCode

N9

Outdated; internal reference ID assigned by Datatrans; please ignore and use uppTransactionId instead

acqAuthorizationCode

AN7

Authorisation code returned by the acquirer

maskedCC

Masked credit card number, which can be stored in your system.

If the authorization failed, you will additionally receive the following error parameter:

Parameter

Type

Description

errorCode

N7

Error code, please refer to the Technical Implementation Guide for the response code list

errorMessage

Error text

errrorDetail

Description of error detail

uppTransactionId

N18

Unique transaction identifier assigned by Datatrans

acqErrorCode

AN7

Error code returned by the acquirer