Datatrans API Reference (2.0.5)

Download OpenAPI specification:Download

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.

Last updated: 17.11.20 - 13:43 UTC

Transaction flow

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

  • Send all the needed parameters with a secure server to server call to Datatrans and retrieve a transactionId.
  • Redirect the customers browser to the Payment Page by using the returned transactionId.
    • When using the Redirect Mode, The URL where the customers browser needs to be redirected to looks like:
      https://pay.sandbox.datatrans.com/v1/start/transactionId
    • When using the Lightbox Mode, make sure to use the latest version of the JS library:
      <script src="https://pay.sandbox.datatrans.com/upp/payment/js/datatrans-2.0.0.js">
      payButton.onclick = function() {
        Datatrans.startPayment({
          transactionId:  "transactionId"
        });
      };
  • The customer enters their payment details and presses the Pay button.
  • The transactionId and other important parameters will be sent to your Webhook URL. Store them in your DB. In addition, the transactionId will also be sent to your success/cancel/error URLs.
  • The browser will be redirected to the success/cancel/error page.
  • Use the transactionId to perform different actions like cancel, credit and settle

For SecureFields please refer to the server to server SecureFields init operation.

Idempotency

For mutable API calls we allow to pass a unique value with the Idempotency-Key header. Those requests can then safely be retried in case a network error happens. For example:

curl -i -u 1100007283:hl2ROSRqCvjnDVRK 'https://api.sandbox.datatrans.com/v1/transactions' \
    -H 'Content-Type: application/json; charset=UTF-8' \
    -H 'Idempotency-Key: e75d621b-0e56-4b71-b889-1acec3e9d867' \
    -d '{
    "refno" : "58b389331dad",
    "amount" : 1000,
    "currency" : "CHF",
    "paymentMethod" : [ "VIS", "ECA", "PAP" ],
    "option" : {
       "createAlias" : true
    }
}'

Authentication

Authentication to the APIs is performed via HTTP basic authentication. Provide your merchantId as the basic authentication username value. To get the password, login to Webadmin and enable server to server security under UPP Administration > Security.

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.

Basic

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Errors

Datatrans uses HTTP response codes to indicate if an API call was successful or resulted in a failure. HTTP 2xx status codes indicate a successful API call whereas HTTP 4xx status codes indicate client errors or if something with the transaction went wrong (for example a decline). In rare cases HTTP 5xx status codes are returned. Those indicate errors on Datatrans side.

Sample HTTP 400 error response payload if a property has a wrong value

{
  "error" : {
    "code" : "INVALID_PROPERTY",
    "message" : "init.initRequest.currency The given currency does not have the right format"
  }
}

Webhook

After each authorization Datatrans tries to call the configured Webhook (POST) URL. The Webhook URL can be configured within the Webadmin Tool. The Webhook payload is the exact same as for the Status API.

Webhook signing

Add an additional security layer by signing our webhooks. To get your HMAC key (sign2), login to our dashboard and navigate to the Security settings in your merchant configuration. If not already done, select the checkbox Use another key for sign2 generation. Datatrans will use this key to calculate a signature. Once the checkbox is active, we will generate a new HMAC key and add two parameters within the HTTP request header Datatrans-Signature: A unique timestamp and the expected signature. For example:

Datatrans-Signature: t=1559303131511,s0=33819a1220fd8e38fc5bad3f57ef31095fac0deb38c001ba347e694f48ffe2fc

To calculate the expected signature, concatenate the timestamp as a string with the webhook payload. Convert the resulting string to bytes and finally create a signature with your HMAC key using SHA256. Finally, compare your calculation to the expected signature s0. Examples:

Java

// hex bytes of the key
byte[] key = Hex.decodeHex(key);

// Create sign with timestamp and payload
String algorithm = "HmacSha256";
SecretKeySpec macKey = new SecretKeySpec(key, algorithm);
Mac mac = Mac.getInstance(algorithm);
mac.init(macKey);
mac.update(String.valueOf(timestamp).getBytes());
byte[] result = mac.doFinal(payload.getBytes());
String sign = Hex.encodeHexString(result);

Python

# hex bytes of the key
key_hex_bytes = bytes.fromhex(key)

