Datatrans logo
API docs by Redocly

Datatrans API Reference (2.0.54)

Download OpenAPI specification:

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: 08.01.26 - 15:58 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.54 - 08.01.2026

  • fixed Klarna birthdate format
  • fixed logo path on API documentation page

2.0.53 - 02.12.2025

  • added token support for PLU on Cancel API
  • added new fields on MF Group QrData property
  • improved the error messages

2.0.52 - 13.11.2025

  • improved eDCC support (new process with correlation-id)
  • added support for account funding transactions (accountFunding)
  • added new 3RI flows (unknown final amount)
  • improved error mapping

2.0.51 - 04.09.2025

  • added Postfinance Pay (PFP)
  • added 3D property in authorize api for network tokens
  • improved the order of properties in the api documentation

2.0.50 - 08.07.2025

  • add support for Klarna EMD (extra merchant data) for AirReservationDetails, Vouchers and OtherDeliveryAddresses

2.0.49 - 31.03.2025

  • updated Byjuno to the CembraPay API
  • added MPX to the authorize api
  • added alias expiration to tokenize/detokenize API
  • return 3D object in init response for type ALIAS requests
  • various bugfixes

2.0.48 - 12.11.2024

  • added new DCC endpoint to fetch DCC options for a specific card, currency and amount
  • extended the authorize and initialize APIs to be able to receive a DCC option
  • bugfix: added MFG to the status API.
  • QR bill data has been added to MFG

2.0.47 - 17.09.2024

  • added new feature for manual card on file processing
    • added cardOnFile property to the init, authorize and validate api
    • this feature needs to be enabled by Datatrans for the merchant
  • added documentation of PLU parameters
  • improved the 3D authentication response description (card.3D.authenticationResponse)

2.0.46 - 29.08.2024

  • added new endpoint Get alias card art

2.0.45 - 02.07.2024

  • improved documentation of 3D params
  • update underlying JSON library
  • minor fixes

2.0.44 - 16.05.2024

  • added card.type feature to the INIT API (same as for the AUTHORIZE API)
  • added support for plain GooglePay and ApplePay device tokens (INIT and AUTHORIZE API)
  • fixed the provided openapi specification (there were issues when creating a client from it)
  • added interim support for GiroPay 2.0

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

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

Whenever the payment method supports customer details, the customer object can be used. The required fields may vary depending on the payment method. For example, in some cases the field birthDate is mandatory.

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.

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

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

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

object (WebhookRequest)

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

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" "PFP" "PYL"

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

Alipay+ specific parameters

object (AmazonPayRequest)

Amazon Pay specific request parameters

object (BoncardRequest)

Boncard specific request parameters

DVI
object (DeltaVistaData)

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

object (ElvInitRequest)

ELV specific payment parameters.

object (EpsRequest)

EPS specific request parameters

object (ESY)
object (GPARequest)

Giropay specific request parameters

object (ByjunoAuthorizeRequest)
object (KlarnaInitRequest)
object (MobilePayRequest)

MobilePay specific parameters

object (MDPInitRequest)
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 (MFXRequest)

MFX specific parameters

object (MPXRequest)

MPX specific parameters

object (PayPalInitRequest)

PayPal specific parameters

object (PfcInitRequest)
object (PostfinancePayInitRequest)
object (SBBHalbtaxPlusInitRequest)
object (PaysafecardRequest)

Paysafecard specific request parameters

object (RekaRequest)

Reka card specific parameters

object (SwissBillingRequest)

Swissbilling specific parameters.

object (SwishRequest)

Swish specific parameters

object (SwissPassRequest)

SwissPass specific parameters

object (TwintInitRequest)
object (VippsRequest)

Vipps specific parameters

object (WeChatRequest)

WeChat specific parameters

object (DccInitRequest)

For DCC data obtained from a previous DCC request for a given credit card, currency, and amount, use correlationId. Otherwise, for DCC data obtained from external sources, provide currency, amount, and rate. If DCC data is supplied, the payment page will bypass the DCC selection view and proceed directly to the 3D Secure process. Authorization will use the provided DCC data. If credit card details were used when obtaining the DCC data, they must also be provided.

object (InitMcpRequest)
object (Metadata)

Merchant reference data

object (AirlineDataRequest)

The airline data including ticket details.

accertify
object (Accertify)

