SDK Core process

Web View for 3DS

The diagram below shows the SDK Core payment process with 3DS redirect via Web View

1. Client creates an order
2. Mobile Server registers that order in Payment Gateway via register.do. Use returnUrl parameter as a marker to close Web View after redirect from ACS on step 13.
3. Mobile Server receives a unique order number mdOrder in response.
4. Client fills in payment data in Mobile App.

5. Mobile App calls SDK to create seToken. (Android: sdkCore.generateWithCard; iOS: CKCToken.generateWithCard).

   The public key used in the corresponding method is taken from the https://uat.dskbank.bg/payment/se/keys.do online resource. If multiple keys are available there, the first key should be used (note that the keys for UAT and production environments are different).

6. Mobile App sends the seToken to Mobile Server.

7. Mobile Server uses the seToken to make a payment via paymentorder.do request.

   • Use seToken instead of pan, cvc and expiry date.
   • Don't forget to send Cardholder name in TEXT field. If you don't collect Cardholder name just send CARDHOLDER.

8. Mobile Server gets a response with no ACS redirect. It means that the payment is completed and we need to go to step 16.

9. Mobile Server gets a response with ACS redirect.

10. Mobile App opens Web View with ACS redirect data.

11. Client enters their one time password to ACS form.

12. ACS redirects the Client to Payment Gateway

13. Payment Gateway makes a payment.

14. Payment Gateway redirects the Client to returnUrl, that can be used as a marker to close Web View.

15. Mobile App closes Web View.

16. Payment Gateway sends callback notification to Merchant server if it's configured for the merchant.

17. Mobile Server checks the final payment status via getOrderStatusExtended.do.

18. Mobile App shows payment result to the Client.

3DS2 SDK for 3DS

The diagram below shows the SDK Core payment process with 3DS redirect 3DS2 SDK. Be aware that many issuers' ACS don't work properly with 3DS Mobile SDKs.

1. Client creates an order.
2. Mobile Server registers the order in Payment Gateway via register.do. Use returnUrl parameter as a marker to close Web View after redirect from ACS on step 13.
3. Mobile Server receives a unique order number mdOrder in response.
4. Client fills in payment data in Mobile App.
5. Mobile App calls SDK to create seToken. (Android: sdkCore.generateWithCard; iOS: CKCToken.generateWithCard).
6. Mobile App sends seToken to Mobile Server.
7. Mobile Server uses that seToken to make a payment via paymentorder.do request.
   • Use seToken instead of pan, cvc and expiry date.
   • Don't forget to send Cardholder name in TEXT field. If you don't collect Cardholder name just send CARDHOLDER.
   • Send threeDSSDK=true to indicate that 3DS2 SDK should be used.
8. Mobile Server gets a response with no ACS keys. It means that payment is completed and we need to go to step 23.
9. Mobile Server gets a response with ACS keys.
   • Response must contain threeDSServerTransId and threeDSSDKKey.
   • Response should not contain threeDSMethodURL which is used in case of browser based redirect to ACS.
10. Mobile Server sends 3DS2 SDK data to Mobile App.
11. Mobile App initiates 3DS2 SDK via createTransaction method.
    • directoryServerID depends on Payment System (for tests A000000003 can be used).
    • messageVersion is 2.1.0 for now.
    • pemPublicKeyfor Android and for iOS is a pem certificate that is got in response in threeDSSDKKey on step 10.
    • dsRootfor Android and for iOS depends on Payment System. Download test key
12. 3DS2 SDK collects device data and encrypts it.
13. Mobile App sends encrypted device data to Mobile Server.
14. Mobile Server initiates second payment API call via paymentorder.do request.
    • sdkEncData encrypted device data that is returned in createTransaction method in 3DS2 SDK.
    • threeDSSDKReferenceNumber 3DS2 SDK officially ids. Don't hardcode them. iOS: 3DS_LOA_SDK_BPBT_020100_00233, Android: 3DS_LOA_SDK_BPBT_020100_00231.
    • threeDSServerTransactionID is returned in response to the first payment call on step 10 in threeDSServerTransId parameter.
    • sdkEphemPubKey is returned in createTransaction method in 3DS2 SDK.
    • sdkAppID is returned in createTransaction method in 3DS2 SDK.
    • sdkTransID is returned in createTransaction method in 3DS2 SDK.
