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!

Redirect & Lightbox

Redirect your customer's payments to our payment pages and shift any developments related to third-party providers to our gateway. We take care of all the necessary redirects. After a transaction has been completed we redirect your customer to your defined success, cancel, or error URL. We also inform your webhook with all necessary information from the transaction, including the saved card information. Besides a full redirect, we also allow you to show our payment pages as an overlay on your website. This overlay method is called Lightbox and helps you keep your UI in the background. Test both solutions by clicking the button below.

Initializing Transactions

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.

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"]
}'

Redirect Integration

Redirect your customers to our payment pages by adding the returned transactionId to the redirect URL. The complete redirect link is also returned in the response header Location. We'll take care of the rest.

https://pay.sandbox.datatrans.com/v1/start/{{transactionId}}

Lightbox Integration

The Lighbox displays an iframe on top of your UI. To use the Lightbox, you will have to load our JavaScript library and call the startPayment function with the transactionId. Using our Lightbox on a smartphone automatically loads the payment pages in fullscreen. Please always load our latest JavaScript library, as specified in our API reference.

<script src="https://pay.sandbox.datatrans.com/upp/payment/js/datatrans-2.0.0.js">

There are 4 optional callbacks you can invoke with our lightbox integration.

  • opened | function(): Triggered when the payment form is opened.
  • loaded | function(): Triggered when the payment form is loaded.
  • closed | function(): Triggered when the payment form is closed.
  • error | function(errorData): Triggered if an error occurred during the initial request. errorData.message contains the actual error message. errorData.detail contains the details of the error. If no details are available, null will be returned.

errorData is not related to the authorization status

Please note that this callback is only triggered if the initial request to Datatrans resulted in an error. This is the case if you sent invalid parameters, such as an invalid merchantId. This callback is not triggered if the authorization resulted in an error.

payButton.onclick = function() {
  Datatrans.startPayment({
    transactionId:  "{{transactionId}}",
    'opened': function() {console.log('payment-form opened');},
    'loaded': function() {console.log('payment-form loaded');},
    'closed': function() {console.log('payment-page closed');},
    'error': function() {console.log('error');}
  });
};

Auto Settlements

Settle your transactions automatically or in two steps with the parameter autoSettle. If you do not specify anything in your init request, your transactions will not be settled automatically. Please refer to the section settling a transaction for more information on deferred settlements and the related server to server request.

"autoSettle": true

Saving Payment Information

Save card or payment method details after your customer has finalized her payment or registration. Not all payment methods support a registration with a payment. Please refer to our tokenization overview to see which payment methods require a dedicated registration. Please also read our section saving payment information for more details.

"amount": 1000,	// Omit the parameter amount for dedicated registrations
"option": {
	"createAlias": true	// Required to save a card
}

Selection of Payment Methods

Our solutions let you choose whether you want to do the payment method selection on your UI or on our payment forms. By default, we display all available payment methods in your merchant's configuration. If you do the preselection on your end, simply send the array paymentMethods including only one payment method to redirect to the final payment screen of that specific payment method. If you wish to have multiple payment methods on our payment pages, you can simply extend the array with further payment methods.

"paymentMethods": ["VIS","ECA","PAP","TWI"]

Redirect Settings

For each of your transactions, you can tell us where we should redirect your customers in case of a success, a cancel, or an error. We have three parameters you can define for this. The successUrl, cancelUrl, and errorUrl can be set in the object redirect. You can also define the HTTP method for the redirect. When using GET as a method, the parameter datatransTrxId will be added to the URL upon redirection. When using POST, all parameters will be moved to the body of the redirect request along with the parameter datatransTrxId.

"redirect": {
	"successUrl": "{{successUrl}}",
	"cancelUrl": "{{cancelUrl}}",
	"errorUrl": "{{errorUrl}}",
	"method": "GET"
}

Styling the Payment Pages

Apply your corporate design to our payment pages with the object theme. Customize the header, the pay button, the logo, and more. The correct value for the parameter logoSrc is the name you specified for your uploaded svg file in our merchant administration portal.