Accertify decision (Accepted, Review, Declined

object (ThreeRIData)
extensions
object (Extension)

An object for additional data for customized processes.

Responses

Request samples

Content type
application/json
Example

Response samples

Content type
application/json

initResponse

{
  • "transactionId": "260108170006704540"
}

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
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 [ 1 .. 4000 ] characters

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

returnMethod
string
Default: "POST"
Enum: "GET" "POST"

The preferred HTTP method for the redirect request (GET or POST).

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": "260108170007654574"
}

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
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.

refno2
string [ 0 .. 40 ] characters

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

object (CustomerRequest)

Whenever the payment method supports customer details, the customer object can be used. The required fields may vary depending on the payment method. For example, in some cases the field birthDate is mandatory.

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.

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

Accarda specific request parameters.

object (AlipayRequest)

Alipay+ specific parameters

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

Boncard specific request parameters

DVI
object (DeltaVistaData)

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

object (ElvRequest)

ELV specific request parameters.

object (ESY)
object (ByjunoAuthorizeRequest)
object (KlarnaAuthorizeRequest)
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 (MfgAuthorizeRequest)

MFG specific parameters.

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

MPX specific parameters

object (PayPalAuthorizeRequest)
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 (PfcAuthorizeRequest)
object (PostfinancePayAuthorizationRequest)
object (SBBHalbtaxPlusAuthorizeRequest)
object (RekaRequest)

Reka card specific parameters

object (SwissBillingAuthorizeRequest)
object (SwissPassRequest)

SwissPass specific parameters

object (TwintAuthorizeRequest)
object (DccAuthorizeRequest)

For DCC data obtained from a previous DCC request for a given credit card, currency, and amount, use correlationId. Otherwise, for DCC data obtained from external sources, provide currency, amount, and rate. If credit card details were used when obtaining the DCC data, they must also be provided.

object (AuthorizeMcpRequest)
object (Metadata)

Merchant reference data

object (AirlineDataRequest)

The airline data including ticket details.

accertify
object (Accertify)

Accertify decision (Accepted, Review, Declined

object (ThreeRIData)
extensions
object (Extension)

An object for additional data for customized processes.

object (MarketPlaceAuthorize)
object (ThreeRI)

3RI specific parameters

Responses

Request samples

Content type
application/json
Example

authorizeRequest1

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

Response samples

Content type
application/json

authorizeResponse

{
  • "transactionId": "260108170007304565",
  • "acquirerAuthorizationCode": "170007",
  • "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": "xt6ZNiX3F"
}

Response samples

Content type
application/json

authorizeSplitResponse

{
  • "acquirerAuthorizationCode": "170022"
}

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": "3sZwO2Ce7",
  • "currency": "CHF",
  • "card": {
    }
}

Response samples

Content type
application/json

validateResponse

{
  • "transactionId": "260108170009414641",
  • "acquirerAuthorizationCode": "170009",
  • "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.

object (Metadata)

Merchant reference data

Responses

Request samples

Content type
application/json

authorizeIncreaseRequest

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

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. The required fields may vary depending on the payment method. For example, in some cases the field birthDate is mandatory.

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": "axQDEtvOj",
  • "customer": {
    },
  • "INT": {
    }
}

Response samples

Content type
application/json

screenResponse

