Mobile SDK Payment

Este SDK no solo muestra la interfaz de usuario para los datos de tarjeta, sino que también interactúa con la API de la pasarela de pagos. Además, maneja todas las redirecciones 3DS y puede usar 3DS SDK como integrado. Es más fácil para el comerciante integrar pagos de esta manera, pero este SDK no es tan flexible como SDK Forms o SDK Core (no hay posibilidad de usar todas las funciones de la API de pagos).

Tenga en cuenta que SDK Payment usa Mobile SDK 3DS2, y el ACS de muchos emisores no funciona correctamente con Mobile SDK 3DS2.

Métodos de pago soportados por este SDK:

Método de pago	Soporte
Tarjeta bancaria	Sí
Credenciales guardadas/tarjeta	Sí
Apple Pay	Sí
Google Pay	Sí

Más información sobre SDK Payment

Proceso de pago SDK Payment

Web View para 3DS

El diagrama a continuación muestra el proceso de pago SDK Payment con redirección 3DS a través de Web View.

sequenceDiagram participant MA as Aplicación móvil participant MS as Servidor móvil participant SDK as SDK participant PG as Pasarela de pagos MA ->> MS: 1. cliente crea pedido MS ->> PG: 2. registro de pedido a través de API PG -->> MS: 3. número único de pedido (mdOrder) MA ->> SDK: 4. inicialización SDK Payment SDK ->> SDK: 5. cliente introduce datos SDK -->> PG: 6. envío seToken PG ->> PG: 7. pago (incluye 3DS) opt Notificaciones Callback configuradas PG -->> MS: 8. notificación callback end MS ->> PG: 9. verificación estado del pago MS ->> MA: 10. mostrar resultado del pago al cliente

El cliente crea un pedido
El servidor móvil registra este pedido en la pasarela de pagos a través de register.do. Use el parámetro returnUrl como marcador para cerrar Web View después de la redirección desde ACS.
El servidor móvil recibe en respuesta el número único de pedido mdOrder.
La aplicación móvil inicia SDK Payment para recopilar los datos de pago del cliente.
El cliente completa los datos de pago.
SDK envía datos de pago cifrados (seToken) a la pasarela de pagos.
La pasarela de pagos realiza el pago.
- Si se requiere, la pasarela de pagos proporciona comunicación con 3D Secure.
- Para procesar pagos con 3DS 2 recomendamos usar redireccionamiento a través de web view (use3ds2sdk=false).
La pasarela de pagos envía notificación de callback al servidor del comerciante, si está configurado para el comerciante.
El servidor móvil verifica el estado final del pago a través de getOrderStatusExtended.do.
La aplicación móvil muestra el resultado del pago al cliente.

iOS

A continuación se describe la configuración del proyecto. El framework se puede instalar manualmente.

SDKPayment está basado en los frameworks ThreeDSSDK, SDKForms. Por lo tanto, son necesarios para la importación.

Para instalar los frameworks manualmente, descargue y añádalos al proyecto.

Integración iOS

Integración SDKForms.framework

Puede integrar SDKForms.framework de la siguiente manera:

Añada SDKForms.framework y SDKCore.framework manualmente.

SDKForms.framework

Descargue la última versión de los frameworks aquí.
Seleccione los archivos SDKCore.framework y SDKForms.framework, y luego añádalos a la carpeta del proyecto.

Figura 1. Adición del archivo SDKForms.framework

Abra la página Targets -> General -> Frameworks, Libraries, and Embedded Content. Para SDKCore.framework y SDKForms.framework en la columna Embed reemplace Do not Embed por Embed & Sign.

Figura 2. Modificación de propiedades SDKForms.framework

Después de esto importe el framework en el archivo ViewController.swift.

Integración SDKPayment.framework

SDKPayment.framework

Descargue la última versión de los frameworks aquí.
Seleccione los archivos descargados y añádalos a la carpeta del proyecto.

Figura 3. Adición del archivo SDKPayment.framework

Abra la página Targets -> General -> Frameworks, Libraries, and Embedded Content. En la columna Embed para los frameworks reemplace Do not Embed por Embed & Sign.

Figura 4. Modificación de propiedades SDKPayment.framework

Después de esto importe el framework en el archivo ViewController.swift.

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

Trabajo con API V2

Configuración SDK

Para la inicialización es necesario establecer la dirección del servidor de la pasarela de pagos.

final class MainViewController: UIViewController {

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

Al usar API V2 es necesario registrar el objeto session. Al registrar session la solicitud debe contener los parámetros successUrl y failureUrl, iguales a "sdk://done".

Para usar el método checkoutWithBottomSheet() es necesario crear CheckoutConfig con 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
      )
    }
  }

Procesamiento del resultado del pago

Para MainViewController es necesario implementar los requisitos de ResultPaymentCallback.

extension MainViewController: ResultPaymentCallback {

    typealias T = PaymentResult

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

Con un pago exitoso se devuelve el objeto PaymentResult, que contiene el campo isSuccess de formato boolean, que contiene el resultado del pago, y el campo opcional exception.

Ejemplos de pantallas


Card payment	3DSecure confirmation

Figura 5. Pago con tarjeta nueva


Saved cards	CVC confirmation	3DSecure confirmation

Figura 6. Pago con tarjeta vinculada

Registro de eventos

Los procesos internos se registran con la etiqueta SDKPayment. También puede registrar sus propios procesos.

El registro de eventos está disponible a través del objeto Logger.shared.

Para agregar interfaces de log es necesario llamar al método addLogInterface() de Logger.

Ejemplo para registro de eventos:

...
final class LoggerImplementation: LogInterface {

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

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

Por defecto se utiliza la etiqueta SDKPayment. Puede establecer la suya propia si lo desea.

Para registrar eventos propios es necesario llamar al método log() de Logger.shared.

Ejemplo:

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

Trabajo con API V1

Configuración del SDK

Para la inicialización es necesario especificar la dirección del servidor de la pasarela de pago.

final class MainViewController: UIViewController {

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

Al utilizar API V1 necesita registrar un nuevo objeto order. Al registrar order la solicitud debe contener el parámetro returnUrl igual a "sdk://done".

Para utilizar el método checkoutWithBottomSheet() es necesario crear CheckoutConfig con 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
      )
    }
  }

