Tokenizing a card in a mobile app

The easiest way to start accepting payments on mobile devices using Smart Router is to use our mobile SDKs. The SDKs will take care of tokenizing your customers’ card numbers, so that you can send those generated tokens to your backend and process payments.

Tokenize a card

First, you should obtain and set up the SDK in your code using the instructions for iOS or Android, as appropriate. Once all set up, you’ll be able to tokenize the card numbers. The returned token is a simple string.

iOS Android

// First create a card object containing the card details
let card = ProcessOut.Card(cardNumber: "4242424242424242", expMonth: 11, expYear: 19, cvc: nil, name: "NAME")

// And then send the card data to ProcessOut to tokenize
ProcessOut.Tokenize(card: card, metadata: [:], completion: {(token, error) -> Void in
    if error != nil {
        switch error! {
        case .BadRequest(let message, let code):
            print(message, code)
        case .InternalError:
            print("An internal error occured")
        case .MissingProjectId:
            print("Check your app delegate file")
        case .NetworkError:
            print("Request could not go through")
        }
    } else {
        // Send token to your backend to charge the customer
        print(token!)
    }
})

// First create a card object containing the card details
Card card = new Card("Jeremy lejoux", "4242424242424242", 11, 19, "123");

// And then send the card data to ProcessOut to tokenize
client.tokenize(card, new TokenCallback() {
    @Override
    public void onSuccess(String token) {
        // Send the card token to your backend for charging
    }

    @Override
    public void onError(Exception error) {
        Log.e("ProcessOut", error.toString());
    }
});

3DS2 handlers

3DS2 handlers are native elements that allow you to implement 3DS2 in your application while giving the best experience to your customers.

1— The test handler

The test handler is very simple: it simply emulates the 3DS authentication flow without having the make actual calls to ACS servers (servers of the banks of your customers used to process authentications).

The ProcessOut SDKs provide factories to build the 3DS2 test handler:

iOS Android

let handler = ProcessOut.createThreeDSTestHandler(viewController: self, completion: { (invoiceId, error) in
    if invoiceId != nil {
        // The authentication was done successfully, you can send
        // back the invoice ID to your backend to validate the payment
        print("invoice: " + invoicecId)
    } else {
        // An error occurred
        print(error)
    }
})

final ThreeDSHandler handler = ProcessOut.createDefaultTestHandler(
    MainActivity.this,
    new ProcessOut.ThreeDSHandlerTestCallback() {
        @Override
        public void onSuccess(String invoiceId) {
            // The authentication was done successfully, you can send
            // back the invoice ID to your backend to validate the payment
            Log.d("PROCESSOUT", "invoice: " + invoiceId);
        }

        @Override
        public void onError(Exception error) {
            // An error occurred
            Log.e("PROCESSOUT", error.toString());
        }
    }
);

The test handler can basically be used when integrating using Smart Router’s sandbox, and can also be used to mock tests in your application.

Once you chose to deploy your mobile application to production, you can then start using the official 3DS SDKs from your 3DS Server partners.

2— The handler with the production 3DS SDK

As mentioned previously, the 3DS2 SDK works in a “bring your own SDK” manner. Most 3DS Server providers/partners will provide you with their own certified SDKs, which might also come with specific features you’d like to integrate.

To help in the process, you can find below the 3DS SDKs we officially support:

Adyen

2.1— Adyen

When making the payment on the Invoice you need to provide the Adyen SDK version to the makeCardPayment call. For iOS Adyen provides a method called ADY3DS2SDKVersion() and for Android it is called getSDKVersion(). We also allow you to optionally overwrite the preferred card scheme if the customer’s card supports co-schemes, such as Cartes Bancaire, as demonstrated below.

iOS Android

...

var authorizationRequest = AuthorizationRequest(
    source:"card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ",
    invoiceID: "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT"
);

// optional
authorizationRequest.thirdPartySDKVersion = ThreeDS2Service.ADY3DS2SDKVersion()
authorizationRequest.preferredScheme = "carte bancaire"

ProcessOut.makeCardPayment(
    authorizationRequest,
    handler,
    with: self
);

...

...

AuthorizationRequest authorizationRequest = new AuthorizationRequest(
    "card_1jSEVrx7oaRta1KEdxoMWbiGkK2MijrZ", // source
    "iv_tIWEiBcrXIFHzJeXcZzqyp8EpY0xwmuT" // invoiceId
);

// optional
authorizationRequest.setThirdPartySDKVersion(ThreeDS2Service.getSDKVersion())
authorizationRequest.setPreferredScheme("carte bancaire")

client.makeCardPayment(
    authorizationRequest,
    handler
);

...

The below code implements the 3DS2 SDK using Adyen’s certified SDK.

iOS Android

import ProcessOut
import Adyen3DS2

class AdyenThreeDSHandler: ThreeDSHandler {
    var transaction: ADYTransaction?

    public func doPresentWebView(webView: ProcessOutWebView) {
        // Called when a web challenge is required. Present 
        // the webview to the user
    }