{
  • "transactionId": "260108170014084799",
  • "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.

object (SBBHalbtaxPlusSettleRequest)

SBB Halbtax Plus specific parameters for settle

object (OrderRequest)

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

Responses

Request samples

Content type
application/json

settleRequest1

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

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

SBB Halbtax Plus specific parameters for cancel

Responses

Request samples

Content type
application/json
{
  • "PLU": {
    }
}

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

The airline data including ticket details.

object (MarketPlaceCredit)
extensions
object (Extension)

An object for additional data for customized processes.

object (CreditMcpRequest)
object (SBBHalbtaxPlusCreditRequest)

SBB Halbtax Plus specific parameters for credit

object (Metadata)

Merchant reference data

object (OrderRequest)

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

Responses

Request samples

Content type
application/json

creditRequest

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

Response samples

Content type
application/json

authorizeResponse

{
  • "transactionId": "260108170006234526",
  • "acquirerAuthorizationCode": "170006"
}

Get DCC values for a given credit card and currency.

Returns the DCC values for a given credit card, currency and amount. This data can be used to create a DCC UI for the customers. The received DCC correlation ID can be used in a sub sequent transaction either through the initialize or the authorize API endpoints.

Authorizations:
Basic
Request Body schema: application/json
required
cardNumber
required
string

Merchants that have the option to store card information on their end can use the number property instead of alias. Please note that this option is only available to merchants that fulfill the requirements by PCI DSS to store sensitive information on their side and only upon request.

currency
required
string = 3 characters

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

amount
required
integer <int64>

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

Responses

Request samples

Content type
application/json

dccRequest

{
  • "cardNumber": "5232050000010003",
  • "currency": "CHF",
  • "amount": 100
}

Response samples

Content type
application/json

dccResponse

{
  • "dccAvailable": true,
  • "originalOption": {
    },
  • "dccOption": {
    },
  • "baseRate": "wholesale",
  • "rate": 1.06015,
  • "margin": 2.97,
  • "correlationId": "ecb37255-5ab8-4b84-9250-4338b7fae97f"
}

Update a Secure Fields transaction

Use this API to update 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

object (SecureFieldsThreeDSecure)

Refer to the official EMVCo. specifications for parameter requirements.

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/260108170009044622 
	--user {merchantId}:{password}

Response samples

Content type
application/json

statusResponse

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

Initialize a Secure Fields tokenization

Authorizations:
Basic
Request Body schema: application/json
required
object (CardholderData)
usage
string
Enum: "SIMPLE" "REGISTRATION"
object (ApplePaySettings)
object (GooglePaySettings)

Responses

Request samples

Content type
application/json
{
  • "cardholder": {
    },
  • "usage": "SIMPLE",
  • "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/AFBWv1fWAAEAAAGbnlX3ky-WPhLaACIG 
	--user {merchantId}:{password}

Response samples

Content type
application/json

aliasInfoResponse

{
  • "alias": "AFBWv1fWAAEAAAGbnlX3ky-WPhLaACIG",
  • "fingerprint": "F-e5-sH1dWRS1onhDWSmmIgP",
  • "type": "CARD",
  • "masked": "424242xxxxxx4242",
  • "dateCreated": "2026-01-08T16:00:00Z",
  • "validUntil": "2030-12-13T16:00:00Z",
  • "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/AFBWv1fWAAEAAAGbnlYLrV4hI84FAPqZ 
	--user {merchantId}:{password}

Response samples

Content type
application/json

deleteErrorResponse

{
  • "error": {
    }
}

Patch alias

Update existing aliases and provision Network Tokens.

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)
createNetworkToken
boolean

Create a Network Token.

object (CardOnFile)

Card On File

object (CardHolderNameVerification)

Cardholder name

Responses

Request samples

Content type
application/json

aliasPatchRequest

{
  • "removePlain": false,
  • "expiryMonth": "12",
  • "expiryYear": "30",
  • "createNetworkToken": true
}

Response samples

Content type
application/json

aliasPatchResponse

{
  • "alias": "AFBWv1fWAAEAAAGbnlYbAeYQB1D8AGWa",
  • "fingerprint": "F-fnlcOgqPqxSdNfyYY0vXHk",
  • "type": "CARD",
  • "masked": "434343xxxxxx4345",
  • "dateCreated": "2026-01-08T16:00:00Z",
  • "validUntil": "2030-12-13T16:00:00Z",
  • "card": {
    }
}

Convert alias

Currently, only Card, PostFinance, Twint, PayPal, Byjuno and Reka aliases can be converted.

Authorizations:
Basic
Request Body schema: application/json
required
type
required
string
Default: "CARD"

Legacy alias type.

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

Responses

Request samples

Content type
application/json

aliasConvertRequest

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

Response samples

Content type
application/json

aliasConvertResponse

{
  • "alias": "AFBWv1fWAAEAAAGbnlYK-sUuBIsxAHMb"
}

Tokenize

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": [
    ]
}

Detokenize

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": [
    ]
}

Get alias card art

Receive card assets such as the image of the card. Works only when a Network Token is mapped to the alias.

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/AFBWv1fWAAEAAAGbnlYZs_85Lho3AGdY/card-art 
	--user {merchantId}:{password}

Response samples

Content type
application/json

aliasCardArtResponse

{
  • "mimeType": "image/png",
  • "encodedData": "encoded data"
}

/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": "2026-01-08T16:00:10.590+00:00",
  • "transactionId": "260108170009884659",
  • "currency": "CHF",
  • "amount": 1000,
  • "type": "payment",
  • "refno": "Cu9WA5nSB"
}

Response samples

Content type
application/json

saleReportResponse

{
  • "transactionId": "260108170009884659",
  • "saleDate": "2026-01-08T16:00:10.590+00:00",
  • "reportedDate": "2026-01-08T16:00:10.692+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": "58ea4f7f-cc99-4136-98af-c1497ac5bb16",
  • "reportDetail": {
    },
  • "rates": [
    ]
}