For any question, we are one click away

Contact us

SDK Payment process

Web View for 3DS

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

sequenceDiagram participant MA as Mobile App participant MS as Mobile Server participant SDK as SDK participant PG as Payment Gateway autonumber MA ->> MS: client creates an order MS ->> PG: create a session PG -->> MS: unique session number (sessionId) MA ->> SDK: init SDK Payment SDK ->> SDK: client enters data SDK ->> PG: send paymentToken PG ->> PG: make payment (includes 3DS) opt Webhook is configured PG -->> MS: webhook notification end MS ->> PG: check payment status MS ->> MA: show payment result to the client
  1. Client creates an order.
  2. Mobile Server creates a session in Payment Gateway via /sessions. Use failureUrl and successUrl parameters as a marker to close Web View after redirect from ACS.
  3. Mobile Server receives a unique session number (sessionId) in response.
  4. Mobile App initiates SDK Payment to collect Client's payment data.
  5. Client fills in payment data.
  6. SDK sends encrypted payment data (paymentToken) to Payment Gateway. Read more about the paymentToken here.
  7. Payment Gateway makes a payment. If it's required, Payment Gateway handles 3DS Secure communication.
  8. Payment Gateway sends webhook notification to Merchant server (it must be configured by the Merchant in advance).
  9. Alternatively, the Merchant may get session object and it's status by sessionId via /sessions.
  10. Mobile App shows payment result to the Client.

iOS

The project setup is described below. Framework can be installed manually.

SDKPayment is based on ThreeDSSDK, SDKForms frameworks. Therefore they are required for import.

To install frameworks manually, download and add them to the project.

iOS Integration

SDKForms.framework integration

You can integrate SDKForms.framework in the following way:

SDKForms.framework

Image 1. Adding the SDKForms.framework file


Image 2. Changing SDKForms.framework properties


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

SDKPayment.framework integration

SDKPayment.framework

Image 3. Adding the SDKPayment.framework file


Image 4. Changing SDKPayment.framework properties


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

//ViewController.swift
...
import SDKPayment
...

How to work with API v2

SDK Configuration

For initialization, it is necessary to set the payment gateway server address.

final class MainViewController: UIViewController {

    private func checkout() {
      SdkPayment.initialize(
        sdkPaymentConfig: SDKPaymentConfig(
          baseURL: "\(baseApiUrl)",
          use3DSConfig: .noUse3ds2sdk,
          keyProviderUrl: "\(baseApiUrl)/se/keys.do"
        )
      )
      ...
    }
  }

When using API v2, you need to register a new session checkout. When registering a session, the request must contain successUrl and failureUrl parameters equal to "sdk://done".

To use the checkoutWithBottomSheet() method, you need to create CheckoutConfig with sessionid.

final class MainViewController: UIViewController {

    private func checkout() {
      ...
      // Creating `CheckoutConfig`
      let checkoutConfig = CheckoutConfig(id: .sessionId(id: sessionId))

      SdkPayment.shared.checkoutWithBottomSheet(
          controller: navigationController!,
          checkoutConfig: checkoutConfig,
          callbackHandler: self
      )
    }
  }

Payment result processing

For MainViewController, you need to implement the requirements of ResultPaymentCallback.

extension MainViewController: ResultPaymentCallback {

    typealias T = PaymentResult

    func onResult(result: PaymentResult) {
      print("\(result.isSuccess) \(result.paymentId)")
    }
  }

On successful payment, a PaymentResult object is returned containing the isSuccess boolean field with the result of the payment and optional exception field.

Screen samples

Paying with a new card


Image 5. Card payment
Image 6. 3DSecure confirmation

Paying with a bound card

Image 7. Card payment
Image 8. CVC confirmation
Image 9. 3DSecure confirmation


Logging

Internal processes are logged with the SDKPayment tag. You can also log your processes.

Logging is available through the Logger.shared object.

Example for logging:

...
final class LoggerImplementation: LogInterface {

    func log(class: AnyClass, tag: String, message: String, exception: (any Error)?) {
        // Do something for logging
    }
}

Logger.shared.addLogInterface(logger: LoggerImplementation())
...

The default tag is SDKPayment. You can set your own one if you like.

Example:

...
     Logger.shared.log(classMethod: type(of: self),
                       tag: "MyTag",
                       message: "My process...",
                       exception: nil)
...

How to work with API V1

SDK configuration

For initialization, it is necessary to set the payment gateway server address.

final class MainViewController: UIViewController {

    private func checkout() {
      SdkPayment.initialize(
        sdkPaymentConfig: SDKPaymentConfig(
          baseURL: "\(baseApiUrl)",
          use3DSConfig: .noUse3ds2sdk,
          keyProviderUrl: "\(baseApiUrl)/se/keys.do"
        )
      )
      ...
    }
  }

When using API v1, you need to register new order. When registering an order, the request must contain the returnUrl parameter equal to "sdk://done".

To use the checkoutWithBottomSheet() method, you need to create CheckoutConfig with mdOrder.

final class MainViewController: UIViewController {

    private func checkout() {
      ...
      // Creating `CheckoutConfig`
      let checkoutConfig = CheckoutConfig(id: .mdOrder(id: mdOrder))

      SdkPayment.shared.checkoutWithBottomSheet(
          controller: navigationController!,
          checkoutConfig: checkoutConfig,
          callbackHandler: self
      )
    }
  }

