Welcome to the Datatrans API reference. This document is meant to be used in combination with https://docs.datatrans.ch. All the parameters used in the curl and web samples are described here. Reach out to [email protected] if something is missing or unclear.

Key concepts

Transaction flow

The below steps describe a basic way of how a transaction flow with Datatrans can work:

  1. Redirect the customers browser to the Payment Page by submitting the mandatory parameters

  2. The customer enters their payment details and presses the Pay button.

  3. The transactionId and other important parameters will be sent to your Webhook (POST URL). Store them in your DB. In addition, all the parameters will also be sent to your success/cancel/error URLs.

  4. The browser will be redirected to the success/cancel/error page.

  5. Use the transactionId to perform different actions like Status cancel, credit and settle

Checkout the Payment processes chapter where all the possible actions which can be done after receiving a transactionId are explained in more detail.

Parameter format description

When describing response and request parameters throughout the reference, the following values are used for the parameter format.

Value Description Example

N

Numeric value

1337

DN

Decimal number

13.37

A

Alphabetic value

ABC

AN

Alphanumeric value

Abc-1337

MM

Month

03 (for March)

YY

Year

11 (for 2011)

N8

Numeric value of length 8

13371337

B

Boolean value

true

The uppTransactionId parameter

Once you do an authorization with an existing alias or by using the one of the integrations the uppTransactionId parameter is returned. The uppTransactionId parameter is needed for all subsequent actions after an authorization. Make sure to save it in your local database.

Parameter Format Description

uppTransactionId

N18

Unique transaction identifier

The reqtype parameter

The reqtype (request type) parameter is used to specify which type of action should be performed on Datatrans side. The different API endpoints support different reqtypes. For Authorizations (Server to Server or by using the Payment page) the following reqtypes are possible:

reqtype Description

NOA

Only authorization should be done. The amount will be blocked and a separate settlement needs to follow in order to actually charge the customer. Not all payment methods support splitting authorization and settlement. Refer to the documentation of the corresponding payment method if Deferred Settlement is possible.

CAA

Direct debit. Authorization with immediate settlement.

SCN

Only a pre-screening request should be done. Not all payment methods support pre-screening requests. Refer to the reqtype request parameter documentation for the particular payment method to see if pre-screening requests are supported.

When using Redirect Mode or Lightbox Mode and the reqtype parameter is not submitted for each transaction, the value configured in the Webadmin Tool will be used.

Reqtypes

In the image above, for both Visa and MasterCard reqtype CAA ('Direct Debit' radio button) would be used. Select 'Authorization / Settlement' if a deferred settlement is the preferred way of integration.

For authorizations with an existing Alias, deferred settlement, cancel and credit other reqtypes apply since they all share a common API endpoint

API call reqtype mandatory in request implicit reqtype if not specified

Authorization with an existing alias

-

NOA

Deferred Settlement

-

COA

Cancel

DOA

-

Credit (Refunds)

-

COA

Transaction status

During the lifecycle of a transaction the status of a transaction changes. Based on the current status of a transaction, different actions can be performed. The following table describes all states for a credit card transaction.

Status Description Possible actions

Verified only

This status can be reached when using the Split Mode integration and finalization of the authorization did not yet happen.

status

Authorized

The amount given in the authorization is blocked/reserved.

settle, cancel, status

Card checked

When using the Validate API, a "card check" against the Acquirer is being made. No amount is blocked. For credit cards, this status means that the card number, expiry and CVV were validated by the acquirer.

status

Settled

The transaction is ready for transmission to the Acquirer.

This transaction status is reached automatically if <reqtype>CAA<reqtype> is used.

cancel, credit, status

Settled credit

The same as status Settled but for Credits.

cancel, status

Settled+credited

An already settled transaction was credited and waiting for transmission to the Acquirer. Note: Also partial credits are possible.

cancel, status, credit

Settled/Transmitted

The transaction has been transmitted to the acquirer. Cancels are no longer possible.

status, credit

Canceled

The transaction was canceled by the customer (for example Payment Page cancel button).

status

Declined

The transaction was declined by the Acquirer or another error occurred.

status

The Status API can be used to check the status for a transaction.

Mandatory parameters

In general the following parameters must be provided as a minimum when using one of the Integrations or making an authorization with an existing alias.

Parameter Format Description

merchantId

mandatory

AN10

Unique Merchant Identifier (assigned by Datatrans during signup). Depending on your integration you might receive multiple merchantIds. For example: One for your mobile application and one for your web shop. Get a merchantId now and start using the APIs.

refno

mandatory

AN18

The merchants reference number. It should be unique for each transaction.

amount

mandatory

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. If the payment method supports it, amount=0 can be submitted when using either Redirect Mode or Lightbox Mode and the user should only be registered (saving the users payment method to a profile for example). Use <amount>0</amount> for validating an existing alias.

currency

mandatory

A3

3 letter ISO-4217 character code. For example CHF, USD

sign

mandatory

The sign parameter to be submitted with each request. Refer to Request signing for more details.

However, there are payment methods where additional mandatory parameters are needed. To see how to call the different APIs with parameters for a particular payment method, refer to the chapter of this payment method.

Authentication & TLS

Authentication to the APIs is performed via HTTP Basic Auth. Provide your merchantId as the basic auth username value. Login to Webadmin to enable server to server security under UPP Administrations > Security and generate your password.

Before enabling basic authentication for an existing merchantId please make sure your current integration already sends the correct Authorization header.

Create a base64 encoded value of merchantId and password (most HTTP clients are able to handle the base64 encoding automatically) and submit the Authorization header with each request. For example:

base64(merchantId:password) = MTAwMDAxMTAxMTpYMWVXNmkjJA==
Authorization: Basic MTAwMDAxMTAxMTpYMWVXNmkjJA==

All API requests must be done over HTTPS with TLS >= 1.2.

Request signing

In addition to basic authentication for the server to server APIs, it is possible to sign the request when using Redirect Mode or Lightbox Mode. Datatrans will check this signature and returns an error if the signatures do not match. The HMAC key needed to sign your requests can be found within the Webadmin tool

Sign

Details on the sign calculation can be found here: https://docs.datatrans.ch/docs/security-sign

Production URLs

Please login to Webadmin on https://admin.sandbox.datatrans.com to find the production environment URLs under “UPP Administration > UPP Data > Service URLs”

Checkout the API usage chapter to see which endpoint must be used for each integration.

Payment processes

This chapter describes the request and response parameters for the common payment processes. The respective API calls can have additional request/response parameters depending on the payment method.

Authorization with an existing alias

To charge an existing credit card Alias the authorize API can be used. In the following example the card is getting charged CHF 10.00. The reqtype parameter is not submitted. Which means the default value reqtype=NOA will be used.

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_authorize.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<authorizationService version="6">
  <body merchantId="1000011011">
    <transaction refno="749532">
      <request>
        <amount>1000</amount>
        <currency>CHF</currency>
        <aliasCC>70323122544331174</aliasCC>
        <expm>12</expm>
        <expy>21</expy>
      </request>
    </transaction>
  </body>
</authorizationService>
EOF
Table 1. Additional mandatory request parameter description
Parameter Format Description

aliasCC

mandatory

Alias format

The aliasCC received with a Payment or Registration. Refere to https://docs.datatrans.ch/docs/payment-process-alias for a detailed description about the alias format.

expm

mandatory

M or MM

Expiry month of the card. For example 1 or 01 for January.

expy

mandatory

YY

