The developer.datatrans.com Developer Hub

Welcome to the developer.datatrans.com developer hub. You'll find comprehensive guides and documentation to help you start working with developer.datatrans.com as quickly as possible, as well as support if you get stuck. Let's jump right in!

API Endpoints

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

credit-authorize

https://api.sandbox.datatrans.com/v1/transactions/credit

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

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 MTEwMDAxNzA2MzpoUm1GOVIyYjRaMEZtUG50' \
--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 settled.

credit-authorize

The API endpoint credit can be used to credit a cardholder without a previous debit. Please refer to our endpoint refund if you wish to refund transactions. Credit requests create a new transactionId.

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

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' 

Updated about a month ago

API Endpoints


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.