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: 20.01.21 - 16:44 UTC
The below steps describe a basic way of how a transaction flow with Datatrans can work:
transactionId
.transactionId
.https://pay.sandbox.datatrans.com/v1/start/transactionId
<script src="https://pay.sandbox.datatrans.com/upp/payment/js/datatrans-2.0.0.js">
payButton.onclick = function() {
Datatrans.startPayment({
transactionId: "transactionId"
});
};
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.transactionId
to perform different actions like cancel, credit and settleFor SecureFields please refer to the server to server SecureFields init operation.
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 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.
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"
}
}
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.
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.
card.3D.cardholderInfo
(if available) from the Status API.ALP
KLN
SWB
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.
currency required | string 3 characters 3 letter ISO-4217 character code. For example |
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 |
object (CustomerRequest) Whenever the payment method supports | |
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 | |
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: "en" "de" "fr" "it" "es" "el" "no" "da" "pl" "pt" "ru" "ja" 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" "SWB" "SCX" "SWP" "TWI" "UAP" "VIS" "ALP" An array of payment method shortnames. For example |
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 | |
object (AlipayRequest) Alipay specific parameters | |
object (SwissBillingRequest) Swissbilling specific parameters. |
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 |