Payment result processing

For MainViewController, you need to implement the requirements of ResultPaymentCallback.

extension MainViewController: ResultPaymentCallback {

    typealias T = PaymentResult

    func onResult(result: PaymentResult) {
      print("\(result.isSuccess) \(result.paymentId)")
    }
  }

Android

SDKPayment is based on ThreeDSSDK, SDKForms frameworks. Therefore, they are required for import.

Android Integration

Connecting to a Gradle project by adding .aar library files

You must add the sdk_forms-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_forms-release", ext = "aar")

  implementation("androidx.cardview:cardview:1.0.0")
  implementation("com.github.devnied.emvnfccard:library:3.0.1")
  implementation("com.caverock:androidsvg-aar:1.4")
  implementation("io.card:android-sdk:5.5.1")
  implementation("com.google.android.gms:play-services-wallet:18.0.0")
}

build.gradle

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

dependencies {
  // dependency is mandatory to add
  implementation(group = "", name = "sdk_forms-release", ext = "aar")
  implementation("androidx.cardview:cardview:1.0.0")
  implementation("com.github.devnied.emvnfccard:library:3.0.1")
  implementation("com.caverock:androidsvg-aar:1.4")
  implementation("io.card:android-sdk:5.5.1")
  implementation("com.google.android.gms:play-services-wallet:18.0.0")
}

Connecting to a Gradle project by adding .aar library files

You must add the sdk_payment-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_payment-release", ext = "aar")
}

build.gradle

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

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

How to work with API V2

SDK configuration

For initialization, it is necessary to set the payment gateway server address.

SDKPayment.init(
  SDKPaymentConfig(
    baseURL = "https://dev.bpcbt.com/payment/rest",
  )
)

When using API v2, you need to register a new session checkout. When registering a sessionId, the request must contain successUrl and failureUrl parameters equal to "sdk://done".

// A link to an activity or a fragment is required. Checkout config is required.
  val checkoutConfig = CheckoutConfig.sessionId("sessionId")
  SDKPayment.checkout(activity = this, checkoutConfig = checkoutConfig)

The base URL for accessing payment gateway methods and the root certificate for verification signatures are specified through the object of the SDKPaymentConfig class.

The checkout method is available in two variations, to be called from Activity and Fragment:

checkout(activity: Activity, checkoutConfig: CheckoutConfig) checkout(fragment: Fragment, checkoutConfig: CheckoutConfig)

Payment result processing

For Activity and Fragment, you need to override the onActivityResult method.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // Processing the result of the payment cycle. 
    SDKPayment.handleCheckoutResult(requestCode, data, object :
        ResultPaymentCallback<PaymentData> {
          override fun onResult(result: PaymentResult) {
            // check payment result
          }
    })
}

On successful payment, a PaymentResult object is returned containing the isSuccess boolean field with the result of the payment and optional exception field.

How to work with API V1

SDK configuration

For initialization, it is necessary to set the payment gateway server address.

SDKPayment.init(
  SDKPaymentConfig(
    baseURL = "https://dev.bpcbt.com/payment/rest",
  )
)

When using API v1, you need to register a new order. When registering an order, the request must contain returnUrl and no other parameters with Url, like failUrl. returnUrl must be equal to "sdk://done".

// A link to an activity or a fragment is required. Checkout config is required.
  val checkoutConfig = CheckoutConfig.MdOrder("eecbbe96-973e-422e-a220-e9fa8d6cb124")
  SDKPayment.checkout(activity = this, checkoutConfig = checkoutConfig)

The base URL for accessing payment gateway methods and the root certificate for verification signatures are specified through the object of the SDKPaymentConfig class.

The checkout method is available in two variations, to be called from Activity andFragment:

checkout(activity: Activity, checkoutConfig: CheckoutConfig) checkout(fragment: Fragment, checkoutConfig: CheckoutConfig)

Payment result processing

For Activity andFragment, you need to override the onActivityResult method.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // Processing the result of the payment cycle. 
    SDKPayment.handleCheckoutResult(requestCode, data, object :
        ResultPaymentCallback<PaymentData> {
          override fun onResult(result: PaymentResult) {
            // check payment result
          }
    })
}

On successful payment, a PaymentResult object is returned containing the isSuccess boolean field with the result of the payment and optional exception field.

Screen samples

Paying with a new card


Image 10. Card payment
Image 11. 3DSecure confirmation


Paying with a bound card

Image 12. Card payment
Image 13. CVC confirmation
Image 14. 3DSecure confirmation

Payment via Google pay by the SDK Payment module

To make a payment via Google Pay by the SDK Payment module, you need to call the
checkout() payment method while passing true value of the gPayClicked flag. The default value is false.

fun checkout(activity: Activity, checkoutConfig: CheckoutConfig, gPayClicked: Boolean = false) {
}

Wallet button screens

Image 15. Google Pay button design

Logging

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

Logging is available through the Logger object.

...
    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.

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

FAQ

Q: What is CardIOUtilities?
A: CardIOUtilities is an interface of the CardIO lib. You can read a manual here https://github.com/card-io/card.io-iOS-source.

Categories:
eCommerce SDK API V2
Categories
Search results