"theme": {
	"name": "DT2015",  // Leave this as a default
	"configuration": {
		"brandColor": "#FFFFFF",	 // Base color
		"logoBorderColor": "#A1A1A1",	 // Border color around your logo
		"brandButton": "#A1A1A1",	 // Background color for the pay button
		"payButtonTextColor": "#FFFFFF", // Color for the text on pay button
		"logoSrc": "{{svg}}",		 // Source SVG for your logo
		"logoType": "circle",		 // Format of your logo on payment pages
		"initialView": "circle",	 // Listing method of payment methods
    
		// Only required if no logo is used:
		"brandTitle": "false"		 // Hides the title from header
		"textColor": "black",		 // Color for the title [white|black]
	}
}

Complete Example

Here's an init example including all options discussed on this page. Send only the required parameters to our API to make your life as a developer easier.

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",
		}
	}
}

Webhook

After any transaction that was processed via our Redirect or Lightbox integration, we will call your webhook with all relevant transaction information. You can define your webhook URL within your merchant configuration. You can choose among two options to call your webhook.

  • Synchronous: You have the option to redirect the customer to the success, error or cancel URL only after our call to your webhook delivered a response. This is the default behaviour.
  • Asynchronous: You have the option to redirect the customer to the success, error or cancel URL regardless of what happens with our webhook call.

Contact us if you require an asynchronous setup

Please contact us if you require an asynchronous setup of your merchant's webhook. This can only be changed by our support team.

{
  "transactionId" : "{{transactionId}}",
  "type" : "payment",
  "status" : "authorized",
  "currency" : "CHF",
  "refno" : "Test-1234",
  "paymentMethod" : "ECA",
  "detail" : {
    "authorize" : {
      "amount" : 1000,
      "acquirerAuthorizationCode" : "113009"
    }
  },
  "customer" : {
    "firstName" : "Test",
    "lastName" : "Test"
  },
  "card" : {
    "alias" : "{{cardAlias}}",
    "masked" : "520000xxxxxx0007",
    "expiryMonth" : "12",
    "expiryYear" : "29",
    "info" : {
      "brand" : "MCI CREDIT",
      "type" : "credit",
      "usage" : "consumer",
      "country" : "MY",
      "issuer" : "DATATRANS"
    },
    "3D" : {
      "authenticationResponse" : "D"
    }
  },
  "history" : [ {
    "action" : "init",
    "amount" : 1000,
    "source" : "api",
    "date" : "20XX-09-14T09:25:27Z",
    "success" : true,
    "ip" : "85.0.141.184"
  }, {
    "action" : "authorize",
    "amount" : 1000,
    "source" : "redirect",
    "date" : "20XX-09-14T09:25:26Z",
    "success" : true,
    "ip" : "85.0.141.184"
  } ]
}

SameSite cookies

From Chrome 80 onwards, cookies that do not specify a SameSite attribute will begin to be treated as if they were SameSite=Lax. Datatrans does not use cookies for payments. However, if your redirect URLs rely on an active user session in order to work properly, there is a possibility that the new cookie behavior in newer versions of Chrome will break your payment flow.

The SameSite=Lax behavior can be enforced with newer versions of Google Chrome for testing. Set chrome://flags/#same-site-by-default-cookies and chrome://flags/#cookies-without-same-site-must-be-secure to enabled. During testing, please make sure to wait 2 minutes before redirecting back to your page. This is needed because Chrome treats cookies without the SameSite attribute only as SameSite=Lax after 2 minutes. If your solution does not work anymore after enabling SameSite=Lax, please adjust your configuration by applying the recommended changes described by Google.

More information and how other browsers handle this topic can be found here.

Setting the ShortLaxAllowUnsafeThreshold

If during development you don't always want to wait two minutes for your tests, the following Chrome feature can be enabled to lower the timeout from 2 minutes to 10 seconds:
--enable-features=ShortLaxAllowUnsafeThreshold

This feature is available in Chrome 79.0.3945.16 and newer.

Updated 25 days ago

Redirect & Lightbox


Suggested Edits are limited on API Reference Pages

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