Datatrans logo
API docs by Redocly

Datatrans API Reference (2.0.43)

Download OpenAPI specification:Download

E-mail: [email protected] URL: https://docs.datatrans.ch

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 support@datatrans.ch if something is missing or unclear.

Last updated: 18.04.24 - 11:31 UTC

Payment Process

The following steps describe how transactions are processed with Datatrans. We separate payments in three categories: Customer-initiated payments, merchant-initiated payments and after the payment.

Customer Initiated Payments

We have three integrations available: Redirect, Lightbox and Secure Fields.

Redirect & Lightbox

  • Send the required parameters to initialize a transactionId to the init endpoint.
  • Let the customer proceed with the payment by redirecting them to the correct link - or showing them your payment form.
    • Redirect: Redirect the browser to the following URL structure
      https://pay.sandbox.datatrans.com/v1/start/transactionId
    • Lightbox: Load the JavaScript library and initialize the payment form:
      <script src="https://pay.sandbox.datatrans.com/upp/payment/js/datatrans-2.0.0.js">

      payButton.onclick = function() {
  Datatrans.startPayment({
    transactionId:  "transactionId"
  });
};
  • Your customer proceeds with entering their payment information and finally hits the pay or continue button.
  • For card payments, we check the payment information with your acquirers. The acquirers check the payment information with the issuing parties. The customer proceeds with 3D Secure whenever required.
  • Once the transaction is completed, we return all relevant information to you (check our Webhook section for more details). The browser will be redirected to the success, cancel or error URL with our datatransTrxId in the response.

Secure Fields

  • Send the required parameters to initialize a transactionId to our secureFieldsInit endpoint.
  • Load the Secure Fields JavaScript libarary and initialize Secure Fields:
    <script src="https://pay.sandbox.datatrans.com/upp/payment/js/secure-fields-2.0.0.js">

    var secureFields = new SecureFields();
secureFields.init(
  {{transactionId}}, {
      cardNumber: "cardNumberPlaceholder",
      cvv: "cvvPlaceholder",
  });
  • Handle the success event of the secureFields.submit() call.
  • If 3D authentication is required for a specific transaction, the redirect property inside the data object will indicate the URL that the customer needs to be redirected to.
  • Use the Authorize an authenticated transactionendpoint to fully authorize the Secure Fields transaction. This is required to finalize the authorization process with Secure Fields.

Merchant Initiated Payments

Once you have processed a customer-initiated payment or registration you can call our API to process recurring payments. Check our authorize endpoint to see how to create a recurring payment or our validate endpoint to validate your customers’ saved payment details.

After the payment

Use the transactionId to check the status and to settle, cancel or refund a transaction.

Idempotency

To retry identical requests with the same effect without accidentally performing the same operation more than needed, you can add the header Idempotency-Key to your requests. This is useful when API calls are disrupted or you did not receive a response. In other words, retrying identical requests with our idempotency key will not have any side effects. We will return the same response for any identical request that includes the same idempotency key.

If your request failed to reach our servers, no idempotent result is saved because no API endpoint processed your request. In such cases, you can simply retry your operation safely. Idempotency keys remain stored for 60 minutes. After 60 minutes have passed, sending the same request together with the previous idempotency key will create a new operation.

Please note that the idempotency key has to be unique for each request and has to be defined by yourself. We recommend assigning a random value as your idempotency key and using UUID v4. Idempotency is only available for POST requests.

Idempotency was implemented according to the "The Idempotency HTTP Header Field" Internet-Draft

Scenario Condition Expectation
First time request Idempotency key has not been seen during the past 60 minutes. The request is processed normally.
Repeated request The request was retried after the first time request completed. The response from the first time request will be returned.
Repeated request The request was retried before the first time request completed. 409 Conflict. It is recommended that clients time their retries using an exponential backoff algorithm.
Repeated request The request body is different than the one from the first time request. 422 Unprocessable Entity.

Example:

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

Authentication

Authentication to the APIs is performed with HTTP basic authentication. Your merchantId acts as the username. To get the password, login to the dashboard and navigate to the security settings under UPP Administration > Security.

Create a base64 encoded value consisting of merchantId and password (most HTTP clients are able to handle the base64 encoding automatically) and submit the Authorization header with your requests. Here’s an example:

base64(merchantId:password) = MTAwMDAxMTAxMTpYMWVXNmkjJA==

Authorization: Basic MTAwMDAxMTAxMTpYMWVXNmkjJA==

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

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.

Here’s the payload of a sample HTTP 400 error, showing that your request has wrong values in it