    func doFingerprint(directoryServerData: DirectoryServerData, completion: @escaping (ThreeDSFingerprintResponse) -> Void) {
        let parameters = ADYServiceParameters()
        parameters.directoryServerIdentifier = directoryServerData.directoryServerID
        parameters.directoryServerPublicKey = directoryServerData.directoryServerPublicKey

        ADYService.service(with: parameters, appearanceConfiguration: nil, completionHandler: {(service: ADYService) -> Void
            in
            do {
                self.transaction = try service.transaction(withMessageVersion: directoryServerData.messageVersion)
                    let authReqParams = self.transaction!.authenticationRequestParameters
                    if let sdkEphemPubKeyData = authReqParams.sdkEphemeralPublicKey.data(using: .utf8) {
                        let sdkEphemPubKey = try JSONDecoder().decode(ThreeDSFingerprintResponse.SDKEphemPubKey.self, from: sdkEphemPubKeyData)
                        let fingerprintResponse = ThreeDSFingerprintResponse(
                            sdkEncData: authReqParams.deviceInformation,
                            sdkAppID: authReqParams.sdkApplicationIdentifier,
                            sdkEphemPubKey: sdkEphemPubKey,
                            sdkReferenceNumber: authReqParams.sdkReferenceNumber,
                            sdkTransID: authReqParams.sdkTransactionIdentifier
                        )

                        completion(fingerprintResponse)
                    } else {
                        print("Could not encode sdkEphem")
                    }
            } catch {
                print(error)
            }
        })
    }

    func doChallenge(authentificationData: AuthentificationChallengeData, completion: @escaping (Bool) -> Void) {
        let challengeParameters = ADYChallengeParameters(
            serverTransactionIdentifier: authentificationData.threeDSServerTransID, 
            acsTransactionIdentifier: authentificationData.acsTransID, 
            acsReferenceNumber: authentificationData.acsReferenceNumber, 
            acsSignedContent: authentificationData.acsSignedContent
        )

        transaction?.performChallenge(with: challengeParameters, completionHandler: { (result, error) in
            if result != nil{
                completion(true)
            } else {
                completion(false)
            }
        })
    }

    func onSuccess(invoiceId: String) {
        // The authentication was done successfully, you can send
        // back the invoice ID to your backend to validate the payment
        print("SUCCESS:" + invoiceId)
    }

    func onError(error: ProcessOutException) {
        // An error occurred
        print(error)
    }
}

import com.adyen.threeds2.AuthenticationRequestParameters;
import com.adyen.threeds2.ChallengeStatusReceiver;
import com.adyen.threeds2.CompletionEvent;
import com.adyen.threeds2.ProtocolErrorEvent;
import com.adyen.threeds2.RuntimeErrorEvent;
import com.adyen.threeds2.ThreeDS2Service;
import com.adyen.threeds2.Transaction;
import com.adyen.threeds2.exception.SDKAlreadyInitializedException;
import com.adyen.threeds2.exception.SDKNotInitializedException;
import com.adyen.threeds2.parameters.ChallengeParameters;
import com.adyen.threeds2.parameters.ConfigParameters;
import com.adyen.threeds2.util.AdyenConfigParameters;

// ...

final ThreeDSHandler handler = new ThreeDSHandler() {
    private Transaction mTransaction;

    @Override
    public void doPresentWebView(ProcessOutWebView webView) {
        // Called when a web challenge is required. Present 
        // the webview to the user
    }

    @Override
    public void doFingerprint(DirectoryServerData dsdata, DoFingerprintCallback callback) {
        ConfigParameters config = new AdyenConfigParameters.Builder(
            dsdata.getDirectoryServerID(), 
            dsdata.getDirectoryServerPublicKey()
        ).build();
        try {
            ThreeDS2Service.INSTANCE.initialize(MainActivity.this, config, null, null);
            mTransaction = ThreeDS2Service.INSTANCE.createTransaction(null, dsdata.getMessageVersion());
            AuthenticationRequestParameters t = mTransaction.getAuthenticationRequestParameters();
            ThreeDSFingerprintResponse gatewayRequest = new ThreeDSFingerprintResponse(
                t.getDeviceData(), 
                t.getSDKAppID(), 
                new Gson().fromJson(t.getSDKEphemeralPublicKey(), SDKEPhemPubKey.class), 
                t.getSDKReferenceNumber(), 
                t.getSDKTransactionID()
            );
            callback.continueCallback(gatewayRequest);
        } catch (SDKAlreadyInitializedException e) {
            e.printStackTrace();
        } catch (SDKNotInitializedException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void doChallenge(AuthenticationChallengeData authenticateData, final DoChallengeCallback callback) {
        ChallengeParameters challengeParameters = new ChallengeParameters();
        challengeParameters.set3DSServerTransactionID(authenticateData.getThreeDSServerTransID());
        challengeParameters.setAcsTransactionID(authenticateData.getAcsTransID());
        challengeParameters.setAcsRefNumber(authenticateData.getAcsReferenceNumber());
        challengeParameters.setAcsSignedContent(authenticateData.getAcsSignedContent());

        mTransaction.doChallenge(MainActivity.this, challengeParameters, new ChallengeStatusReceiver() {
            @Override
            public void completed(CompletionEvent completionEvent) {
                callback.success();
            }

            @Override
            public void cancelled() {
                // Cancelled by the user or the App.
                callback.error();
            }

            @Override
            public void timedout() {
                // The user didn't submit the challenge within the given time, 5 minutes in this case.
                callback.error();
            }

            @Override
            public void protocolError(ProtocolErrorEvent protocolErrorEvent) {
                // An error occurred.
                callback.error();
            }

            @Override
            public void runtimeError(RuntimeErrorEvent runtimeErrorEvent) {
                // An error occurred.
                callback.error();
            }
        }, 5);
    }

    @Override
    public void onSuccess(String invoiceId) {
        // The authentication was done successfully, you can send
        // back the invoice ID to your backend to validate the payment
        Log.d("PROCESSOUT", "SUCCESS:" + invoiceId);
    }

    @Override
    public void onError(Exception error) {
        // An error occurred
        Log.e("PROCESSOUT", error.toString());
    }
};