Our 3D Secure Mobile SDKs allow you to securely collect and tokenize sensitive card data (card numbers and CVV codes) in your native iOS or Android app while authenticating the cardholder via 3D Secure at the same time. Completely outsource your tokenization and authentication processes to our libraries and benefit from:

• 3D Secure / SCA Ready: the SDK takes over the complexity of the 3DS process
• Secure, smart and state of the art UI components
• Card brand identification and input validation
• Credit card scanner
• Storing payment information for later use and checkout: reuse tokens stored in our vaults
• Theme and styling support

📘

It is currently not possible to use this API while sending 3D Acquiring data dynamically.

Contact us if you have such a use case.

Before you start

🚧

3D Secure Fields requires a 3D Secure enrolled acquiring contract for each card brand.

Check out the enrolment requirements for more information. You will need data provided in this contract when using 3D Secure Fields.

Make sure to also use our 3D Secure-enabled test credit cards and credentials.

💡

Note that all 'amounts' in these APIs are in minor units.

For example, CHF has 2 decimal points, so "amount": 1250 corresponds to 12.50 CHF. For JPY, "amount": 1250 corresponds to 1250 JPY.

Distribution and Download

Refer to Overview for links to download. Once you have the libraries, follow the below guide to integrate 3D Secure on the SDKs.

1. Initial server-to-server call

To start a 3D Secure Mobile SDK tokenization, you have to call our init API from your server. The response returns a mobileToken which is required to initialize our libraries.

curl --request POST \
  --url 'https://api.sandbox.datatrans.com/v1/transactions' \
  --header 'Authorization: Basic {{basicAuth}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "currency": "EUR",
    "refno": "SDK 3D_test",
    "paymentMethods": [
        "ECA", "VIS"
    ],
    "card": {
        "createAliasCVV": true
    },
    "option": {
        "authenticationOnly": true,
        "createAlias": true,
        "returnMobileToken": true
    }
}'

{
  "mobileToken": "cca3f978017a694e11e92c10d78e71f302eb982819eaa857"
}

2. Integrate the mobile SDK

Now that you have retrieved a mobileToken, you can continue with the initialization of our iOS or Android SDK. Make sure to call the library with your mobile token to start a transaction. Below are some examples of suggested minimum options to start a transaction with iOS (Swift, Objective-C) and Android (Kotlin, Java).

let transaction = Transaction(mobileToken: mobile, aliasPaymentMethods: aliasPaymentMethods)
transaction.delegate = self
transaction.options.appCallbackScheme = "your_scheme"
transaction.options.testing = true
transaction.options.useCertificatePinning = true
transaction.start(presentingController: navigationController)

DTTransaction* transaction = [[DTTransaction alloc] initWithMobileToken:mobileToken aliasPaymentMethods:aliasPaymentMethods];
transaction.delegate = self;
transaction.options.appCallbackScheme = @"your_scheme";
transaction.options.testing = YES;
transaction.options.useCertificatePinning = YES;
[transaction startWithPresentingController:self.navigationController];

val transaction = Transaction(mobileToken, aliasPaymentMethods)
transaction.listener = this
transaction.options.appCallbackScheme = "your_scheme"
transaction.options.isTesting = true
transaction.options.useCertificatePinning = true
TransactionRegistry.startTransaction(this, transaction)

Transaction transaction = new Transaction(mobileToken, aliasPaymentMethods);
transaction.setListener(this);
transaction.getOptions().setAppCallbackScheme("your_scheme");
transaction.getOptions().setTesting(true);
transaction.getOptions().setUseCertificatePinning(true);
TransactionRegistry.INSTANCE.startTransaction(this, transaction);

Check out our detailed class descriptions for iOS and Android to discover more initialization options.

Once the card details have been collected, the 3D Authentication process will start automatically. If required, the cardholder will be directed to the website or the banking application of the card issuer to complete a challenge.

After the transaction is completed, you can refer to the TransactionSuccess class, which will return the details of the transaction. If the transaction failed, you will have to refer to the TransactionError class for further details. You may implement TransactionDelegate (iOS) or TransactionListener (Android) to be notified when a transaction is successfully finalized, encounters an error, or is canceled by the user.

Additional requirements for iOS

For the card scanner to work, a usage description for camera use will be required in your .plist file. If you do not provide a description for camera use, the app will crash when starting the card scanner.

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

3. Obtain Tokens and 3D Secure data

To obtain the tokens and authentication result, you need to first submit the transactionId returned by the SDK to your server.

Then, call the GET Status API LINK from your server together with the transactionId to obtain a token for the card number and CVV code. Additionally, this API also returns a card.3D object which contains information about the result of the authentication process.

Example

curl --request GET \
  --url 'https://api.sandbox.datatrans.com/v1/transactions/190906151210861442' \
  --header 'Authorization: Basic MTEwMDAxNzY3NTpTejdodE5uSjdNM05YQ0lT'

{
  "transactionId": "210609101239797372",
  "type": "payment",
  "status": "authenticated",
  "currency": "EUR",
  "refno": "SDK 3D_test",
  "paymentMethod": "ECA",
  "detail": {
    "authorize": {
      "amount": 1000
    }
  },
  "card": {
    "alias": "AAABee_Un5_ssdexyrAAAXULTeyzAAe1",
    "fingerprint": "F-c6FruvXTy36oJPosQUsRCf",
    "masked": "540400xxxxxx0001",
    "aliasCVV": "HemcmX8TTB6Lipr_uF5IwG9M",
    "expiryMonth": "06",
    "expiryYear": "25",
    "3D": {
      "eci": "02",
      "xid": "1f88043a-7d5c-431b-be5d-bfebd6088992",
      "cavv": "OTkxOTA4MDkxNjMzMTYwNTUwMzY=",
      "threeDSVersion": "2.2.0",
      "directoryResponse": "Y",
      "authenticationResponse": "Y",
      "transStatusReason": "01",
      "cardHolderInfo": "Detailed issuer notification if available",
      "threeDSTransactionId": "8558c931-277b-4240-adfc-443cbd61a2c0"
    }
  },
  "history": [
    {
      "action": "authenticate",
      "amount": 1000,
      "source": "api",
      "date": "2021-06-09T08:12:49Z",
      "success": true,
      "ip": "178.238.172.18"
    }
  ]
}

Customizations

Refer to Customizations for more details.