15. Payment Gateway returns new special parameters for 3DS2 SDK.
16. Mobile Server sends those parameters to Mobile App.
17. Mobile App initiates challenge flow via doChallenge method.
    • doChallenge acsTransactionIDparameter corresponds to threeDSAcsTransactionId in Payment Gateway response.
    • doChallenge acsRefNumberparameter corresponds to threeDSAcsRefNumber in Payment Gateway response.
    • doChallenge acsSignedContentparameter corresponds to threeDSAcsSignedContent in Payment Gateway response.
    • doChallenge 3DSServerTransactionIDparameter corresponds to threeDSServerTransId in Payment Gateway response.
18. 3DS2 SDK communicates with issuers ACS via CReq/CRes API until Client confirms the payment.
19. ACS sends RReq to Payment Gateway to confirm or reject the payment.
20. 3DS2 SDK informs Mobile App that 3DS2 flow is over via ChallengeStatusReceiver.
21. Mobile Server finalizes the payment with finish3dsVer2Payment.do.
22. Payment Gateway makes a payment.
23. Payment Gateway sends callback notification to Merchant server if it's configured for merchant.
24. Mobile Server checks the final payment status via getOrderStatusExtended.do.
25. Mobile App shows payment result to the Client.

IOS

iOS Integration

SDKCore.framework integration

You can integrate SDKCore.framework by adding it manually.

SDKCore.framework

• Download the latest version of the framework here.

• Take the SDKCore.framework file and add it to the project folder.

• Open Targets -> General -> Frameworks, Libraries, and Embedded Content. For SDKCore.framework, in the Embed column, change Do not Embed to Embed & Sign.

Once done, import the framework in the ViewController.swift file.

//ViewController.swift
...
import SDKCore
...

How to work with API V1

External dependencies

For generation of the token, it is necessary to set the public key.

let publicKey: String =
      "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoIITqh9xlGx4tWA+aucb0V0YuFC9aXzJb0epdioSkq3qzNdRSZIxe/dHqcbMN2SyhzvN6MRVl3xyjGAV+lwk8poD4BRW3VwPUkT8xG/P/YLzi5N8lY6ILlfw6WCtRPK5bKGGnERcX5dqL60LhOPRDSYT5NHbbp/J2eFWyLigdU9Sq7jvz9ixOLh6xD7pgNgHtnOJ3Cw0Gqy03r3+m3+CBZwrzcp7ZFs41bit7/t1nIqgx78BCTPugap88Gs+8ZjdfDvuDM+/3EwwK0UVTj0SQOv0E5KcEHENL9QQg3ujmEi+zAavulPqXH5907q21lwQeemzkTJH4o2RCCVeYO+YrQIDAQAB-----END PUBLIC KEY-----"

Token generation method

let sdkCore = SdkCore()

let cardParams = CardParams(
     pan: "4111111111111111",
     cvc: "123",
     expiryMMYY: "12/28",
     cardholder: "TEST CARDHOLDER", 
     mdOrder: "mdOrder",
     pubKey: publicKey
)

let cardParamsConfig = SDKCoreConfig(
    paymentMethodParams: .cardParams(params: cardParams)
)
let tokenResult = sdkCore.generateWithConfig(config: cardParamsConfig)

let bindignParams = BindingParams(
    pubKey: publicKey,
    bindingId: "das",
    cvc: "123",
    mdOrder: "mdOrder"
)
let bindingParamsConfig = SDKCoreConfig(
    paymentMethodParams: .bindingParams(params: bindignParams)
)
let tokenResult = sdkCore.generateWithConfig(config: bindingParamsConfig)

Models

CardParams

BindingParams

Field validation errors

Android

Android Integration

Connecting to a Gradle project by adding .aar library files

You must add the sdk_core-release.aar library file to the libs folder, then specify the dependency of the added library.

build.gradle.kts

allprojects {
    repositories {
        // ...
        flatDir {
            dirs("libs")
        }
    }
}

dependencies {
    // dependency is mandatory to add
    implementation(group = "", name = "sdk_core-release", ext = "aar")
}

build.gradle

allprojects {
    repositories {
        // ...
        flatDir {
            dirs 'libs'
        }
    }
}

dependencies {
    // dependency is mandatory to add
    implementation(group: '', name: 'sdk_core-release', ext: 'aar')
}

Android Configuration

Logging

Internal processes are logged with the SDK-Core tag. You can also log your processes.

Logging is available through the Logger object.

• To add log- interfaces, you should call the Logger-method addLogInterface().

  Example of logging into LogCat:

...
    Logger.addLogInterface(object : LogInterface {
        override fun log(classMethod: Class<Any>, tag: String, message: String, exception: Exception?) {
                Log.i(tag, "$classMethod: $message", exception)
            }
        })
