Datatrans Documentation

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!

Mobile SDK

Accept payments on your iOS or Android apps: Our mobile SDKs support your entire payment and registration process and simplify the integration of any payment method in your mobile apps. Completely outsource your payment processes to us from inside your native apps. We also take care of redirecting your users to 3D Secure processes and enable smooth app-switches to other payment applications including PayPal, Twint, and PostFinance.

We just revamped our Mobile SDK integration!

Our Mobile SDKs for iOS and Android were recently revamped. We improved UX and UI processes for our mobile SDKs. This new solution offers a state-of-the-art payment experience for mobile applications using native elements. Send us a message anytime by using this link if you have questions about our new SDKs.

If you are looking for our old Mobile SDK, please click here. We do recommend switching to our new SDKs for new solutions.

Distribution & Download

Access the latest version of our SDKs by following the links below and link the latest release to your app projects.



Github: Link
iOS SDK Reference: Link

Supported iOS Versions: 11 +


JFrog Repository: Link
Android SDK Reference: Link

Supported Android Versions: 5.0 +

Features

Easy Integration: Integrate many of our payment methods easily to your iOS and Android projects. Smart, modern and secure UI components to master online payments in your apps.

Card Scanner: Let your customers scan their card information easily with our prebuilt card scanner. No time wasted with entering card information.

3DS 2.0 / SCA Ready: The iOS and Android SDK takes over the complexity of the 3DS process. We remain in charge of redirecting users whenever 3D authentication is required to the 3DS process of their bank and back to the SDK.

Smooth App-Switch: Do you offer payment methods like Twint or PostFinance that require the user to confirm the payment in a separate mobile app? The library switches smoothly to external apps and back to the SDK.

Tokens and Fast Checkouts: Save your customers’ payment information for later use and offer fast checkouts in your app. Delegate the token selection to the library.

Theme Support: Style various items according to your corporate identity if needed. We also support the native dark theme of iOS and Android.

Easy Integration: Integrate many of our payment methods easily to your iOS & Android projects. Smart, modern and secure UI components to master online payments in your apps.

Card Scanner: Let your customers scan their card information easily with our prebuilt card scanner. No time wasted with entering card information.

3DS 2.0 / SCA Ready: The iOS & Android SDK takes over the complexity of the 3DS process. We remain in charge of redirecting users whenever 3D authentication is required to the 3DS process of their bank and back to the SDK.

Smooth App-Switch: Do you offer payment methods like Twint or PostFinance that require the user to confirm the payment in a separate mobile app? The library switches smoothly to external apps and back to the SDK.

Tokens and Fast Checkouts: Save your customers’ payment information for later use and offer fast checkouts in your app. Delegate the token selection to the library.

Theme Support: Style various items according to your corporate identity if needed. We also support the native dark theme of iOS and Android.

Initializing Transactions

To create a payment with our Mobile SDKs, you will need to initialize a mobileToken via a server-to-server call first. Call our init endpoint with your desired parameters and the option returnMobileToken and we'll return a mobileToken ready to be used with our SDKs. Please note that a mobileToken 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.

You need to specify at least one payment method during your init call to retrieve a mobileToken. If you do the preselection of the payment method on your end, simply send the array paymentMethods including only one payment method to directly show the final payment screen of that specific payment method. If you wish to display several payment methods on our Mobile SDK, you can simply extend the array with further payment methods. The order of the payment methods in your init call defines the order that is displayed in our SDKs.

If a payment method requires specific customer, shipping, or billing information, you may include it as well during your init payload. This is usually necessary for invoice payments.

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": 100,
	"paymentMethods": ["ECA","VIS","PAP","TWI"],
	"option": {
		"returnMobileToken": true
	}
}'

Mobile SDK Integration

Now that you have retrieved a mobileToken, you can continue with the initialization of our iOS or Android SDK. For iOS, you can add the SDK to your project by adding a new package dependency in Xcode or via Cocoapods with pod 'Datatrans'. For Android projects, you can link the repo and dependencies as demonstrated here:

repositories {
	...
	maven { url 'https://datatrans.jfrog.io/artifactory/mobile-sdk/' }
}

dependencies {
	...
	implementation 'ch.datatrans:android-sdk:1.4.2'
}

Call the library with your mobile token to start a transaction. You can optionally specify further options and pass tokens for fast checkouts with our provided classes. Below is an example of the suggested minimum options to start a transaction with iOS (Swift, Objective-C) and Android (Kotlin, Java). Please read our detailed classes description for iOS and Android to discover more initialization options.

let transaction = Transaction(mobileToken: String, paymentMethodTokens: [PaymentMethodToken])
transaction.delegate = self // you must implement your TransactionDelegate here
transaction.options.appCallbackScheme = "your_scheme"
transaction.options.testing = true
transaction.options.useCertificatePinning = true
transaction.start(presentingController: navigationController)
 
DTTransaction* transaction = [[DTTransaction alloc] initWithMobileToken:mobileToken paymentMethodTokens:paymentMethodTokens];
transaction.delegate = self;  // you must implement your TransactionDelegate here
transaction.options.appCallbackScheme = @"your_scheme";
transaction.options.testing = YES;
transaction.options.useCertificatePinning = YES;
[transaction startWithPresentingController:self.navigationController];
 
