This page contains an explanation of our API endpoints. Please refer to our API reference for more information on each endpoint. For production, you may simply remove the .sandbox part of the URLs.

📘
basicAuth credentials & TLS 1.2
Your basicAuth settings can be found in your merchantId configuration within the tab security. Depending on your account setup, you may need to send your calls to a different merchantId depending on which API endpoint you are trying to call. Usually one merchantId is dedicated to customer-initiated transactions and another to merchant-initiated transactions.
Please make sure to always use TLS version 1.2 when interacting with our endpoints.

API Endpoint	URL
Redirect URL	`https://pay.sandbox.datatrans.com/v1/start/{{transactionId}}`
init	`https://api.sandbox.datatrans.com/v1/transactions`
secureFieldsInit	`https://api.sandbox.datatrans.com/v1/transactions/secureFields`
authorize	`https://api.sandbox.datatrans.com/v1/transactions/authorize`
authorize-split	`https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/authorize`
validate	`https://api.sandbox.datatrans.com/v1/transactions/validate`
settle	`https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/settle`
cancel	`https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/cancel`
refund	`https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/credit`
status	`https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}`
health-check	`https://api.sandbox.datatrans.com/upp/check`

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.

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.

curl 'https://api.sandbox.datatrans.com/v1/transactions/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: {idempotencyKey}' \
--data-raw '{
	"currency" : "CHF",
	"refno" : "Test-1234",
	"amount" : 1000
}'

init

To use either the Redirect or Lightbox integration, you will need to initialize a transaction first. Call our init endpoint with your desired parameters and we'll return a transactionId ready to be used with our Redirect or Lightbox. Please note that a transactionId is only valid for 30 minutes. More information on the Redirect & Lightbox integration can be found here.

curl 'https://api.sandbox.datatrans.com/v1/transactions' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"refno": "Test-1234",
	"amount": 1000,
	"paymentMethods": ["VIS","ECA","PAP,"TWI"],
	"autoSettle": true,
	"option": {
		"createAlias": true
	},
	"redirect": {
		"successUrl": "{successUrl}",
		"cancelUrl": "{cancelUrl}",
		"errorUrl": "{errorUrl}"
	},
	"theme": {
		"name": "DT2015",
		"configuration": {
			"brandColor": "#FFFFFF",
			"logoBorderColor": "#A1A1A1",
			"brandButton": "#A1A1A1",
			"payButtonTextColor": "#FFFFFF",
			"logoSrc": "{svg}",
			"logoType": "circle",
			"initialView": "list",
		}
	}
}

{
	"transactionId": "{transactionId}"
	"3D": {
		"enrolled": true
	}
}

secureFieldsInit

To create a payment with Secure Fields, you will need to initialize a transactionId. Call our secureFieldsInit endpoint with your desired parameters and we'll return a transaction identifier ready to be used with our Secure Fields. The parameter returnUrl specifies where the browser should be redirected to after a 3D Secure authentication. Please note that a transactionId is only valid for 30 minutes. If you wish to do a dedicated registration, you must omit the parameter amount. Please read our section saving payment information for more details. More information on the Secure Fields integration can be found here.

curl 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"amount": 100,
	"returnUrl": "{returnUrl}"
}'

{
    "transactionId": "{transactionId}"
}

authorize

The API endpoint authorize can be called to do merchant initiated transactions. If you wish to do merchant initiated transactions, you will first have to save your customers' payment details with a customer-initiated transaction. Please read our section saving payment information for more details. More information on merchant initiated payments can be found here.

curl 'https://api.sandbox.datatrans.com/v1/transactions/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"refno": "Test-1234",
	"amount": 100,
	"card": {
		"alias": "424242SKMPRI42423",
		"expiryMonth": 12,
		"expiryYear": 21
	},
	"autoSettle": false
}'

{
	"transactionId": "{transactionId}",
	"acquirerAuthorizationCode": "172105",
	"card": {
		"masked": "424242xxxxxx4242"
	}
}

authorize-split

The API endpoint authorize-split can be used to authorize a previously authenticated transaction. This request type is required for Secure Fields transactions. More information on the Secure Fields integration can be found here.

curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"refno": "Test-1234",
	"amount": 100,
	"autoSettle": true
}'

{
	"acquirerAuthorizationCode": "172115"
}

validate

The API endpoint validate can be used to validate an existing alias at any time. No amount will be blocked on the customers account. Only credit cards, Apple Pay, Google Pay, PostFinance Card, Klarna and PayPal support validation of an existing alias.

curl 'https://api.sandbox.datatrans.com/v1/transactions/validate' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "refno": "Test-1234",
    "card": {
        "alias": "{cardAlias}",
        "expiryMonth": "12",
        "expiryYear": "21"
    }
}'

{
	"transactionId": "{transactionId}",
	"acquirerAuthorizationCode": "172052",
	"card": {
		"masked": "424242xxxxxx4242"
	}
}

settle

The API endpoint settle can be used to settle an authorized transaction. More information on Deferred Settlements can be found here.

curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/settle' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"currency": "CHF",
	"amount": 100,
	"refno": "Test-1234-settled"
}'

We respond with an HTTP status 204 if the transaction was successfully settled.

cancel

The API endpoint cancel can be used to cancel an authorized transaction.

curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/cancel' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"refno": "Test-1234-cancelled"
}'

We respond with an HTTP status 204 if the transaction was successfully canceled.

refund

The API endpoint refund can be used to refund a transaction. Refund requests create a new transactionId.

curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/credit' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"amount": 100,
	"currency": "CHF",
	"refno": "Test-1234-credit"
}'

{
	"transactionId": "{transactionId}",
	"acquirerAuthorizationCode": "172051"
}

status

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

curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json'

{
	"transactionId": "{transactionId}",
	"type": "payment",
	"status": "authorized",
	"currency": "CHF",
	"refno": "Yhhnse53e",
	"paymentMethod": "VIS",
	"detail": {
		"authorize": {
		"amount": 1000,
		"acquirerAuthorizationCode": "172053"
		}
	},
	"receiptUrl": "{receiptUrl}",
	"card": {
		"masked": "424242xxxxxx4242",
		"expiryMonth": "12",
		"expiryYear": "21",
		"info": {
			"brand": "VISA CREDIT",
			"type": "credit",
			"usage": "consumer",
			"country": "GB",
			"issuer": "DATATRANS"
		}
	},
	"history": [
    {
      "action": "authorize",
      "amount": 1000,
      "source": "api",
      "date": "YYYY-MM-DDT15:20:53Z",
      "success": true,
      "ip": "{{ip}}"
    },
    {
      "action": "settle",
      "amount": 1000,
      "source": "api",
      "date": "YYYY-MM-DDT07:54:01Z",
      "success": true,
      "ip": "{{ip}}"
    }
	]
}

health-check

health-check returns the status of our payment platform. Please bear in mind that third-party systems are not included in this check. If our platform is operational we will return a status 200 and the string ok.

curl 'https://api.sandbox.datatrans.com/upp/check'

API Endpoints

📘
basicAuth credentials & TLS 1.2

Idempotency

init

secureFieldsInit

authorize

authorize-split

validate

settle

cancel

refund

status

health-check

📘basicAuth credentials & TLS 1.2

Idempotency

init

secureFieldsInit

authorize

authorize-split

validate

settle

cancel

refund

status

health-check

📘
basicAuth credentials & TLS 1.2