...

The default tag is SDK-Core. You can set your own one if you like.

• To log your own events, you should call Logger-method log().

  Example:

...
     Logger.log(this.javaClass, "MyTag", "My process...", null)
...

Example Kotlin_core (no GUI)

Example of cryptogram formation

import net.payrdr.mobile.payment.sdk.core.SDKCore
import net.payrdr.mobile.payment.sdk.core.TokenResult
import net.payrdr.mobile.payment.sdk.core.model.BindingParams
import net.payrdr.mobile.payment.sdk.core.model.CardParams
import net.payrdr.mobile.payment.sdk.core.validation.BaseValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardCodeValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardExpiryValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardHolderValidator
import net.payrdr.mobile.payment.sdk.core.validation.CardNumberValidator
import net.payrdr.mobile.payment.sdk.core.validation.OrderNumberValidator

class MainActivity : AppCompatActivity() {
    // initialization of validators for card information entry fields
    private val cardNumberValidator by lazy { CardNumberValidator(this) }
    private val cardExpiryValidator by lazy { CardExpiryValidator(this) }
    private val cardCodeValidator by lazy { CardCodeValidator(this) }
    private val cardHolderValidator by lazy { CardHolderValidator(this) }
    private val orderNumberValidator by lazy { OrderNumberValidator(this) }
    private val sdkCore by lazy { SDKCore(context = this) }

    override fun onCreate(savedInstanceState: Bundle?) {
        // installation of validators on the card information entry fields
        cardNumberInput.setupValidator(cardNumberValidator)
        cardExpiryInput.setupValidator(cardExpiryValidator)
        cardCodeInput.setupValidator(cardCodeValidator)
        cardHolderInput.setupValidator(cardHolderValidator)
        mdOrderInput.setupValidator(orderNumberValidator)

        // creation of an object and initialization of fields for a new card
        val params = NewPaymentMethodCardParams(
            pan = cardNumberInput.text.toString(),
            cvc = cardCodeInput.text.toString(),
            expiryMMYY = cardExpiryInput.text.toString(),
            cardHolder = cardHolderInput.text.toString(),
            pubKey = pubKeyInput.text.toString()
        )
        // method call to get the cryptogram for a new card
        sdkCore.generateWithConfig(SDKCoreConfig(params))

        // Creation of an object and initialization of fields for the linked card
        val params = NewPaymentMethodStoredCardParams(
            storedPaymentId = "storedPaymentMethodId",
            cvc = "123",
            pubKey = pubKeyInput.text.toString()
        )
        // method call to get the cryptogram for the linked card
        sdkCore.generateWithConfig(SDKCoreConfig(params))
    }
}

Models

NewPaymentMethodCardParams

NewPaymentMethodStoredCardParams

TokenResult

Field validation errors

How to work with API V1

External dependencies

For generation of the token, it is necessary to set the public key.

val publicKey: String =
    "-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoIITqh9xlGx4tWA+aucb0V0YuFC9aXzJb0epdioSkq3qzNdRSZIxe/dHqcbMN2SyhzvN6MRVl3xyjGAV+lwk8poD4BRW3VwPUkT8xG/P/YLzi5N8lY6ILlfw6WCtRPK5bKGGnERcX5dqL60LhOPRDSYT5NHbbp/J2eFWyLigdU9Sq7jvz9ixOLh6xD7pgNgHtnOJ3Cw0Gqy03r3+m3+CBZwrzcp7ZFs41bit7/t1nIqgx78BCTPugap88Gs+8ZjdfDvuDM+/3EwwK0UVTj0SQOv0E5KcEHENL9QQg3ujmEi+zAavulPqXH5907q21lwQeemzkTJH4o2RCCVeYO+YrQIDAQAB-----END PUBLIC KEY-----"

Token generation method

// TokenResult with CardParams
val cardParams: CardParams = CardParams(
    mdOrder = "mdOrder",
    pan = "4111111111111111",
    cvc = "123",
    expiryMMYY = "12/28",
    cardHolder = "TEST CARDHOLDER",
    pubKey = "publicKey"
)
val tokenResult = sdkCore.generationWithConfig(paymentCardParams = cardParams)

// TokenResult with BindingParams
val bindingParams: BindingParams = BindingParams(
    mdOrder = "mdOrder",
    bindingID = "das",
    cvc = "123",
    pubKey = "publicKey"
)

val tokenResult = sdkCore.generationWithConfig(paymentCardParams = bindingParams)