Expiry year of the card
For non credit card payment methods who support the creation of an alias (for example PostFinance Card, the <pmethod> attribute needs to be submitted. Additionally, expm and expy are not needed.

Successful response:

<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='4'>   (1)
  <body merchantId='1000011011' status='accepted'>  (2)
    <transaction refno='749532' trxStatus='response'> (3)
      <request>
        <amount>100</amount>
        <currency>CHF</currency>
        <aliasCC>70323122544331174</aliasCC>
        <expm>12</expm>
        <expy>21</expy>
        <sign>30916165706580013</sign>
        <reqtype>NOA</reqtype> (4)
      </request>
      <response>
        <responseCode>01</responseCode>
        <responseMessage>Authorized</responseMessage>
        <uppTransactionId>181003160948513946</uppTransactionId>
        <authorizationCode>948543947</authorizationCode>
        <acqAuthorizationCode>160948</acqAuthorizationCode>
        <maskedCC>375811xxxxx1115</maskedCC>
      </response>
    </transaction>
  </body>
</authorizationService>
1 The outer most element is <authorizationService>
2 The status attribute of the body element is either accepted or error. Error cases are for example a not well formated XML payload or a wrong merchantId. Note, the status attribute can have the value accepted but still result in an error. One example for this is if the card gets declined.
3 The trxStatus attribute of the transaction element defines if a response or error element is present.
4 If not present in the request, the reqtype parameter gets added to the <request> element.
Parameter Format Description

responseCode

N2

Authorization response code. 01 for a successful authorization, 02 for a successful authorization without liability shift.

Response code 02 is returned, if the issuer doesn’t claim liability. In case of a charge back the merchants will have the liability. These transactions are declined by default. If you would like to accept transactions with a response code 02, please modify the configuration in the Webadmin Tool

responseMessage

Human readable response message.

authorizationCode

N9

Deprecated, use uppTransactionId instead.

acqAuthorizationCode

AN

Authorization code returned by credit card issuing bank (length depending on payment method)

maskedCC

Masked credit card number. Returned only for Credit cards and if aliasCC was used for the request or uppReturnMaskedCC was used with either Redirect Mode or Lightbox Mode. The maskedCC can be safely stored and might be used for later displaying it to the user.

returnCustomerCountry

A3

If available, ISO 3166-1 alpha-3 country code of the cardholders issuer bank.

Error response (for example a declined card):

<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='4'>
  <body merchantId='1000011011' status='accepted'>
    <transaction refno='749532' trxStatus='error'>
      <request>
        <amount>100</amount>
        <currency>CHF</currency>
        <aliasCC>70323122544331174</aliasCC>
        <expm>12</expm>
        <expy>22</expy>
        <sign>30916165706580013</sign>
        <reqtype>NOA</reqtype>
      </request>
      <error>
        <errorCode>1403</errorCode>
        <errorMessage>declined</errorMessage>
        <errorDetail>Declined</errorDetail>
        <uppTransactionId>181003164051720477</uppTransactionId>
        <acqErrorCode>50</acqErrorCode>
      </error>
    </transaction>
  </body>
</authorizationService>
Parameter Format Description

errorCode

N4

The error code for the transaction.

errorMessage

Error response message text if available. For example: declined

errorDetail

Error detail if available. For example: Declined

acqErrorCode

N

Contains the error code sent by the acquirer

Validation error response with status='error':

<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='4'>
  <body merchantId='1000011011' status='error'>
    <transaction refno='749532' trxStatus='error'>
      <request>
        <currency>CHF</currency>
        <aliasCC>70323122544331174</aliasCC>
        <expm>12</expm>
        <expy>22</expy>
        <sign>30916165706580013</sign>
        <amount/>
      </request>
      <error>
        <errorCode>2021</errorCode>
        <errorMessage>missing value</errorMessage>
        <errorDetail>amount</errorDetail>
        <uppTransactionId>181003165103955108</uppTransactionId>
      </error>
    </transaction>
  </body>
</authorizationService>

Validate an existing Alias

An existing aliasCC can be validated at any time by submitting <amount>0</amount> to the Authorization with an existing alias API.

Only Credit cards and PostFinance support the validation of an existing alias.

Deferred Settlement

The Settlement request is often also referred to as “Capture” or “Clearing”. It can be used for the settlement of previously authorized transactions. The uppTransactionId is needed to settle an authorization.

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<paymentService version="1"> (1)
  <body merchantId="1000011011">
    <transaction refno="929787">
      <request>
        <amount>1000</amount>
        <currency>CHF</currency>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId> (2)
      </request>
    </transaction>
  </body>
</paymentService>
EOF
1 The outer most element is <paymentService>
2 The uppTransactionId received earlier by doing an authorization.
Please note

  1. The authorized amount must not be exceeded.

  2. If the payment method supports it, transactions can also be partially settled. Use a lower amount compared to the authorization.

  3. Deferred settlement is not supported by all payment methods.

Successful response:

<paymentService version="1">
    <body merchantId="1000011011" status="accepted">
        <transaction refno="929787" trxStatus="response">
            <request>
                <amount>1000</amount>
                <currency>CHF</currency>
                <uppTransactionId>TRANSACTION-ID</uppTransactionId>
                <reqtype>COA</reqtype> (1)
                <transtype>05</transtype>
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>settlement succeeded</responseMessage>
            </response>
        </transaction>
    </body>
</paymentService>
1 Implicit <reqtype> element for a deferred settlement call. Gets added to the <request> element if not specified in the request.

Successful response for a partial settlement:

<paymentService version="1">
    <body merchantId="1000011011" status="accepted">
        <transaction refno="929788" trxStatus="response">
            <request>
                <amount>1000</amount>
                <currency>CHF</currency>
                <uppTransactionId>TRANSACTION-ID</uppTransactionId>
                <reqtype>COA</reqtype>
                <transtype>05</transtype>
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>partialDebit succeeded</responseMessage>  (1)
            </response>
        </transaction>
    </body>
</paymentService>
1 Human readable response message that the partial settlement succeeded. Use the Status API to check how much of the total amount was already settled.

Cancel

The cancel API can be used to release the blocked amount from an authorization. The transaction must either be in status authorized or settled. The uppTransactionId is needed to cancel an authorization.

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<paymentService version="1"> (1)
  <body merchantId="1000011011">
    <transaction refno="178892">
      <request>
        <amount>100</amount>
        <currency>CHF</currency>
        <uppTransactionId>180507112808027192</uppTransactionId>
        <reqtype>DOA</reqtype> (2)
      </request>
    </transaction>
  </body>
</paymentService>
EOF
1 The outer most element is <paymentService>
2 <reqtype>DOA</reqtype> element is mandatory for a cancel API call.
Please note

  1. Authorized transactions cannot be cancelled partially. the Cancel Request reverses the transaction completely.

  2. Not all credit card issuers support Cancel Requests.

Successful response:

<paymentService version="1">
    <body merchantId="1000011011" status="accepted">
        <transaction refno="16675" trxStatus="response">
            <request>
                <amount>100</amount>
                <currency>CHF</currency>
                <uppTransactionId>180507112808027192</uppTransactionId>
                <reqtype>DOA</reqtype>
                <transtype>05</transtype>  (1)
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>cancellation succeeded</responseMessage>
            </response>
        </transaction>
    </body>
</paymentService>
1 Implicit <transtype> element. Gets added to the <request> element.

Credit (Refunds)

Use the credit API to credit a transaction which is in status settled or settled/transmitted.

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<paymentService version="1">   (1)
  <body merchantId="1000011011">
    <transaction refno="479509">
      <request>
        <amount>100</amount>
        <currency>CHF</currency>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId>
        <transtype>06</transtype>   (2)
      </request>
    </transaction>
  </body>
</paymentService>
EOF
1 The outer most element is <paymentService>
2 <transtype>06</transtype> element is mandatory for a credit API call.
Please note

  1. The previously settled amount must not be exceeded.

  2. Transactions can also be partially refunded.

  3. Refund and partial refund is not supported by all payment methods.

Successful response:

<paymentService version="1">
    <body merchantId="1100004624" status="accepted">
        <transaction refno="509183" trxStatus="response">
            <request>
                <amount>100</amount>
                <currency>CHF</currency>
                <uppTransactionId>TRANSACTION-ID</uppTransactionId>
                <transtype>06</transtype>
                <reqtype>COA</reqtype>  (1)
            </request>
            <response>
                <responseCode>01</responseCode>
                <responseMessage>credit succeeded</responseMessage>
                <uppTransactionId>180507104204173177</uppTransactionId>  (2)
                <authorizationCode>204203178</authorizationCode>  (3)
                <acqAuthorizationCode>104204</acqAuthorizationCode>  (4)
            </response>
        </transaction>
    </body>
</paymentService>
1 Implicit <reqtype> element for a deferred settlement call.
2 When doing a credit, a new uppTransactionId is created behind the scenes. This transaction can again be settled individually.
3 authorizationCode. Same as when doing an authorization with an existing alias
4 acqAuthorizationCode. Same as when doing an authorization with an existing alias

Checking the status of a transaction

Once a transactionId has been received the status can be checked with the Status API.

curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_status.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<statusService version="3"> (1)
  <body merchantId="1100004624">
    <transaction>
      <request>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId>
        <reqtype>STX</reqtype> (2)
      </request>
    </transaction>
  </body>
</statusService>
EOF
1 The outer most element is <statusService>
2 Mandatory <reqtype> for the Status API.

Successful response:

<?xml version='1.0' encoding='UTF-8'?>
<statusService version='3'>
  <body merchantId='1100004624' status='accepted'>
    <transaction trxStatus='response'>
      <request>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId>
        <reqtype>STX</reqtype>
      </request>
      <response itemNr='1'>  (1)
        <responseCode>2</responseCode>
        <responseMessage>Trx debit waiting for daily settlement process</responseMessage>
        <refno>594080</refno>
        <amount>1000</amount>
        <currency>CHF</currency>
        <authorizationCode>896916723</authorizationCode>
        <pmethod>VIS</pmethod>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId>
        <maskedCC>424242xxxxxx4242</maskedCC>
        <aliasCC>70119122433810042</aliasCC>
        <expm>12</expm>
        <expy>21</expy>
        <trxDate>20180507</trxDate>
        <trxTime>123956</trxTime>
        <trtype>05</trtype>
        <settledAmount>1000</settledAmount>
      </response>
    </transaction>
  </body>
</statusService>
1 The Status API can also be called 'by refno'. If there are multiple transactions with the same refno it is possible that the there is more than one <response> element. However, using the refno for Status API calls is not recommended.
Table 2. Additional Status API response parameters
Parameter Format Description

trxDate

YYYYMMDD

Date when authorization request was received.

trxTime

HHMMSS

Time when tha authorization request was received.

trtype

05 or 06

05 if it was a debit. 06 for a credit. This corresponds to the <transtype> parameter.

settledAmount

The amount already settled. Can be lower than the amount of the authorization partial settlements are used.

Marketplace

Marketplace specific parameters can be used with the Settlement and the Credit APIs.

Marketplace parameters during a settlement call.
curl -v -X POST https://api.sandbox.datatrans.com/upp/jsp/XML_processor.jsp \
-H 'Content-Type: application/xml' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d @- << EOF
<?xml version="1.0" encoding="UTF-8" ?>
<paymentService version="1">
  <body merchantId="1000011011">
    <transaction refno="929787">
      <request>
        <amount>1000</amount>
        <currency>CHF</currency>
        <uppTransactionId>TRANSACTION-ID</uppTransactionId>
        <closeTransaction>yes</closeTransaction>
        <marketplace>
          <subMerchantId>173294401</subMerchantId>
          <fee>
            <amount>10</amount>
            <currency>CHF</currency>
          </fee>
      </marketplace>
      </request>
    </transaction>
  </body>
</paymentService>
EOF
Table 3. Marketplace related request parameters
Parameter Format Description

closeTransaction

AN

yes - Required if the transaction should be closed after a settlement with a smaller amount than authorized amount. An authorized transaction will automatically be closed after a settlement reaches the authorized amount.

subMerchantId

AN15

Sub-merchant ID within the marketplace context. By default, this is equal to the VP-number of your sub-merchant.

amount

N

The amount which the marketplace receives from the sub-merchant for each transaction. It is automatically deducted from the settled or refunded amount. This amount needs to cover the acquiring costs to avoid issues during the acquirer’s payouts. The acquiring costs are automatically deducted from this amount.

currency

A3

Currency code for fee amount.

Integrations

General

Datatrans offers 3 ways to collect payment details from a customer on the web.

The Redirect Mode and Lightbox Mode share common optional parameters:

Table 4. Optional request paramters
Parameter Format Description

useAlias

yes to returns an Alias if the payment method supports it. The value of the alias will be in the aliasCC parameter.

language

A2

This parameter specifies the language (language code) in which the payment page should be presented to the cardholder. The following ISO-639-1 two letter language codes are supported:

  • de (German)

  • en (English)

  • fr (French)

  • it (Italian)

  • es (Spanish)

  • el (Greek)

  • no (Norwegian)

  • da (Danish)

  • pl (Polish)

  • pt (Portuguese)

uppStartTarget

If the payment is started within an iframe or when using the Lightbox Mode, use value _top. This ensures a proper browser flow for payment methods who need a redirect.

uppReturnTarget

If the payment is started within an iframe or when using the Lightbox Mode use _top if the callback URLs should be opened full screen when payment returns from a 3rd party (for example 3D).

mode

forceRedirect when displaying the redirect mode inside an iframe. It makes sure that no (X) button on the top right of the payment page is getting displayed. Additionally a click on the back button will redirect to the merchants cancel url.

uppStatus3D

Submit return as the parameter value in the request, and it will be replaced in the response with the real 3D status:

  • Y = 3D full authentication

  • D = merchant has a 3D contract, but card holder is not enrolled

  • A = 3D activation during shopping

  • U = 3D no liability shift

  • N = 3D authentication failed

  • C = 3D authentication uncomplete

  • N/A = TRX not 3D

uppReturnMaskedCC

yes – requests the return of the masked credit card number to the merchant in field maskedCC. Example value: 424242xxxxxx4242

This parameter only works for Credit cards

Successful authorization response

After a successful transaction with the Redirect Mode or Lightbox Mode the following response parameters will be sent to the callback URLs and the Webhook (POST URL).

Parameter Format Description

uppTransactionId

N18

Unique transaction identifier

merchantId

AN10

Unique Merchant Identifier (assigned by Datatrans during signup). Depending on your integration you might receive multiple merchantIds. For example: One for your mobile application and one for your web shop. Get a merchantId now and start playing with the APIs.

refno

AN18

The merchants reference number. It should be unique for each transaction.

amount

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. Can be omitted for a registration (if the payment method supports registrations)

currency

A3

3 letter ISO-4217 character code. For example CHF, USD

sign

The sign parameter to be submitted with each request. Refer to Request signing for more details.

uppMsgType

web for the success/cancel/error URLs, post for the Webhook (POST URL)

reqtype

A3

The reqtype of the transaction.

status

Constant value: success

aliasCC

Alias format

If the payment method supports it and useAlias=yes was used in the initial request.

responseCode

N2

Authorization response code. 01 for a successful authorization, 02 for a successful authorization without liability shift.

Response code 02 is returned, if the issuer doesn’t claim liability. In case of a charge back the merchants will have the liability. These transactions are declined by default. If you would like to accept transactions with a response code 02, please modify the configuration in the Webadmin Tool

responseMessage

Human readable response message.

authorizationCode

N9

Deprecated, use uppTransactionId instead.

acqAuthorizationCode

AN

Authorization code returned by credit card issuing bank (length depending on payment method)

maskedCC

Masked credit card number. Returned only for Credit cards and if aliasCC was used for the request or uppReturnMaskedCC was used with either Redirect Mode or Lightbox Mode. The maskedCC can be safely stored and might be used for later displaying it to the user.

returnCustomerCountry

A3

If available, ISO 3166-1 alpha-3 country code of the cardholders issuer bank.

sign2

Returned only by successful transaction if parameter sign was submitted within the request. Check chapter Request signing.

Failed / unsuccessful authorization response

This response is sent to errorUrl and/or Webhook (POST URL) provided by the merchant.

Parameter Format Description

uppTransactionId

N18

Unique transaction identifier

merchantId

AN10

Unique Merchant Identifier (assigned by Datatrans during signup). Depending on your integration you might receive multiple merchantIds. For example: One for your mobile application and one for your web shop. Get a merchantId now and start playing with the APIs.

refno

AN18

The merchants reference number. It should be unique for each transaction.

amount

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. Can be omitted for a registration (if the payment method supports registrations)

currency

A3

3 letter ISO-4217 character code. For example CHF, USD

sign

The sign parameter to be submitted with each request. Refer to Request signing for more details.

uppMsgType

web for the success/cancel/error URLs, post for the Webhook (POST URL)

reqtype

A3

The reqtype of the transaction.

status

Constant value: error

aliasCC

Alias format

If the payment method supports it and useAlias=yes was used in the initial request.

errorCode

N4

The error code for the transaction.

errorMessage

Error response message text if available. For example: declined

errorDetail

Error detail if available. For example: Declined

Canceled transaction response

If the cardholder decides to cancel the payment process and to return to the shop without payment, the response is sent back to the cancelUrl.

Parameter Format Description

uppTransactionId

N18

Unique transaction identifier

merchantId

AN10

Unique Merchant Identifier (assigned by Datatrans during signup). Depending on your integration you might receive multiple merchantIds. For example: One for your mobile application and one for your web shop. Get a merchantId now and start playing with the APIs.

refno

AN18

The merchants reference number. It should be unique for each transaction.

amount

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00. Can be omitted for a registration (if the payment method supports registrations)

currency

A3

3 letter ISO-4217 character code. For example CHF, USD

sign

The sign parameter to be submitted with each request. Refer to Request signing for more details.

uppMsgType

web for the success/cancel/error URLs, post for the Webhook (POST URL)

status

Constant value: cancel

Redirect Mode

The Redirect Mode is the easiest way to create a payment. It is best practice to not use an <iframe> when using the Redirect Mode. This is because not every payment method or credit card 3D Page support the use of an <iframe>.

The Lightbox Mode should only be used if the payment method selection page happens on the Datatrans Payment Page or if the customer needs to enter payment method details. For example, if you start a transaction by specifying paymentmehod=PFC there is no need to use the Lightbox Mode integration. As in this case, the customers browser would be redirected to the PostFinance website immediately without the Datatrans Payment Page in Lightbox Mode being displayed.

Secure Fields

The Secure Fields allow you to securely collect card data by injecting iframes to your DOM. A separate iframe for both, card number and CVV code is used. Thereby, sensitive data never touches your server and allows you to capture all other related card data such as cardholder name, expiry date, etc. directly by yourself. The integration effort is higher compared to Redirect Mode or Lightbox Mode. However, Secure Fields are giving you the most flexibility when implementing your checkout flow.

Webhook (POST URL)

If configured in the Webadmin Tool, the Webhook (POST URL) will be called for each web transaction. We highly recommend to implement a Webhook (POST URL) listener in order to have more control about a transaction in scenarios where the user closes his browser for example.

The Webhook (POST URL) will be invoked whenever Datatrans tries to do an authorization with the payment method provider. As an example: The Webhook (POST URL) will be called after a successful or erroneous authorization with a credit card acquirer.

<?xml version="1.0" encoding="UTF-8"?>
<uppTransactionService version="1"> (1)
  <body merchantId="1000011011" testOnly="yes">
    <transaction refno="840973" status="success">
      <uppTransactionId>180710155401925243</uppTransactionId>
      <amount>1000</amount>
      <currency>CHF</currency>
      <pmethod>VIS</pmethod>
      <reqtype>CAA</reqtype>
      <language>en</language>
      <success> (2)
        <authorizationCode>417485393</authorizationCode>
        <acqAuthorizationCode>155417</acqAuthorizationCode>
        <responseMessage>Authorized</responseMessage>
        <responseCode>01</responseCode>
      </success>
      <userParameters> (3)
        <parameter name="sign">30916165706580013</parameter>
        <parameter name="responseCode">01</parameter>
        <parameter name="expy">21</parameter>
        <parameter name="expm">12</parameter>
      </userParameters>
    </transaction>
  </body>
</uppTransactionService>
1 The outer most element is <uppTransactionService>.
2 A success or error element.
3 A userParameters element for parmeters which where sent when the transaction was started.

success/cancel/error URLs

The result of a web payment transaction using Redirect Mode or Lightbox Mode is either success, cancel or error. Datatrans makes a HTTP POST request with Content-Type: application/x-www-form-urlencoded to the specified URLs. The URLs can either be configured in the Webadmin Tool or can be sent for each transaction:

Parameter Description

successUrl

This parameter represents the URL of the merchant’s web shop, where the consumer should be redirected to after a successful transaction

cancelUrl

This parameter represents the URL of the merchant’s web shop, application, where the consumer should be redirected to after cancelling the transaction.

errorUrl

This parameter represents the URL of the merchant’s web shop, application, where the consumer should be redirected to after a failed transaction

Common parameters

The Redirect Mode, Lightbox Mode and Authorization with an existing alias APIs share common parameters. Note, not all payment methods have support for them. For example PostFinance does not support shipping details. Refer to the payment method, if a specific object is supported. Common objects can be sent together. So if the payment method supports it, the uppCustomer* parameters can be used together with the uppArticle* parameters for example.

When doing a server to server authorization, those common parameters can be submitted in the following way inside the <uppCustomerDetails> element.

<?xml version='1.0' encoding='UTF-8'?>
<authorizationService version='4'>
  <body merchantId='1000011011'>
    <transaction refno='749532'>
      <request>
        <!-- other mandatory parameters here -->
        <uppCustomerDetails>
          <uppCustomer*>
          <uppArticle*>
          <uppFee*>
          <uppShipping*>
        </uppCustomerDetails>
      </request>
    </transaction>
  </body>
</authorizationService>

Where for example uppCustomer* could be uppCustomerFirstName. Check the following sections to see all available parameters for uppCustomer*, uppArticle*, uppFee* and uppShipping*.

If one of the Integrations is used, those parameters can be sent as form post or query string parameters for the Redirect Mode or as data attributes when using the Lightbox Mode. For Secure Fields the parameters can be submitted to the final split call.

Customer details

Whenever the payment method supports customer details, the uppCustomer* parameters can be used. If a particular parameter is required varies from payment method to payment method. For example the parameter uppCustomerBirthDate is not mandatory for each payment method supporting the uppCustomer* parameters.

Parameter Format Description

uppCustomerDetails

AN100

For web transactions using one of the Integrations:

yes, if the sent customer details parameters should be stored in the Webadmin Tool, or return (only available for PayPal) – if address details should be returned from PayPal to the merchant.

For server to server authorizations the Common parameters are placed inside the <uppCustomerDetails> element.

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerId

AN

Identifier for a customer

Mandatory for: INT

uppCustomerTitle

AN30

Title of the customer

uppCustomerName

AN100

Name of the customer

uppCustomerFirstName

AN100

First name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerLastName

AN100

Last name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerType

A1

Either P (=person/B2C) or C (=company/B2B)

Mandatory for: ACC INT DVI

uppCustomerStreet

AN100

Steet name of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerStreet2

AN100

Second street name of the customer

uppCustomerCity

AN100

City of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerCountry

A3

ISO 3166-1 alpha-3 country code of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI

uppCustomerZipCode

AN10

Postal code of the customer

Mandatory for: ACC BPY BPL BPD INT SWB DVI MFX MFA

uppCustomerState

AN100

State of the customer

uppCustomerPhone

AN40

Phone number of the customer

Mandatory for: ACC BPY BPL BPD SWB

uppCustomerFax

AN40

Fax number of the customer

uppCustomerEmail

AN100

E-Mail address of the customer

BPY BPL BPD SWB MFX MFA INT

uppCustomerGender

A6

Gender of the customer. Possible values: female, male

Mandatory for: ACC BPY BPL BPD MFX MFA INT

uppCustomerBirthDate

Date

Customer date of birth. Format: dd.mm.yyyy or yyyy-mm-dd

Mandatory for: ACC BPY BPL BPD SWB MFX MFA INT

uppCustomerLanguage

A2

Language of customer. Possible values: en, de, fr, it

Mandatory for: ACC INT

uppCustomerOccurence

AN100

Possible values: EXISTING, REGISTERING, GUEST

Mandatory for:

BPY BPL BPD

uppCustomerSubscription

AN

Type of customer subscription. For example: test

Mandatory for: SWB

Article details

Whenever the payment method supports article parameters, the uppArticles* parameters can be used. If multiple articles need to be submitted, the uppArticle_N_* format can be used. Where N=1 would be the first article and N=2 the second one.

Parameter Format Description

uppArticle_1_Id

AN

Identifier for the product

Mandatory for: BPY BPL BPD

uppArticle_1_Name

AN

Name of the product

Mandatory for: BPY BPL BPD KLN

uppArticle_1_ProductCategory

AN

Category of the product, free text values accepted.

uppArticle_1_Description

AN

Other information related to the product

uppArticle_1_Type

AN

Type of the product. Possible values vary per payment method. Refer to the corresponding payment method chapter.

uppArticle_1_Quantity

N

Quantity of similar products on the current invoice line item

Mandatory for: BPY BPL BPD KLN

uppArticle_1_Price

N

Line item price including VAT. If the current invoice line has multiple similar products then uppArticle_1_Price = uppArticle_1_Quantity * uppArticle_1_SingleArticlePrice

Mandatory for: BPY BPL BPD KLN

uppArticle_1_PriceGross

N

Product unit gross price including VAT

Mandatory for: BPY BPL BPD

uppArticle_1_Tax

N / DN

VAT rate for this product

Mandatory for: KLN

uppArticle_1_PriceWithoutVAT

N

Line item price without VAT

uppArticle_1_TaxAmount

N

VAT amount for this line item

Mandatory for: KLN

uppArticle_1_SingleArticlePrice

N

Product unit price including VAT

uppArticle_1_SingleArticlePriceWithoutVAT

N

Product unit price without VAT

Shipping details

Whenever the payment method supports shipping parameters, the uppShipping* parameters can be used. If a particular field is required varies from payment method to payment method.

Parameter Format Description

uppShippingDetails

If yes all shipping parameters are mandatory except uppShippingStreet2 remains optional.

uppShippingTitle

AN

Title of the recipient

uppShippingFirstName

AN40

First name of recipient

Mandatory for: BPY BPL BPD

uppShippingLastName

AN40

Last name of recipient

Mandatory for: BPY BPL BPD

uppShippingStreet

AN40

Street address of recipient

Mandatory for: BPY BPL BPD

uppShippingStreet2

AN40

Possible values vary per payment method. Refer to the corresponding payment method chapter.

uppShippingZipCode

AN10

Postal code of recipient

Mandatory for: BPY BPL BPD

uppShippingCity

AN40

City of recipient

Mandatory for: BPY BPL BPD

uppShippingCountry

A3

ISO 3166-1 alpha-3 country code of the recipient

Mandatory for: BPY BPL BPD

uppShippingPhone

AN15

Phone number of recipient

uppShippingCellPhone

AN50

Cell phone number of recipient

uppShippingPrice

N7

Value of all items in the basket, in smallest available unit.

Mandatory for: BPY BPL BPD

uppShippingPriceGross

N7

Gross value of all items in the basket, in smallest available unit.

Mandatory for: BPY BPL BPD

uppShippingCarrier

AN50

For example: DHL, Express

Mandatory for: BPY BPL BPD

uppShippingEmail

AN50

The email address of the recipient

Billing details

Whenever the payment method supports billing parameters, the uppBilling* parameters can be used. If a particular field is required varies from payment method to payment method.

Parameter Format Description

uppBillingDetails

If yes all billing parameters are mandatory except uppBillingStreet2 remains optional.

uppBillingTitle

AN

Title of the recipient of the bill

uppBillingFirstName

AN40

First name of the recipient of the bill

uppBillingLastName

AN40

Last name of the recipient of the bill

uppBillingStreet

AN40

Street address of the recipient of the bill

uppBillingStreet2

AN40

Possible values vary per payment method. Refer to the corresponding payment method chapter.

uppBillingPhoneNumber

AN15

Phone number of the recipient of the bill

uppBillingEmail

AN50

The email address of the recipient of the bill

uppBillingZipCode

AN10

Postal code of the recipient of the bill

uppBillingCity

AN40

City of the recipient of the bill

uppBillingCountry

A3

ISO 3166-1 alpha-3 country code of the the recipient of the bill

Payment methods

General

The following sub chapters only highlight the differences or payment method specific parameters. Checkout the Payment processes and Common parameters chapters for basic API invocations and parameter documentation.

Fully working samples for all payment methods can be found on https://docs.datatrans.ch/docs/credit-cards for credit cards and https://docs.datatrans.ch/docs/other-payment-methods for all other payment methods.

Credit cards

The following payment methods are considered credit cards.

  • Visa VIS

  • MasterCard ECA

  • American Express AMX

  • Diners DIN

  • Discover DIS

  • JCB JCB

  • Dankort DNK

  • Manor MyOne MYO

  • China UnionPay CUP

  • Jelmoli Bonus Card JEL

All the above mentioned credit card payment methods do have expm and expy and support the creation of an alias. This allows to do an authorization with an existing alias for example.

3D secure

An existing Alias in combination with expm and expy can be used to initialize a 3D secure transaction. If 3D secure is enabled and the card is enrolled, the browser can be redirected by using one of the integration methods.

Accarda KaR

Payment method code: ACC

Checkout which Customer details parameters are mandatory for Accarda.
Table 5. Additional Accarda specific request parameters
Element Format Description

reqtype

A3

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

uppCustomerName

mandatory for B2B

AN100

Name of the company

uppCustomerCompanyLegalForm

mandatory for B2B

AN40

Legal form of the company

sub_pmethod

mandatory

AN

Either INVOICE or INSTALLMENT

authorizationId

optional

AN

The authorizationId received from an initial credit check request. Use <reqtype>SCN</reqtype> to do only a credit check and not an actual payment.

accardaAttachments

optional

AN20

base64 encoded values of attachments in the following format:

<attachment mimeType="text/xml" name="invoicetext.xml">
  <value>base64 encoded content 1</value>
</attachment>

accardaOtherPaymentMeansAmount

optional

N

Amount in the basket payed by coupon or other payment instruments.

accardaPreferredRateModel

optional

AN

Possible values: 3x3, 4x12, 12x12

accardaInvoiceChannel

optional

AN

Possible values: EMAIL, PRINT, INSURANCE, MERCHANT

accardaEnableStreetSplit

optional

A

true or false whether the uppCustomerStreet will be splitted into streetName and streetNumber

accardaCustomerOrderNumber

optional

AN

Accarda reference number, mainly useful for B2B orders where the company doing the order might have their own ID to identify the invoice later on within their own systems.

Accarda supports uppFee* parameters. They will appear as separate line items on the customers bill. Just like with Article details multiple fee items can be submitted by using the uppFee_N_* format.

Table 6. Additional optional request parameters for Accarda
Element Format Description

uppFee_1_Id

AN

Identifier of the fee

uppFee_1_Name

AN

Name of the fee

uppFee_1_ProductCategory

AN

Category of the fee, free text values are accepted

uppFee_1_Type

AN

Type of the fee. Accepted values are GOODS, REBATE, FEE or OTHERPM but recommended value is FEE

uppFee_1_Quantity

N

Quantity of similar fees in the current invoice line item

uppFee_1_Price

N

Fee total price including VAT

uppFee_1_Tax

N / DN

VAT rate for this fee

uppFee_1_PriceWithoutVAT

N

Fee total price without VAT

uppFee_1_TaxAmount

N

VAT amount for this fee

uppFee_1_SingleArticlePrice

N

Fee unit price including VAT

uppFee_1_SingleArticlePriceWithoutVAT

N

Fee unit price without VAT
Table 7. Additional response parameters for Accarda
Element Format Description

accardaBasket

AN

XML representation of the Accarda eshop basket containing the total amount and the products. This parameter is base64 encoded and can be used for future partial credit requests.

installmentPlan

AN

XML representation of the instalment plan returned by the successfulcredit decision check. This parameter is base64 encoded.

info

AN

XML representation of the info element returned by the successful transaction. This parameter is base64 encoded. For example:

<info>
  <status>AUTHORIZED</status>
  <validUntil>2018-11-10</validUntil>
  <isSuitableForDelivery>false</isSuitableForDelivery>
</info>

When doing a pre-screening request with reqtype=SCN:

<info>
  <status>PREAUTHORIZED</status>
  <validUntil>2018-10-11</validUntil>
  <isSuitableForDelivery>false</isSuitableForDelivery>
</info>

When doing a credit request:

<info>
  <status>CREDITED</status>
  <validUntil>2018-01-07</validUntil>
  <isSuitableForDelivery>true</isSuitableForDelivery>
</info>

decisionRiskTaker

AN

Possible values: PROVIDER, MERCHANT

decisionInstallment

AN

Possible values: OK, NOK

decisionInvoice

AN

Possible values: OK, NOK

authorizationId

N

The authorization id returned by the successful credit decision check

purchaseInInstallementGranted

B

If installments are available. Check the sub_pmethod parameter.

purchaseOnInvoiceGranted

B

If invoice is available. Check the sub_pmethod parameter.

If INSTALLMENT is used for the sub_pmethod parameters, the available rate plans are returned. For example:

<installmentPlan>
  <totalRateAmount>349.0</totalRateAmount>
  <interestRate>0.0</interestRate>
  <billingDate>2018-10-11</billingDate>
  <rateModel>4X12</rateModel>
  <rates>
    <rateAmount>87.25</rateAmount>
    <rateDate>2018-11-10</rateDate>
    <interestAmount>17.9</interestAmount>
  </rates>
  <rates>
    <rateAmount>87.25</rateAmount>
    <rateDate>2019-02-08</rateDate>
    <interestAmount>0.0</interestAmount>
  </rates>
  <rates>
    <rateAmount>87.25</rateAmount>
    <rateDate>2019-06-08</rateDate>
    <interestAmount>0.0</interestAmount>
  </rates>
  <rates>
    <rateAmount>87.25</rateAmount>
    <rateDate>2019-10-06</rateDate>
    <interestAmount>0.0</interestAmount>
  </rates>
</installmentPlan>

Apple Pay

Apple Pay

Table 8. Additional mandatory Apple Pay request parameters for server to server authorizations.
Element Format Description

applePayToken

AN

The token received from Apple when integrating the Buy with Apple Pay button. Needs to be wrapped in a CDATA element:

<![CDATA[$token]]>

Billpay

Payment method codes: BPY, BPL and BPD

Checkout which Common parameters are mandatory for the different Billpay payment methods.
Table 9. Additional optional request parameters for Billpay
Element Format Description

uppRebate

N

The rebate amount

uppRebateGross

N

The rebate gross amount.
Table 10. Additional Billpay response parameters.
Element Format Description

accountHolder

N

Name of the account holder.

bankCode

N

Bank code of the account holders bank.

invoiceReference

AN

Invoice reference number

bankName

AN

The bank name.

accountNumber

AN

Account holders IBAN. For example DE2501200000TEST000000000003.
accountHolder, bankCode, invoiceReference, bankName and accountNumber are also getting returned with the settlement request.

Boncard

Payment method code: BON

Boncard does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/boncard.

Byjuno

Payment method code: INT

Checkout which Customer details parameters are mandatory for Byjuno.
Table 11. Additional Byjuno specific request parameters
Element Format Description

reqtype

A3

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

uppCustomerName

mandatory for B2B

AN60

Name of the company

uppCustomerCompanyRegisterNumber

mandatory for B2B

AN100

Register number of the company

sub_pmethod

mandatory

AN

One of

  • INVOICE

  • INSTALLMENT

  • BYJUNO_INVOICE

intrumDeviceFingerprintId

AN35

Identification of the customer in the shop.

intrumDeliveryMethod

AN35

One of

  • POST - Delivery by Swiss Post

  • SHOP - Point of Sale

  • HLD - Home Delivery Service

intrumCustomerEmailConfirmed

B

Can be true or false to indicate that customer has confirmed the email address to the merchant. It has a default value of false if missing.

intrumSiteID

AN

Can be used in case when client operates different legally separated stores / points of sale.

intrumRepaymentType

N2

Number value from 1 to 20 indicate repayment schedule, is used in combination with Payment Methods and defined per client configuration.

intrumRiskOwner

AN

Which party should take the risk. Possible values: IJ (Intrum Justitia) or CLIENT.

intrumPaperInvoice

AN

Wheter or not to send a paper invoice. Possible values: YES and NO.

intrumCustomData[1]

AN100

Custom fields.

intrumFirstRateAmount

N15,2

Installment amount of the first installment.
If multiple custom fields need to be submitted, the intrumCustomData[*] format can be used. Where N=1 would be the first custom field and N=2 the second one. The interface has support for up to 10 custom fields. The value sent into refno2 is linked to intrumCustomData[1]; when both fields have values the refno2 will prevail.
Table 12. Additional Byjuno response parameters.
Element Format Description

allowedPaymentMethods

AN

List of the available payment options returned by a successful credit decision check. Those Byjuno payment methods can be submitted with the sub_pmethod parameter. For example:

<sub_pmethod>BYJUNO-INVOICE</sub_pmethod>
The refno (AN18) of the merchant order will be forwarded to Byjuno and has to be unique.
Table 13. Additional optional Byjuno request parameters for settlement
Element Format Description

closeTransaction

AN

Possible values: yes and no

Byjuno has support for partial settlement. If one of the partial settlement requests will send closeTransaction=true it will close the partial settlement process, no other settlement requests will be accepted.

CRIF Deltavista

Payment method code: DVI

Only reqtype=SCN is supported.

CRIF Deltavista does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/crif-deltavista.

EPS (stuzza.at)

Payment method code: EPS

Table 14. Additional EPS optional request parameters for web transactions
Element Format Description

bankbic

AN11

Identification of the customer’s (buyer’s) financial institution by a BIC

refno2

AN27

Structured remittance identifier "Zahlungsreferenz"

Easypay

Payment method code: ESY

Table 15. Additional Easypay specific request parameters for web transactions
Element Format Description

easyPaymentInfo

AN50

This value is displayed on the external Swisscom webpage, in the notification SMS, in the Swisscom customer center and on the consumer‘s bill.

If parameter is not submitted, the value from parameter refno will be taken. If parameter is submitted without value, an error will occure on Swisscom webpage. Allowed characters: A-Za-z0-9_-

easyTitle

AN25

Title of the content/product. Will be displayed on external webpage from Swisscom. Allowed characters: A-Za-z0-9_-

easyDescription

AN50

Description of the content/product. Will be displayed on external webpage page from Swisscom. Allowed charcters: Everything except ‘<’, ‘>’, ‘&’

Girosolution EPS

Payment method code: GEP

Table 16. Additional Girosolution EPS optional request parameters for web transactions
Element Format Description

bankbic

AN11

BIC (8 or 11-digits)

refno2

AN27

Purpose
Table 17. Additional Girosolution EPS response parameters
Element Format Description

gepBankcode

N

Bank code

gepBankname

AN

Bank name

gepBackendTxId

AN

payment processor transaction ID

UATPNumber

AN

UATP cardnumber

UATPExpYear

N4

expiry year of UATP card (format: YYYY)

UATPExpYear

N2

expiry month of UATP card (format: MM)

Giropay

Payment method code: GPA

Giropay supports Article details parameters. However, only uppArticle_N_Name and uppArticle_N_Description can be used.
Table 18. Additional Giropay optional request parameters for web transactions
Element Format Description

bankbic

AN11

BIC (8 or 11-digits)

refno2

AN27

Purpose

uppArticle_1_Name

AN30

Additional information field which is shown on the payment form (label)

uppArticle_1_Description

AN80

Additional information field which is shown on the payment form (text)

Information for multiple labels and texts (max 5) can be submitted by adding additional parameters for article. The names of the additional parameters for articles are defined as: uppArticle_2_Name, uppArticle_2_Description, etc.

Table 19. Additional Giropay response parameters
Element Format Description

gpaBankcode

N

Bank code

gpaBankname

AN

Bank name

gpaBackendTxId

AN

payment processor transaction ID

gpaObvName

AN

Optional adjustable field, which includes the name of the person who has to be verified (giropay-ID)

gpaResultAVS

N

Age verification result code

UATPNumber

AN

UATP cardnumber

UATPExpYear

N4

expiry year of UATP card (format: YYYY)

UATPExpYear

N2

expiry month of UATP card (format: MM)

Google Pay

Payment method code: PAY

Table 20. Additional mandatory Google Pay request parameters for server to server authorizations.
Element Format Description

googlePayData

AN

The data received from Google when integrating the Buy with Google Pay button. Needs to be wrapped in a CDATA element:

<![CDATA[
{
  "signature": "...",
  "protocolVersion": "ECv1",
  "signedMessage": "{\"encryptedMessage\":\"...\"}"
}
]]>

The data above is truncated. Make sure to submit the whole cryptogram received by Google.

iDEAL

Payment method code: DEA

iDEAL does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/ideal.

Klarna

Payment method code: KLN

Checkout which Customer details parameters are mandatory for Klarna. In addition, Klarna supports the Customer details and Shipping details parameters.
Table 21. Additional Klarna specific request parameters
Element Format Description

uppCustomerCompanyRegisterNumber

mandatory for B2B

AN100

Register number of the company

uppCustomerLanguage

default DE if not specified

AN2

Language to use with the Klarna payment page after redirect

uppCustomerCountry

default CH if not specified

AN2

Country of the customer

uppArticle_x_Type

AN

Type of the line item. It should be one of the following values [ physical | discount | shipping_fee | sales_tax | digital | gift_card ]
Table 22. Additional Klarna specific request parameters for events
Element Format Description

klarnaEvents[1].event_name

AN100

Name of the event, e.g. "Fancy Singer"

klarnaEvents[1].event_company

AN100

Name of the company arranging the event, e.g. "Happy Parties Ltd."

klarnaEvents[1].genre_of_event

AN100

Category or type of venue, "Pop"

klarnaEvents[1].arena_name

AN100

Name of the venue, "Song Arena"

klarnaEvents[1].arena_location.street_address

AN100

Street name of the arena.

klarnaEvents[1].arena_location.postal_code

AN100

Postal code of the arena.

klarnaEvents[1].arena_location.city

AN100

City of the arena.

klarnaEvents[1].arena_location.country

AN100

Country of the arena.

klarnaEvents[1].start_time

Datetime

Start time of the event, e.g. 2020-01-24 15:00

klarnaEvents[1].end_time

Datetime

End time of the event, e.g. 2020-01-24 18:00

klarnaEvents[1].access_controlled_venue

Boolean

Tickets are digitally checked when enetering the venue.

[ true | false ]

klarnaEvents[1].ticket_delivery_method

AN10

Ticket delivery menthod

[ pick_up | email | post | phone ]

klarnaEvents[1].ticket_delivery_recipient

AN100

The name of the recipient the ticket is delivered to. If email or phone, then use either the email address or the phone number.

klarnaEvents[1].affiliate_name

AN100

Name of the affiliate that originated the purchase. If none, leave blank.
If multiple events need to be submitted, the klarnaEvents[*] format can be used. Where N=1 would be the first event and N=2 the second one.
Table 23. Additional Klarna specific request parameters for subscriptions
Element Format Description

klarnaSubscriptions[1].subscription_name

AN100

Name of the product on subscription, e.g. "Contact lenses"

klarnaSubscriptions[1].start_time

Datetime

Start time of the subscription, e.g. 2020-01-24 15:00

klarnaSubscriptions[1].end_time

Datetime

End time of the subscription, e.g. 2020-01-24 18:00

klarnaSubscriptions[1].auto_renewal_of_subscription

Boolean

Info whether the subscription will be auto renewed upon expiry.

klarnaSubscriptions[1].affiliate_name

AN100

Name of the affiliate that originated the purchase. If none, leave blank.
If multiple subscriptions need to be submitted, the klarnaSubscriptions[*] format can be used. Where N=1 would be the first subscription and N=2 the second one.
Table 24. Additional Klarna specific request parameters for customer account info
Element Format Description

klarnaCustomerAccountInfos[1].unique_account_identifier

AN100

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

klarnaCustomerAccountInfos[1].account_registration_date

Datetime

Registration time of the customer account, e.g. 2020-01-24 15:00

klarnaCustomerAccountInfos[1].account_last_modified

Datetime

Last modified time of the customer account, e.g. 2020-01-24 18:00
If multiple customer account infos need to be submitted, the klarnaCustomerAccountInfos[*] format can be used. Where N=1 would be the first customer account info and N=2 the second one.
Table 25. Additional Klarna specific request parameters for payment history simple
Element Format Description

klarnaPaymentHistorySimple[1].unique_account_identifier

AN100

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

klarnaPaymentHistorySimple[1].paid_before

Boolean

Whether the customer has paid before or not
Table 26. Additional Klarna specific request parameters for payment history full
Element Format Description

klarnaPaymentHistoryFull[1].unique_account_identifier

AN100

Unique name / number to identify the specific customer account. Max 24 characters. E.g. "Adam Adamsson"

klarnaPaymentHistoryFull[1].payment_option

AN

Type of the line item. It should be one of the following values

[ card | direct banking | non klarna credit | sms | other ]

klarnaPaymentHistoryFull[1].number_paid_purchases

N

Total number of successful purchases

klarnaPaymentHistoryFull[1].total_amount_paid_purchases

N

Total amount of successful purchases (local currency), e.g. 1234.00

klarnaPaymentHistoryFull[1].date_of_last_paid_purchase

Datetime

Date of last paid purchase, e.g. 2020-01-24 15:00

klarnaPaymentHistoryFull[1].date_of_first_paid_purchase

Datetime

Date of the first paid purchase, e.g. 2020-01-24 15:00

Maestro

Payment method code: MAU

Maestro does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/maestro-international.

Mediamarkt Shopping Card

Payment method code: MMS

Mediamarkt Shopping Card does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/mediamarkt-shopping-card.

MFGroup Powerpay

Payment method codes: MFX, MFG and MFA

Checkout which Common parameters are mandatory for the different MFGroup Powerpay payment methods.
Table 27. Additional optional request parameters for MFX and MFA
Element Format Description

uppCustomerName

mandatory for B2B

AN100

Name of the company.

For B2B, parameters uppCustomerFirstName, uppCustomerLastName, uppCustomerGender and uppCustomerBirthDate are optional.
Table 28. Additional request parameters for MFG
Element Format Description

virtualCardno

mandatory

AN100

The virtual card number of the customer. Returned to the success URL when submitting returnVirtualCardno=yes with MFX or MFA.

installmentType

AN30

The parameters that are necessary to offer paying on installments to the customers are the following: <installmentNumber>, <installmentAmount>, <installmentFees>, <installmentInterests>. We will send those fields in the response if the field <installmentType> is i.e. 4in12, which means 4 payments in 12 months. Merchant need special agreement for this option with MFGroup.

atOwnRisk

AN30

This parameters gives the merchant the possibility to take the risk for some transactions, especially when the <amount> is higher than the <mfaAvailableCredit> of the customer. Please consider, that the merchant has to be authorized by MFGroup first, to do such kind of transactions.

refno2

AN27

Will be forwarded as parameter ExternalReference2 to MFGroup

refno3

AN27

Will be forwarded as parameter ExternalReference3 to MFGroup

InvoiceOnDelivery

yes

Whether an invoice should be sent together with the delivery. If yes, the response parameter ESRData will contain the necessary data to print the payment slip.
Table 29. Additional response parameters for MFA
Element Description

mfaAvailableCredit

The credit of the customer currently available for purchases.

mfaMaximalCredit

The maximum credit available for this customer

mfaReference

The customers reference within the MFGroup system which can be saved and used to retrieve the customer and his account for further purchases; to be submitted with all subsequent transactions of the same customer.

mfaCreditRefusalReason

contains the result of the credit check, which is None in case of success

mfaResponseCode

Response code from MFGroup

errorDetail

Returned in case of error. Possible values are: * unknown address - customer is unknown or was not found * other - request was declined because of an unknown error.

installmentNumber

The number of installments the customer has to pay.

installmentAmount

The amount of each installment the customer has to pay (including installment fees and installment interest), amount in the smallest available unit.

installmentFees

The amount of fees included in the installments, amount in the smallest available unit.

installmentInterests

The amount of interests included in the installments, amount in the smallest available unit.
Table 30. Additional response parameters for MFG
Element Description

ESRData

XML element - contains all needed data to correctly print the payment slip.

BankConnection

XML element - contains data for direct bank connection.

Migros Bank E-Pay

Payment method code: MDP

Table 31. Additional Migros Bank E-Pay optional request parameters for web transactions
Element Format Description

mdpUserId

A18

Username of registered MDP customer.

mdpAlias

A18

needed if a payment shall be processed as an alias payment
Table 32. Additional Migros Bank E-Pay response parameters
Element Format Description

mdpAlias

A18

Alias (if requested by merchant and confirmed by the customer) when using useAlias=yes

txnMbRefNo

A18

Migros Banks unique transaction reference number

myOne Card

Payment method code: MYO

myOne Card does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/myone-card.

Paysafecard

Payment method code: PSC

Table 33. Additional mandatory Paysafecard request parameters for web transactions
Element Format Description

paysafecardMerchantClientId

AN11

This parameter is identifying the customer, i.e. 2 transactions made from the same customer must have the same paysafecardMerchantClientId. You can use the unique ID of your customer as registered within your database, for example. If you are using the e-mail address or any other personal information, please encrypt it.

PayPal

Payment method code: PAP

Please note

  1. It’s not possible to process PayPal transactions within an <iframe>

  2. PayPal authorizations expire within 30 days. older transactions can’t be recovered
PayPal reference transactions

This option allows to process recurring transactions as a back-end process without user authentication. It is therefore suitable for monthly subscription billing or mobile applications with one click check-out. Creating an alias works the same way as for credit cards. The PayPal billing agreementId will be returned within response parameter aliasCC. The Authorization with an existing alias API can then be used to do an authorization without customer interaction. You need to grant special permissions to your merchant PayPal account to process reference transactions. Please contact us for more details.

Table 34. Submitting line items
Element Format Description

ITEMAMT

N

Header item: Total amount of all items (L_AMT0 * L_QTY0) + (L_AMT1 * L_QTY1) + …​

TAXAMT

N

Header item: Total tax amount in cents (L_TAXAMT0 * L_QTY0) + (L_TAXAMT1 * L_QTY1) + …​

SHIPPINGAMT

N

Header item: total shipping fees excluding tax.

L_NAMEn

AN20

Line item: Item name - For example L_NAME1=Beer

L_AMTn

N

Line item: price per items in cents

L_Numbern

N

Line item: article number

L_Descn

AN20

Line item: description

L_QTYn

N

TLine item: number of items

L_TAXAMTn

N

Line item: tax amount

The final amount parameter is calculated from ITEMAMT + SHIPPINGAMT + TAXAMT.
Table 35. Additional PayPal specific parameters
Element Format Description

uppForwardCustomerDetails

yes if the Customer details (if submitted) should be forwarded to PayPal. The following Customer details parameters are mandatory so that PayPal will display (uppDisplayShippingDetails=yes) them:

  • uppCustomerName

  • uppCustomerStreet

  • uppCustomerCity

  • uppCustomerZipCode

  • uppCustomerCountry

  • uppCustomerState

uppDisplayShippingDetails

Regulates whether the shipping details are displayed or not. (Note: uppForwardCustomerDetails and uppDisplayShippingDetails should be set to no if the shipping details should not be shown on the PayPal page.

pendingPayPal

This parameter will be returned only if the PayPal transaction is in a pending status. Pending means that the transaction couldn’t be confirmed by PayPal. Make sure to contact PayPal directly in this case.

PostFinance Card and PostFinance E-Finance

Payment method codes: PFC, PEF

PostFinance does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/postfinance-card and https://docs.datatrans.ch/docs/postfinance-e-finance.

Reka

Payment method code: REK

Reka does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/boncard.

Samsung Pay

Payment method code: SAM

Table 36. Additional mandatory Samsung Pay request parameters for server to server authorizations.
Element Format Description

samsungPayData

AN

The data received from Samsung when integrating the Pay with Samsung Pay button. Needs to be wrapped in a CDATA element:

<![CDATA[
{
  "resultCode": "0",
  "resultMessage": "SUCCESS",
  "method": "3DS",
  "card_brand": "MC",
  "card_last4digits": "0018",
  "3DS": {
    "type": "S",
    "version": "100",
    "data": "eyJhbGciFH3DpkWjijCGpEnTiDq0g"
  },
  "wallet_dm_id": "nMpLjujxa0m9mSfFN1J0="
}
]]>

Sofort

Payment method code: DIB

Sofort does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/sofort.

Swissbilling

Payment method code: SWB

Checkout which Customer details are mandatory for Swissbilling. In addition, Swissbilling supports the Shipping details and Article details parameters.
Table 37. Additional optional request parameters for Swissbilling
Element Format Description

reqtype

A3

Use SCN if only a pre-screening request should be done. When using NOA, a screening and authorization request will be done.

uppCustomerName

mandatory for B2B

AN100

Name of the company

uppCustomerType

mandatory for B2B

A1

Either P (=person/B2C) or C (=company/B2B)

taxAmount

DN

Total VAT amount for this purchase

uppDiscountAmount

DN

Total discount amount, use positive value

For Swissbilling, when doing server to server authorizations, article details must be submitted within the <order> element. For example:

<order>
  <article>
    <quantity>1</quantity>
    <taxPercent>6.94</taxPercent>
    <type>goods</type>
    <id>PK123423</id>
    <price>7200</price>
    <description>XBox Live Gold Card 12+1 Monate im FiFA 14 Design</description>
    <name>XBox Live+Gold Card</name>
    <tax>500</tax>
  </article>
  <article>
    <id>PK43563456</id>
    <quantity>1</quantity>
    <price>13000</price>
    <type>goods</type>
    <taxPercent>7.38</taxPercent>
    <name>Kinect Sensor</name>
    <tax>960</tax>
    <description>Kinect Adventures</description>
  </article>
</order>
For web transactions using one of the Integrations the article details can be submitted as usual.

TWINT

Payment method code: TWI

TWI does not have any additional request or response parameters. Please refer to the web and curl samples on https://docs.datatrans.ch/docs/twint.