val transaction = Transaction(mobileToken, paymentMethodTokens)
transaction.listener = this // this refers to Android's Activity
transaction.options.appCallbackScheme = "your_scheme"
transaction.options.isTesting = true
transaction.options.useCertificatePinning = true
TransactionRegistry.startTransaction(this, transaction)
 
Transaction transaction = new Transaction(mobileToken, paymentMethodTokens);
transaction.setListener(this); // this refers to Android's Activity
transaction.getOptions().setAppCallbackScheme("your_scheme");
transaction.getOptions().setTesting(true);
transaction.getOptions().setUseCertificatePinning(true);
TransactionRegistry.INSTANCE.startTransaction(this, transaction);

Additional Requirements for iOS

For the card scanner to work, a usage description for the camera use will be required in your .plist file. If you do not provide a description for the camera use, the app will crash when starting the card scanner. If you are integrating Twint or PostFinance Card in your app, an automatic app-switch to the payment application and back to the SDK will be possible. For iOS projects however, you will have to add an array LSApplicationQueriesSchemes to your .plist file and the necessary schemes as Strings. This enables your iOS application to do an app-switch to Twint or PostFinance applications. 

Key    :  Privacy - Camera Usage Description   
Value  :  $(PRODUCT_NAME) requires camera access to scan cards.

Key    :  LSApplicationQueriesSchemes
Value  :  ["twint-issuer1", ... "twint-issuer50", "postfinance-epayment"]

To enable Apple Pay in your iOS projects, you will need to create an Apple merchant identifier, upload a certificate to your Datatrans merchant settings and activate the Apple Pay capability in XCode. Please refer to the section Apple Pay via Mobile SDK to correctly enable Apple Pay for your XCode project.

Auto Settlements

Settle your transactions automatically or in two steps with the parameter autoSettle during your init calls. 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 their 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. Payment methods that do not support tokenization will be automatically omitted.

The registered token (aka alias) and further relevant information will be returned by the library, in our webhook, and can be additionally retrieved by checking the status of a transaction. 

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

You can convert the returned paymentMethodToken class to a JSON object by using the function toJson.

Fast Checkouts

Fast checkouts or one-click checkouts can also be performed with our SDKs. If you include the object card with alias, expiryMonth, and expiryYear in your payload, we will continue with the authorization automatically once the SDK was called. This is useful for payments where you want your customers to complete a transaction quickly while also supporting 3D Secure. Only one payment method should be included in the array paymentMethods. You may also avoid calling the SDK with tokens for this to work properly.

"card": {
	"alias": "{{cardAlias}}",
	"expiryMonth": 12,
	"expiryYear": 25
},
"paymentMethods": ["VIS"]

Please note that fast checkouts are only available for card payments through the SDK. For other payment methods, you may proceed with a merchant-initiated transaction if you require a recurring seamless transaction without having to show the SDK UI. Another option would be to start the SDK with the token selection screen.

Token Selection Screen

Unlike our Redirect and Lightbox integration, you can call our SDK with a token selection screen. You can even include multiple tokens per payment method. This is useful if you want the user to finalize their payment with one click with a previously registered card. To initialize the library with a token, you may refer to the class PaymentMethodAlias and its sub-classes (i.e. CardAlias) for payment methods requiring more than just the token to create a payment.

After the Transaction

After the transaction has been completed, you can refer to the class TransactionSuccess that will return the details of the transaction, including the payment method, the transaction unique identifier, and the token if one was created. If the transaction failed, you will have to refer to the class TransactionError for further details instead. You may also implement TransactionDelegate (iOS) and TransactionListener (Android) to be notified when a transaction is successfully finalized, encounters an error, or canceled by the user. We will also return the transaction information to your defined webhook.

Styling the Theme

You can style various options in our Mobile SDKs. Refer to the class ThemeConfiguration to adapt various colors to your corporate identity.

Webhook

After any transaction that was processed via our Mobile SDK integration, we will call your webhook with all relevant transaction information. You can define your webhook URL within your merchant configuration. We include our mobileToken in a HTTP header and a transactionId in the payload to let you match Mobile SDK transactions. Any server to server request to modify an existing transaction has to be made with our transactionId. Please refer to our page After The Payment for more information on actions you can make after a payment has been completed.

Within our SDK integration, your webhook will always be called asynchronously after a transaction has been completed. Unsuccessful calls will not trigger an error on the client calling the SDK. We only try to call your webhook once. If it fails, no additional calls will be performed.

{
  "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" : "Y"
    }
  },
  "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"
  } ]
}

Language Support

Our iOS and Android Mobile SDK integrations are currently translated and supported in the following languages:

English en

German de

French fr

Italian it

Please get in touch should you need an additional language to be added for your checkout or if you find a translation error.

Miscellaneous

As of April 2020, the iOS App Store no longer accepts new apps or app updates using UIWebView. Read more here.

Updated about 16 hours ago

Mobile SDK

Suggested Edits are limited on API Reference Pages

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