Manejo del resultado del pago

Para MainViewController es necesario implementar los requisitos de ResultPaymentCallback.

extension MainViewController: ResultPaymentCallback {

    typealias T = PaymentResult

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

Android

SDKPayment se basa en los frameworks ThreeDSSDK, SDKForms. Por lo tanto, son necesarios para la importación.

Integración Android

Conexión al proyecto Gradle mediante la adición de archivos .aar de la biblioteca

Es necesario agregar el archivo de la biblioteca sdk_forms-release.aar a la carpeta libs, y luego especificar la dependencia de la biblioteca agregada.

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")
}

Conexión al proyecto Gradle añadiendo archivos .aar de la biblioteca

Es necesario añadir el archivo de biblioteca sdk_payment-release.aar a la carpeta libs, y luego especificar la dependencia de la biblioteca añadida.

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")
}

Trabajo con API V2

Configuración del SDK

Para la inicialización es necesario establecer la dirección del servidor de la pasarela de pagos.

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

Al usar API V2 es necesario registrar el objeto session. Al registrar session la solicitud debe contener los parámetros successUrl y failureUrl, iguales a "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)

La URL base para acceder a los métodos de la pasarela de pagos y el certificado raíz para verificar la firma se especifican a través del objeto de la clase SDKPaymentConfig.

El método de pago está disponible en dos variantes, llamadas desde Activity y Fragment:

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

Procesamiento del resultado del pago

Para Activity y Fragment es necesario redefinir el método onActivityResult.

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
          }
    })
}

Cuando el pago es exitoso se devuelve el objeto PaymentResult, que contiene el campo isSuccess de formato boolean, conteniendo el resultado del pago, así como el campo opcional exception.

Trabajo con API V1

Configuración del SDK

Para la inicialización es necesario establecer la dirección del servidor de la pasarela de pagos.

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

Al usar API V1 necesita registrar un nuevo objeto order. Al registrar order la solicitud debe contener el parámetro returnUrl y no contener ningún otro parámetro con Url, como failUrl. returnUrl debe tener el valor "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)

La URL base para acceder a los métodos de la pasarela de pagos y el certificado raíz para verificar la firma se especifican a través del objeto de la clase SDKPaymentConfig.

El método de pago está disponible en dos variantes, llamadas desde Activity y Fragment:

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

Procesamiento del resultado del pago

Para Activity y Fragment es necesario sobrescribir el método onActivityResult.

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
          }
    })
}

Cuando el pago es exitoso, se devuelve un objeto PaymentResult, que contiene un campo de texto isSuccess de formato boolean, que contiene el resultado del pago, así como un campo opcional exception.

Ejemplos de pantallas


Pago con tarjeta	Confirmación 3DSecure

Figura 7. Pago con nueva tarjeta


Tarjetas guardadas	Confirmación CVC	Confirmación 3DSecure

Figura 8. Pago con tarjeta vinculada

Pago a través de Google Pay con el módulo SDK Payment

Para realizar un pago a través de Google Pay con el módulo SDK es necesario llamar al método de pago checkout(), pasando el valor true del flag gPayClicked. El valor por defecto es false.

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

Pantallas con botones de pago de billeteras

Figura 9. Diseño del botón Google Pay

Registro de eventos

Los procesos internos se registran con la etiqueta SDK-Core. También puedes registrar tus propios procesos.

El registro de eventos está disponible a través del objeto Logger.

Para agregar interfaces de log es necesario llamar al método addLogInterface() de Logger.

Ejemplo para registro en LogCat:

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

Por defecto se usa la etiqueta SDK-Core. Puedes establecer la tuya propia, si lo deseas.

Para registrar eventos propios es necesario llamar al método log() de Logger.

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

Preguntas frecuentes

Q: ¿Qué es CardIOUtilities?
A: CardIOUtilities - es una interfaz de la biblioteca CardIO. Puedes leer la guía aquí: https://github.com/card-io/card.io-iOS-source.

Categorías:

eCommerce SDK

Mobile SDK Payment

Proceso de pago SDK Payment

Web View para 3DS

iOS

Integración iOS

Integración SDKForms.framework

Integración SDKPayment.framework

Trabajo con API V2

Configuración SDK

Procesamiento del resultado del pago

Registro de eventos

Trabajo con API V1

Configuración del SDK

Manejo del resultado del pago

Android

Integración Android

Conexión al proyecto Gradle mediante la adición de archivos .aar de la biblioteca

build.gradle.kts

build.gradle

Conexión al proyecto Gradle añadiendo archivos .aar de la biblioteca

build.gradle.kts

build.gradle

Trabajo con API V2

Configuración del SDK

Procesamiento del resultado del pago

Trabajo con API V1

Configuración del SDK

Procesamiento del resultado del pago

Pago a través de Google Pay con el módulo SDK Payment

Registro de eventos

Preguntas frecuentes

Contáctanos

¡Gracias!