{
  "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 dashboard. It is also possible to overwrite the configured webhook URL with the init.webhook property. The Webhook payload contains the same information as the response of a Status API call.

Webhook signing

If you want your webhook requests to be signed, setup a HMAC key in your merchant configuration. To get your HMAC key, login to our dashboard and navigate to the Security settings in your merchant configuration to view your server to server security settings. Select the radio button Important parameters will be digitally signed (HMAC-SHA256) and sent with payment messages. Datatrans will use this key to sign the webhook payload and will add a Datatrans-Signature HTTP request header:

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

On your server, calculate the signature of the webhook payload and finally compare it to s0. timestamp is the t value from the Datatrans-Signature header, payload represents all UTF-8 bytes from the body of the payload and finally key is the HMAC key you configured within the dashboard. If the value of sign is equal to s0 from the Datatrans-Signature header, the webhook payload is valid and was not tampered.

Java

// hex bytes of the key

// if Java version < 17, a 3rd-party library like apache-commons can be used
byte[] key = Hex.decodeHex(key);

// if Java version >= 17, the built in HexFormat class can be used
byte[] key = HexFormat.of().parseHex(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)

Release notes

Details

2.0.43 - 18.04.2024

  • added DEVICE_TOKEN as possible card type in the Authorize API
  • added the card type behavior to the Init API

2.0.42 - 13.02.2024

  • added paycard to MFA/MFX
  • added better support for Amex Network Tokenization
  • multiple fixes related to PLU
  • fixed idempotency behavior in case of a response with status 500
  • fixed 3D enrollment for CBL cards in Init API

2.0.41 - 17.01.2024

  • added cardholder to alias patch request
  • added fingerprint implementation for TWI
  • added option.storeCustomerData to the authorize API
  • added MFG to the screen API

2.0.40 - 14.11.2023

  • added avs object to the status api
  • added ELV object to the status api
    • mandateId and iban are returned if available
  • added secure fields init tokenize

2.0.39 - 18.10.2023

  • added fingerprint support for Twint aliases
  • fixed broken link in idempotency chapter
  • adjusted java sign example

2.0.38 - 04.10.2023

  • added support for PLU
  • added support for CUV
  • added MFG support for the authorize API
  • added init.option.storeCustomerData

2.0.37 - 19.07.2023

  • added MPX paycard number to the status API
  • added airlineData to the Authorize Split API
  • added wallet indicator in Alias Status response
  • added Alipay+ support
  • added documentation for Twint+ parameters
  • added support for ferry reservations for Klarna
  • added 3D2.2 feature 3RI
  • added support for MPA and MPG
  • fixed bug in MCP handling
  • fixed the handling of authorize.card.3D.threeDSTransactionId
  • fixed Klarna subtype documentation for the Status API

2.0.36 - 16.03.2023

  • added MBP (MobilePay) payment method
  • added uniqueRefno handling to the init API
    • if the unique refno feature is enabled the init does not accept duplicated refnos anymore. even if the redirect never happens.
  • added proper error mappings for various errors with code UNKNOWN_ERROR

2.0.35 - 08.02.2023

  • added VPS (Vipps) payment method
  • added SWP to the authorize API
  • added imageUrl to the article property for KLN
  • fixed wrong validation for the marketplace property
  • added proper error mappings for various errors with code UNKNOWN_ERROR

2.0.34 - 12.12.2022

  • added support for accertify
  • increase the maximum length of refno to 40 characters
  • refactor of MCP properties to support static MCP

2.0.33 - 08.11.2022

  • fixed the openapi specification
    • renamed the models
    • removed illegal characters from the specification
  • added validation to some 3D properties

2.0.32 - 12.10.2022

  • added different card types PlainCard, AliasCard and NetworkTokenCard for the authorize and init endpoint
    • the old card type is still supported
  • fixed webhook.url for mobile flows
  • improved the API docs for statusResponse.status

2.0.31 - 06.10.2022

  • update API docs for status.language in the status response

2.0.30 - 23.09.2022

  • added qrData to MPX and MFX in the status API response
  • added support for KLN train reservations
  • added additional airPlus properties
  • added the ELV request properties to the API docs (init and authorize API)
  • fix MCP sample request/response examples in the api docs
  • fix date format issues for airPlus properties

2.0.29 - 17.08.2022

  • added merchantId to the status API response
  • added SWH (Swish) payment method
  • added messageExtensions to init.card.3d
  • added authorizeResponse.card to the API docs
  • added GFT (MFG Gift Card) payment method
  • added CBL (Cartes Bancaires) payment method
  • added HPC (Hipercard) payment method
  • added airPlus to the init API request
  • added more languages to the init.language API docs
  • cleaned up order.article property
  • extended the init flow to work also with tokenization mode
  • improved the api docs for the credit api
  • no card object is returned in the alias info response if the content is empty
  • fix the status api now also returns the externalCode for INT transactions
  • fix enrollment check in init api if init.number is set with plain card number
  • fix handle airlineData date format issues

2.0.28 - 23.05.2022

  • Added support to send a webhook URL along the init request. If set, it overwrites the POST URL configured in the dashboard.
    • See init.webhook for more information.

2.0.27 - 13.04.2022

  • Added MCP support (Multi Currency Processing)
    • Added new GET /v1/multicurrency/rates API to fetch the MCP rates.
    • Added init.mcp property
    • Added authorize.mcp property
    • Added mcp property in the status response if available for the transaction

2.0.26 - 16.03.2022

  • Added the OpenAPI description for the GET /v1/aliases/{alias} response.

2.0.25 - 02.03.2022

  • New API /v1/transactions/{transactionId}/increase to increase the amount for an authorized transaction (credit cards only).

2.0.24 - 15.12.2021 🎄

  • Added full support for invoiceOnDelivery when using MFX or MPX as payment method.
  • The Status API now returns the ESR data for MFX and MPX when invoiceOnDelivery=true was used.

2.0.23 - 20.10.2021

  • Added support for Klarna KLN hotel extended merchant data (EMD)

2.0.22 - 21.07.2021

  • Added full support for Swisscom Pay ESY
  • The marketplace object now accepts an array of splits.

2.0.21 - 21.05.2021

2.0.20 - 18.05.2021

  • In addition to debit and credit the Status API now also returns prepaid in the card.info.type property.
  • paysafecard - Added support for merchantClientId

2.0.19 - 03.05.2021

  • Fixed PAP.orderTransactionId to be a string
  • Added support for PAP.fraudSessionId (PayPal FraudNet)

2.0.18 - 21.04.2021

  • Added new POST /v1/transactions/screen API to check a customer's credit score before sending an actual authorization request. Currently only INT (Byjuno) is supported.

2.0.17 - 20.04.2021

  • Added new GET /v1/aliases API to receive more information about a particular alias.

2.0.16 - 13.04.2021

  • Added support for Migros Bank E-Pay MDP

2.0.15 - 24.03.2021

  • Byjuno - renamed subPaymentMethod to subtype (subPaymentMethod still works)
  • Klarna - Returning the subtype (pay_now, pay_later, pay_over_time, direct_debit, direct_bank_transfer) from the Status API

2.0.14 - 09.03.2021

  • Byjuno - Added support for customData and firstRateAmount
  • Returning the transactionId (if available) for a failed Refund API call.

2.0.13 - 15.02.2021

  • The Status and Webhook payloads now include the language property
  • Fixed a bug where card.3D.transStatusReason and card.3D.cardholderInfo was not returned

2.0.12 - 04.02.2021

  • Added support for PayPal transaction context (STC)
  • Fixed a bug where the transaction status did not switch to failed after it timed out
  • Fixed a bug with option.rememberMe not returning the Alias from the Status API

2.0.11 - 01.02.2021

  • Returning card.3D.transStatusReason (if available) from the Status API

2.0.10 - 18.01.2021

  • Returning card.3D.cardholderInfo (if available) from the Status API

2.0.9 - 21.12.2020

  • Added support for Alipay ALP

2.0.8 - 21.12.2020

  • Added full support for Klarna KLN
  • Added support for swissbilling SWB

/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. This call is required to proceed with our Redirect and Lightbox integration

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

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

refno
required
string [ 1 .. 40 ] characters

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

refno2
string [ 0 .. 40 ] 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. If not present with the init request, the settings defined in the dashboard ('Authorisation / Settlement' or 'Direct Debit') will be used. Those settings will only be used for web transactions and not for server to server API calls.

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 (CardInit)
object (BoncardRequest)

Boncard specific request parameters

object (PayPalInitRequest)

PayPal specific parameters

object (PfcInitRequest)
object (RekaRequest)

Reka card specific parameters

object (KlarnaInitRequest)
object (TwintInitRequest)
object (ByjunoAuthorizeRequest)
object (AlipayRequest)

Alipay+ specific parameters

object (ESY)
object (MfaAuthorizeRequest)

MFA specific parameters. At least an empty MFA object is required if MFA should be processed. Even if no additional parameters are sent.

object (SwissPassRequest)

SwissPass specific parameters

object (SBBHalbtaxPlusInitRequest)
object (AirlineDataRequest)

The airline data including ticket details.

accertify
object (Accertify)

Accertify decision (Accepted, Review, Declined

object (ThreeRIData)
DVI
object (DeltaVistaData)

DVI has no specific request parameters but we need an empty object here to handle it as a DVI request.

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" "fi" "hu" "ko" "nl" "no" "da" "pl" "pt" "ru" "ja" "sk" "sl" "sv" "tr" "zh"

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 = 3 characters ]
Items Enum: "ACC" "ALP" "APL" "AMX" "AZP" "BAC" "BON" "CBL" "CFY" "CSY" "CUP" "DEA" "DIN" "DII" "DIB" "DIS" "DNK" "ECA" "ELV" "EPS" "ESY" "GFT" "GPA" "HPC" "INT" "JCB" "JEL" "KLN" "MAU" "MDP" "MFA" "MFX" "MPA" "MFG" "MPG" "MPX" "MYO" "PAP" "PAY" "PEF" "PFC" "PSC" "REK" "SAM" "SWB" "SCX" "SWP" "TWI" "UAP" "VIS" "WEC" "SWH" "VPS" "MBP" "CUV" "GEP" "PLU" "DVI"

An array of payment method shortnames. For example ["VIS", "PFC"]. If omitted, all available payment methods will be displayed on the payment page. If the Mobile SDKs are used (returnMobileToken), this array is mandatory.

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 (WebhookRequest)

Used to define the webhook configuration. If not set, the webhook configuration from the merchant configuration will be used.

object (OptionRequest)
object (MFXRequest)

MFX specific parameters

object (MPXRequest)

MPX specific parameters

object (AmazonPayRequest)

Amazon Pay specific request parameters

object (EpsRequest)

EPS specific request parameters

object (SwishRequest)

Swish specific parameters

object (VippsRequest)

Vipps specific parameters

object (MobilePayRequest)

MobilePay specific parameters

object (WeChatRequest)

WeChat specific parameters

object (ElvInitRequest)

ELV specific payment parameters.

object (SwissBillingRequest)

Swissbilling specific parameters.

object (MDPInitRequest)
object (PaysafecardRequest)

Paysafecard specific request parameters

object (InitMcpRequest)
extensions
object (Extension)

An object for additional data for customized processes.

Responses

Request samples

Content type
application/json
Example

initRequest1

{}

Response samples

Content type
application/json

initResponse

{
  • "transactionId": "240418133228257610"
}

Initialize a Secure Fields transaction

Proceed with the steps below to process Secure Fields payment transactions:

  • Call the /v1/transactions/secureFields endpoint to retrieve a transactionId. The success result of this API call is a HTTP 201 status code with a transactionId in the response body.
  • Initialize the SecureFields JavaScript library with the returned transactionId:
    var secureFields = new SecureFields();
secureFields.init(
  transactionId, {
      cardNumber: "cardNumberPlaceholder",
      cvv: "cvvPlaceholder",
  });
  • Handle the success event of the secureFields.submit() call. Example success event data:
    {
  "event":"success",
  "data": {
      "transactionId":"{transactionId}",
      "cardInfo":{"brand":"MASTERCARD","type":"credit","usage":"consumer","country":"CH","issuer":"DATATRANS"},
      "redirect":"https://pay.sandbox.datatrans.com/upp/v1/3D2/{transactionId}"
  }
}
  • If 3D authentication is required, the redirect property will indicate the URL that the browser needs to be redirected to.
  • Use the Authorize an authenticated transaction endpoint to authorize the Secure Fields transaction. This is required to finalize the authorization process with Secure Fields.
  • Use the transactionId to check the status and to settle, cancel or credit (refund) an transaction.
Authorizations:
Basic
header Parameters
client-name
string
Enum: "ANDROID_SDK" "IOS_SDK" "LINK"
Request Body schema: application/json
required
amount
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

returnUrl
required
string

The URL where the browser will be redirected after the 3D authentication process.

object (InitMcpRequest)
object (SecureFieldsThreeDSecure)

Refer to the official EMVCo. specifications for parameter requirements.

Responses

Request samples

Content type
application/json

secureFieldsInitRequest1

{}

Response samples

Content type
application/json

secureFieldsInitResponse

{
  • "transactionId": "240418133228267612"
}

Authorize a transaction

To create a transaction without user interaction, send all required parameters to our authorize endpoint. This is the API call for merchant-initiated transactions with an existing alias. Depending on the payment method, additional parameters will be required. Refer to the payment method specific objects (for example PAP) to see which parameters are required additionally send. For credit cards, the card object has to be used

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

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

refno
required
string [ 1 .. 40 ] characters

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

refno2
string [ 0 .. 40 ] 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. If not present with the init request, the settings defined in the dashboard ('Authorisation / Settlement' or 'Direct Debit') will be used. Those settings will only be used for web transactions and not for server to server API calls.

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 (Card)
object (BoncardRequest)

Boncard specific request parameters

object (PayPalAuthorizeRequest)
object (PfcAuthorizeRequest)
object (RekaRequest)

Reka card specific parameters

object (KlarnaAuthorizeRequest)
object (TwintAuthorizeRequest)
object (ByjunoAuthorizeRequest)
object (AlipayRequest)

Alipay+ specific parameters

object (ESY)
object (MfaAuthorizeRequest)

MFA specific parameters. At least an empty MFA object is required if MFA should be processed. Even if no additional parameters are sent.

object (SwissPassRequest)

SwissPass specific parameters

object (SBBHalbtaxPlusAuthorizeRequest)
object (AirlineDataRequest)

The airline data including ticket details.

accertify
object (Accertify)

Accertify decision (Accepted, Review, Declined

object (ThreeRIData)
DVI
object (DeltaVistaData)

DVI has no specific request parameters but we need an empty object here to handle it as a DVI request.

amount
required
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

object (AccardaRequest)

Accarda specific request parameters.

object (GooglePayRequest)

The data received from Google when integrating the 'Buy with Google Pay' button. See https://github.com/datatrans/google-pay-web-sample for more information.

object (ApplePayRequest)

The data received from Apple when integrating the 'Buy with Apple Pay' button. See https://developer.apple.com/documentation/apple_pay_on_the_web for more information.

object (MpaAuthorizeRequest)

MPA specific parameters. At least an empty MPA object is required if MPA should be processed. Even if no additional parameters are sent.

object (MpgAuthorizeRequest)

MPG specific parameters.

object (MfgAuthorizeRequest)

MFG specific parameters.

object (MarketPlaceAuthorize)
object (ElvRequest)

ELV specific request parameters.

object (SwissBillingAuthorizeRequest)
object (AuthorizeOptionRequest)
object (AuthorizeMcpRequest)
extensions
object (Extension)

An object for additional data for customized processes.

object (ThreeRI)

3RI specific parameters

Responses

Request samples

Content type
application/json
Example

authorizeRequest1

{
  • "currency": "CHF",
  • "refno": "WeCUiwNqu",
  • "card": {
    },
  • "amount": 1000
}

Response samples

Content type
application/json

authorizeResponse

{
  • "transactionId": "240418133231147694",
  • "acquirerAuthorizationCode": "133231",
  • "card": {
    }
}

Authorize an authenticated transaction

Use this API endpoint to fully authorize an already authenticated transaction. This call is required for any transaction done with our Secure Fields or if during the initialization of a transaction the parameter option.authenticationOnly was set to true

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after authentication was done.

Request Body schema: application/json
required
amount
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

refno
required
string [ 0 .. 40 ] characters

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

refno2
string [ 0 .. 40 ] 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. If not present with the init request, the settings defined in the dashboard ('Authorisation / Settlement' or 'Direct Debit') will be used. Those settings will only be used for web transactions and not for server to server API calls.

CDM
object (CDMRequest)

CyberSource specific parameters. Use the same properties as you would for direct CyberSource requests.

https://developer.cybersource.com/api/reference/api-reference.html
object (AirlineDataRequest)

The airline data including ticket details.

object (AuthorizeSplitThreeDSecure)

3D secure parameters

Responses

Request samples

Content type
application/json

autorizeSplitRequest1

{
  • "amount": 1000,
  • "refno": "EERzMcLvv"
}

Response samples

Content type
application/json

authorizeSplitResponse

{
  • "acquirerAuthorizationCode": "133237"
}

Validate an existing alias

An existing alias can be validated at any time with the transaction validate API. No amount will be blocked on the customers account. Only credit cards (including Apple Pay and Google Pay), PFC, KLN and PAP support validation of an existing alias.

Authorizations:
Basic
Request Body schema: application/json
required

Validate an alias

refno
required
string [ 1 .. 40 ] characters

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

refno2
string [ 0 .. 40 ] characters

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

currency
required
string = 3 characters

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

object (CardValidateRequest)

The card object to be submitted when validating with an existing credit card alias.

object (PfcValidateRequest)

PostFinance Card specific parameters

object (KlarnaValidateRequest)

Klarna specific parameters

object (PayPalValidateRequest)

PayPal specific parameters for the validate request.

object (GooglePayValidateRequest)

Google Pay specific parameters for the validate request.

object (ApplePayValidateRequest)

Apple Pay specific parameters for the validate request.

object (EasyPayValidateRequest)

Swisscom Pay specific parameters

Responses

Request samples

Content type
application/json

validateRequest1

{
  • "refno": "LsBGQh7Yt",
  • "currency": "CHF",
  • "card": {
    }
}

Response samples

Content type
application/json

validateResponse

{
  • "transactionId": "240418133235777764",
  • "acquirerAuthorizationCode": "133235",
  • "card": {
    }
}

Increase the authorized amount of a transaction

Use this API to increase the authorized amount for a transaction. The transaction must be in status authorized. The transactionId is needed to increase the amount for an authorization. Only credit cards support increase of the authorized amount.

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after an authorization.

Request Body schema: application/json
required

Increase authorization amount

amount
required
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

refno
required
string [ 1 .. 40 ] characters

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

Responses

Request samples

Content type
application/json

authorizeIncreaseRequest

{
  • "amount": 1000,
  • "currency": "GBP",
  • "refno": "Hln8J5Lhu"
}

Response samples

Content type
application/json

authorizeIncreaseResponse

{
  • "increasedAmount": 2000
}

Screen the customer details

Check the customer's credit score before sending an actual authorization request. No amount will be blocked on the customers account. Currently, only invoicing method INT support screening.

Authorizations:
Basic
Request Body schema: application/json
required

Screen request

amount
required
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

refno
required
string [ 1 .. 40 ] characters

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

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 (ByjunoScreenRequest)
object (MfaAuthorizeScreenRequest)

MFA has no specific request parameters but we need an empty object here to handle it as a MFA request.

DVI
object (DeltaVistaScreenRequest)

DVI has no specific request parameters but we need an empty object here to handle it as a DVI request.

Responses

Request samples

Content type
application/json

screenRequest

{
  • "amount": 2000,
  • "currency": "CHF",
  • "refno": "29GKih2x3",
  • "customer": {
    },
  • "INT": {
    }
}

Response samples

Content type
application/json

screenResponse

{
  • "transactionId": "240418133230647681",
  • "INT": {
    }
}

Settle a transaction

The Settlement request is often also referred to as “Capture” or “Clearing”. It can be used for the settlement of previously authorized transactions. Only after settling a transaction the funds will be credited to your bank account. The transactionId is needed to settle an authorization. This API call is not needed if autoSettle was set to true when initializing a transaction.

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after an authorization.

Request Body schema: application/json
required
amount
required
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

refno
required
string [ 1 .. 40 ] characters

The merchant's reference number. Most payment methods require you to have a unique reference for a transaction. In case you must change the reference number in settlement, ensure first it is supported by the dedicated payment method.

refno2
string [ 0 .. 40 ] characters

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

object (AirlineDataRequest)

The airline data including ticket details.

object (MarketPlaceSettle)
object (SettleMcpRequest)
object (MultiplePartialCapture)

Can be used to do the settlement in partial steps.

extensions
object (Extension)

An object for additional data for customized processes.

Responses

Request samples

Content type
application/json

settleRequest1

{
  • "amount": 1000,
  • "currency": "CHF",
  • "refno": "PTP3WH91C"
}

Response samples

Content type
application/json

settleErrorResponse

{
  • "error": {
    }
}

Cancel a transaction

Cancel requests can be used to release a blocked amount from an authorization. The transaction must either be in status authorized or settled. The transactionId is needed to cancel an authorization

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after an authorization.

Request Body schema: application/json
object (CancelRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json

cancelErrorResponse

{
  • "error": {
    }
}

Refund a transaction

Refund requests can be used to credit a transaction which is in status settled or transmitted. The previously settled amount must not be exceeded.

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after an authorization.

Request Body schema: application/json
required

Credit a transaction

amount
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

refno
required
string [ 1 .. 40 ] characters

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

refno2
string [ 0 .. 40 ] characters

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

object (MarketPlaceCredit)
extensions
object (Extension)

An object for additional data for customized processes.

object (CreditMcpRequest)
object (SBBHalbtaxPlusCreditRequest)

SBB Halbtax Plus specific parameters for credit

Responses

Request samples

Content type
application/json

creditRequest

{
  • "amount": 1000,
  • "currency": "CHF",
  • "refno": "1ESaLKgtR"
}

Response samples

Content type
application/json

authorizeResponse

{
  • "transactionId": "240418133230757685",
  • "acquirerAuthorizationCode": "133230"
}

Update the amount of a Secure Fields transaction

Use this API to update the amount of a Secure Fields transaction. This action is only allowed before the 3D process. At least one property must be updated.

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received from the Initialize a Secure Fields transaction call

Request Body schema: application/json
required
amount
integer <int64>

The newly to be used amount in the currency’s smallest unit. For example use 1000 for CHF 10.00.

currency
required
string = 3 characters

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

Responses

Request samples

Content type
application/json

secureFieldsUpdateRequest

{
  • "amount": 1338
}

Response samples

Content type
application/json

secureFieldsUpdateErrorResponse

{
  • "error": {
    }
}

Checking the status of a transaction

The API endpoint status can be used to check the status of any transaction, see its history, and retrieve the card information.

Authorizations:
Basic
path Parameters
transactionId
required
integer <int64>

The transactionId received after an authorization.

Responses

Request samples 

curl -i -X GET https://api.sandbox.datatrans.com/v1/transactions/240418133234737752 \
	--user {merchantId}:{password} \

Response samples

Content type
application/json

statusResponse

{
  • "transactionId": "240418133234737752",
  • "merchantId": "1000001111",
  • "type": "payment",
  • "status": "authorized",
  • "currency": "CHF",
  • "refno": "ARkuKk3T4",
  • "paymentMethod": "VIS",
  • "detail": {
    },
  • "card": {
    },
  • "history": [
    ]
}

Initialize a Secure Fields tokenization

Authorizations:
Basic
header Parameters
client-name
string
Enum: "ANDROID_SDK" "IOS_SDK" "LINK"
Request Body schema: application/json
required
object (CardholderData)
object (ApplePaySettings)
object (GooglePaySettings)

Responses

Request samples

Content type
application/json
{
  • "cardholder": {
    },
  • "applePay": {
    },
  • "googlePay": {
    }
}

Response samples

Content type
application/json
{
  • "transactionId": "string"
}

/v1/aliases

The aliases API gives you complete control over a Datatrans alias, be it a card number alias or an alias of a non-card payment method such as PayPal, Postfinance etc.

Note that the operations of this API apply only to the most recent Datatrans alias format. Please reach out to support@datatrans.ch if you are not sure which alias format you have in use.

Alias access

By default, only the merchant that created the alias has access to it. Contact us, if you have a use case where you need to share the alias.

Get alias info

Get alias info.

Authorizations:
Basic
path Parameters
alias
required
string
Example: AAABeCBPbiHssdexyrAAAYkaznYWAPYt

An alias (token) received from a previous transaction if option.createAlias was set to true. In order to retrieve the alias from a previous transaction, use the Status API.

https://docs.datatrans.ch/docs/tokenization#section-token-format

Responses

Request samples 

curl -i -X GET https://api.sandbox.datatrans.com/v1/aliases/7LHXscqwAAEAAAGO8PqTVHdGoTaCAH6f \
	--user {merchantId}:{password} \

Response samples

Content type
application/json

aliasInfoResponse

{
  • "alias": "7LHXscqwAAEAAAGO8PqTVHdGoTaCAH6f",
  • "fingerprint": "F-e5-sH1dWRS1onhDWSmmIgP",
  • "type": "CARD",
  • "masked": "424242xxxxxx4242",
  • "dateCreated": "2024-04-18T11:32:17Z",
  • "card": {
    }
}

Delete alias

Delete an alias with immediate effect. The alias will no longer be recognized if used later with any API call.

Authorizations:
Basic
path Parameters
alias
required
string
Example: AAABeCBPbiHssdexyrAAAYkaznYWAPYt

An alias (token) received from a previous transaction if option.createAlias was set to true. In order to retrieve the alias from a previous transaction, use the Status API.

https://docs.datatrans.ch/docs/tokenization#section-token-format

Responses

Request samples 

curl -i -X DELETE https://api.sandbox.datatrans.com/v1/aliases/7LHXscqwAAEAAAGO8PqZdbWFDCZEALEB \
	--user {merchantId}:{password} \

Response samples

Content type
application/json

deleteErrorResponse

{
  • "error": {
    }
}

Patch alias

Update an existing card alias with expiration year and month.

Authorizations:
Basic
path Parameters
alias
required
string
Request Body schema: application/json
required
removePlain
boolean

Remove the pan from storage.

expiryMonth
string = 2 characters \d{2}

The expiry month of the card.

expiryYear
string = 2 characters \d{2}

The expiry year of card.

object (CardholderData)

Responses

Request samples

Content type
application/json

aliasPatchRequest

{
  • "removePlain": false,
  • "expiryMonth": "05",
  • "expiryYear": "25"
}

Response samples

Content type
application/json

aliasPatchResponse

{
  • "alias": "7LHXscqwAAEAAAGO8PqS7CdT9OfHAEhU",
  • "fingerprint": "F-fnlcOgqPqxSdNfyYY0vXHk",
  • "type": "CARD",
  • "masked": "434343xxxxxx4345",
  • "dateCreated": "2024-04-18T11:32:17Z",
  • "card": {
    }
}

Convert alias

Currently, only credit card aliases can be converted.

Authorizations:
Basic
Request Body schema: application/json
required
expiryMonth
string = 2 characters \d{2}

The expiry month of the credit card behind alias.

expiryYear
string = 2 characters \d{2}

The expiry year of the credit card behind the alias

legacyAlias
required
string

The legacy alias

type
string

Legacy alias type.

Responses

Request samples

Content type
application/json

aliasConvertRequest

{
  • "legacyAlias": "424242SKMPRI4242",
  • "type": "CARD"
}

Response samples

Content type
application/json

aliasConvertResponse

{
  • "alias": "7LHXscqwAAEAAAGO8PqWn9pEjhfLAH_i"
}

Vault API: Bulk tokenization

Tokenize cards, CVVs and custom fields. It supports single and bulk tokenization for batches of requests.

Authorizations:
Basic
Request Body schema: application/json
required
required
Array of objects (TokenizeRequest)

List of tokenization requests.

Responses

Request samples

Content type
application/json

bulkTokenizeRequest

{
  • "requests": [
    ]
}

Response samples

Content type
application/json

bulkTokenizationResponse

{
  • "overview": {
    },
  • "responses": [
    ]
}

Vault API: Bulk detokenization

Detokenize cards, CVVs and custom fields. It supports single and bulk detokenization for batches of requests.

Authorizations:
Basic
Request Body schema: application/json
required
required
Array of objects (DetokenizeRequest)

List of detokenization requests.

Responses

Request samples

Content type
application/json

bulkDetokenizeRequest

{
  • "requests": [
    ]
}

Response samples

Content type
application/json

bulkTokenizationResponse

{
  • "overview": {
    },
  • "responses": [
    ]
}

/v1/reconciliations

Report a sale

If you are a merchant using our reconciliation services, you can use this API to confirm a sale. The matching is based on the transactionId. The status of the transaction will change to compensated

Authorizations:
Basic
Request Body schema: application/json
required
date
string <date-time>

The date when the transaction happened.

transactionId
string

The transactionId received after an authorization.

currency
string

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

amount
integer <int64>

The amount of the transaction in the currency’s smallest unit. For example use 1000 for CHF 10.00.

type
string
Enum: "payment" "credit" "card_check"

The type of the transaction

refno
string

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

Responses

Request samples

Content type
application/json

saleReportRequest

{
  • "date": "2024-04-18T11:32:36.443+00:00",
  • "transactionId": "240418133234657749",
  • "currency": "CHF",
  • "amount": 1000,
  • "type": "payment",
  • "refno": "MaiZYunPZ"
}

Response samples

Content type
application/json

saleReportResponse

{
  • "transactionId": "240418133234657749",
  • "saleDate": "2024-04-18T11:32:36.443+00:00",
  • "reportedDate": "2024-04-18T11:32:36.555+00:00",
  • "matchResult": "MATCHED"
}

Bulk reporting of sales

If you are a merchant using our reconciliation services, you can use this API to confirm multiple sales with a single API call. The matching is based on the transactionId. The status of the transaction will change to compensated

Authorizations:
Basic
Request Body schema: application/json
required
Array of objects (SaleReportRequest)

A list of sale objects.

Responses

Request samples

Content type
application/json

bulkSaleRequest

{
  • "sales": [
    ]
}

Response samples

Content type
application/json

bulkSaleResponse

{
  • "sales": [
    ]
}

/v1/multicurrency

Get conversion rates for different currencies

To get current rates call this endpoint. It will return all available rates for the configured merchant. Note: These rates are Acquirer specific, need a specific acquiring contract and need to be set up by Datatrans.

Authorizations:
Basic

Responses

Request samples 

curl -i -X GET https://api.sandbox.datatrans.com/v1/multicurrency/rates \
	--user {merchantId}:{password} \

Response samples

Content type
application/json

authorizeResponse

{
  • "requestId": "6de49e4b-0483-4e1a-bebc-fac820599d4a",
  • "reportDetail": {
    },
  • "rates": [
    ]
}