You can simply send an XML request with a token to check, reserve an amount, or charge a stored card. When you authorize a stored credit card, you can choose between different process options:

Check validity
Reserve an amount
Charge cardholder

When you check a stored card, we run your query against the Visa & Mastercard network to check if the card is still valid. The authorization does not appear on the customer statement but still gives you the ability to test the validity of a stored credit card.

When you reserve an amount on a stored card, the monthly allowance of the cardholder is reduced by the authorised amount, no matter whether the transaction will be settled later or not. The authorised amount is reserved for the merchant and should be settled within the period agreed with the acquirer. The issuer returns an authorisation code which serves as the reference of the authorisation. Once a transaction has been successfully authorised it can be settled.

Important: the cardholder will not be charged without settlement. Authorisation and settlement can also be processed in one single step (see Charge amount).

When you charge a stored card, the authorization and settlement will be processed in one single step. The settlement is often also referred to as “capture” or “clearing”. Once you sent a charge request, the authorized amount is reduced from the monthly allowance of the cardholder and will be automatically settled, which means that the cardholder will be actually charged.

Stored cards can be used multiple times for recurring transactions or One-Click payments.

1. Add acquirer to your account

You can choose from a list of Supported Acquirer and contact us at [email protected]

For this feature, you need an existing acquiring contract.

2. Authorize a stored card

post
AUTH method

https://api.sandbox.datatrans.com
/upp/jsp/XML_authorize.jsp
The AUTH method allows you to authorize a stored credit card.
Request
Response
Headers
Authentication
optional
string
Basic MTEwMDAwNzAwNjpLNnFYMXUkIQ== see Setup
Content-Type
optional
string
API consumes application/xml
Body Parameters
merchantId
required
string
Your unique account id at PCI Proxy (e.g. 1000011011)
amount
required
string
Transaction amount in smallest unit (e.g. 123.50 = 12350)
currency
required
string
Transaction currency – ISO character code (EUR, etc.)
refno
required
string
Your unique reference number (AN18)
aliasCC
required
string
Credit card token (AN20)
aliasCVV
optional
string
CVV token for CVV code (base64)
expm
required
string
Expiration month (MM)
expy
required
string
Expiration year (YY)
uppCustomerIpAddress
optional
string
Customer’s IP address (source IP used by cardholder)
sign
required
string
Your security sign see Setup
reqtype
optional
string
NOA – Authorisation only (default) CAA – Authorisation and settlement
200: OK
Successful authorization response
<?xml version=”1.0” encoding=”UTF-8”?>
<authorizationService version=”2”>
<body merchantId=”1000011011” status=”accepted”>
<transaction refno=”1234987” trxStatus=”response”>
<request>
<amount>1000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>15</expy>
<uppCustomerDetails>
<uppCustomerIpAddress>192.168.100.13</uppCustomerIpAddress>
</uppCustomerDetails>
<sign>30916165706580013</sign>
<reqtype>NOA</reqtype>
</request>
<response>
<responseCode>01</responseCode>
<responseMessage>Authorized</responseMessage>
<uppTransactionId>140813153050582536</uppTransactionId>
<authorizationCode>950672542</authorizationCode>
<acqAuthorizationCode>153050</acqAuthorizationCode>
<maskedCC>375811xxxxx1115</maskedCC>
</response>
</transaction>
</body>
</authorizationService>
400: Bad Request
Failed authorization response
<?xml version=”1.0” encoding=”UTF-8”?>
<authorizationService version=”2”>
<body merchantId=”1000011011” status=”accepted”>
<transaction refno=”1234987” trxStatus=”response”>
<request>
<amount>1000</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>15</expy>
<uppCustomerDetails>
<uppCustomerIpAddress>192.168.100.13</uppCustomerIpAddress>
</uppCustomerDetails>
<sign>30916165706580013</sign>
<reqtype>NOA</reqtype>
</request>
<error>
<errorCode>1403</errorCode>
<errorMessage>declined</errorMessage>
<errorDetail>Declined</errorDetail>
<uppTransactionId>140813155837703945</uppTransactionId>
<acqErrorCode>50</acqErrorCode>
</error>
</transaction>
</body>
</authorizationService>

In test mode, only test credit cards are allowed.

Examples

Check validity (zeroAuth)
Reserve amount (authorize)
Charge amount (auth+settle)

To check a stored card, simply send an authorization request with amount=0:

Check
Response (card valid)
Response (card not valid)
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>0</amount>
<currency>CHF</currency>
<aliasCC>424242SKMPRI4242</aliasCC>
<expm>12</expm>
<expy>18</expy>
<sign>30916165706580013</sign>
</request>
</transaction>
</body>
</authorizationService>'

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

Reserve
Response (successful)
Response (insufficient limit)
Response (card blocked)
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>
</request>
</transaction>
</body>
</authorizationService>'

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

Charge
Response (successful)
Response (insufficient limit)
Response (card blocked)
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>'

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