# Create sign with timestamp and payload
sign = hmac.new(key_hex_bytes, bytes(str(timestamp) + payload, 'utf-8'), hashlib.sha256)

If the value of sign is equal to s0 from the Datatrans-Signature header, the webhook payload is valid and was not tampered.

/v1/transactions

Initialize a transaction

Securely send all the needed parameters to the transaction initialization API. The result of this API call is a HTTP 201 status code with a transactionId in the response body and the Location header set. If you want to use the payment page redirect mode to collect the payment details, the browser needs to be redirected to this URL to continue with the transaction. Following the link provided in the Location header will raise the Datatrans Payment Page with all the payment methods available for the given merchantId. If you want to limit the number of payment methods, the paymentMethod array can be used.

Authorizations:
Request Body schema: application/json
currency
required
string 3 characters

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

refno
required
string [ 1 .. 20 ] characters

The merchant's reference number. It should be unique for each transaction.

refno2
string [ 0 .. 17 ] characters

Optional customer's reference number. Supported by some payment methods or acquirers.

autoSettle
boolean

Whether to automatically settle the transaction after an authorization or not. Default is false.

object (CustomerRequest)

Whenever the payment method supports customer details, the customer object can be used. If a particular field is required varies from payment method to payment method. For example the field birthDate is not mandatory for each payment method supporting the customer object.

object (BillingAddress)
object (ShippingAddress)

The address where the article(s) should be sent to.

object (OrderRequest)

If supported by the payment method, an order with one or more articles can be defined.

object (BoncardRequest)

Boncard specific request parameters

object (CardInitRequest)

The card object to be submitted when initializing a transaction with an existing alias. The inner 3D object can be used to submit all mandatory, conditional and optional 3D 2.0 parameters.

object (PayPalInitRequest)

PayPal specific parameters

object (PfcInitRequest)
object (RekaRequest)

Reka card specific parameters

object (KlarnaInitRequest)
object (TwintRequest)

Twint specific parameters

object (ByjunoRequest)

Byjuno specific request parameters.

object (AirlineDataRequest)

The airline data including ticket details.

amount
integer <int64>

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

language
string 2 characters
Enum: "de" "en" "fr" "it" "es" "el" "no" "da" "pl" "pt"

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

paymentMethods
Array of strings 3 characters
Items Enum: "ACC" "APL" "AMX" "AZP" "BON" "CFY" "CUP" "DIN" "DII" "DIB" "DIS" "DNK" "ECA" "ELV" "EPS" "ESY" "INT" "JCB" "JEL" "KLN" "MAU" "MFX" "MPX" "MYO" "PAP" "PAY" "PEF" "PFC" "PSC" "REK" "SAM" "SWP" "TWI" "UAP" "VIS"

An array of payment method shortnames. For example ["VIS", "PFC"]. If omitted, all available payment methods will be displayed on the payment page.

object (theme)

The theme (including configuration options) to be used when rendering the payment page.

object (RedirectRequest)

The redirect object is used to customize the browser behaviour when using the payment page (Redirect or Lightbox Mode) to do a transaction.

object (OptionRequest)
object (SwissPassRequest)

SwissPass specific parameters

object (MFXRequest)

MFX specific parameters

object (MPXRequest)

MPX specific parameters

object (AmazonPayRequest)

Amazon Pay specific request parameters

object (EpsRequest)

EPS specific request parameters

Responses

Response Headers
Location
string

A URL where the users browser needs to be redirect to complete the payment. This redirect is only needed when using Redirect Mode. For Lightbox Mode the returned transactionId can be used to start the payment page.

Response Schema: application/json
transactionId
integer <int64>

The transactionId to be used when using Redirect- or Lightbox Mode. If no further action happens with the transactionId after initialization, it will be invalidated after 30 minutes.

mobileToken
string

Mobile token which is needed to initialize the Mobile SDKs.

object (Secure3DResponse)

The 3D object is only present if init call was done with an alias.

Response Schema: application/json
object (TransactionsError)

Request samples

Content type
application/json
Example

initRequest1

{
  • "currency": "CHF",
  • "refno": "cK1lO9XLv",
  • "amount": 1337