Saltar al contenido principal

Integración con iOS

Esta guía proporciona información técnica detallada sobre la integración del SDK en una aplicación iOS. Asegúrese de seguir los pasos y consideraciones que se mencionan a continuación para lograr una integración exitosa.

Paso 1: Descargar el SDK​

  1. Descarga el archivo SDK aquí

  2. Una vez en el enlace, haz clic en el botón de descarga para obtener el archivo del SDK en formato comprimido.

  3. Descomprime el archivo descargado en una ubicación de tu elección en tu máquina de desarrollo.

Paso 2: Integración del SDK en tu proyecto​

Para integrar el SDK en el proyecto de la aplicación, siga estos pasos técnicos:

  • Agregue el archivo .framework del SDK al proyecto de la aplicación arrastrándolo y soltándolo en la estructura del proyecto.

  • Acceda a la configuración del comercio en la pestaña "General" y localice el apartado "Frameworks, Libraries, Embedded content" (el nombre puede variar según la versión de Xcode).

  • En ese apartado, modifique el flag Embed del SDK a "Embed & Sign".

Al seguir estos pasos, el SDK se integrará correctamente en el proyecto de la aplicación, lo que permitirá utilizar sus funcionalidades y características en la implementación.

Paso 3: Configuración en el controlador de la pantalla​

Para agregar funcionalidad al controlador de la pantalla que mostrará el formulario, se debe incluir la siguiente línea de código al comienzo del archivo:

import UIKit
import IzipayPayButtonSDK
import RLTMXProfiling
import RLTMXProfilingConnections

class ViewController: UIViewController {}

Paso 4: Crear el objeto de configuración​

Para crear un objeto del tipo ConfigPaymentIzipay con los datos del comercio, la orden y el usuario, se debe seguir el siguiente código:


let config = ConfigPaymentIzipay()

func initializeConfigPayment() -> ConfigPaymentIzipay {

    var config = ConfigPaymentIzipay()

        /*...
            -- ¡Recuerda siempre inicializar cualquier objeto antes de asignarle valores!
            var config = ConfigPaymentIzipay()
        ...*/

        config.enviroment = "TEST"
        config.merchantCode = "<CODIGO DE COMERCIO>"

        config.publicKey = "<public key>"

        config.transactionId = "TEST"
        config.action = "TEST"

        config.order = OrderPaymentIzipay()
        config.order?.orderNumber = "TEST"
        config.order?.amount = "1.00"
        config.order?.currency = "PEN"
        config.order?.channel = "mobile"
        config.order?.processType = "autorize"
        config.order?.payMethod = "card"
        config.order?.merchantBuyerId = "123456"
        //...
        config.billing = BillingPaymentIzipay()
        config.billing?.firstName = "Jose"
        config.billing?.lastName = "Perez"
        config.billing?.email = "jperez@itest.com"
        config.billing?.phoneNumber = "958745896"
        config.billing?.street = "Av. Jorge Chávez 275"
        config.billing?.city = "Lima"
        config.billing?.state = "Lima"

        //...
        config.shipping = ShippingPaymentIzipay()
        config.shipping?.firstName = "Juan"
        config.shipping?.lastName = "Wick"
        config.shipping?.email = "jwickq@izi.com"

        //...
        config.token = TokenPaymentIzipay()
        config.token?.cardToken = cardtoken

        config.appearance = AppearencePaymentIzipay()
        config.appearance?.theme = "green"
        config.appearance?.logo = "URL"
        config.appearance?.formControls =AppearenceControlsPaymentIzipay()
        config.appearance?.formControls?.isAmountLabelVisible = true
        config.appearance?.formControls?.isLangControlVisible = true
        config.appearance?.language = language
        config.appearance?.customTheme = CustomThemePaymentIzipay()

        config.urlIPN = "URL"
}
Consejo Importante

¡Recuerda siempre inicializar cualquier objeto antes de asignarle valores!

Por ejemplo:


var config = ConfigPaymentIzipay()

¡Asegúrate de seguir este paso para una integración sin problemas!


En este código, se crea una instancia de ConfigPaymentIzipay y se asignan los valores correspondientes a las propiedades commerceId, orderId y userId. Esos valores deben ser proporcionados según los datos del comercio, la orden y el usuario en el contexto de la integración. Una vez creado el objeto config, se podrá utilizar para realizar las operaciones de pago y procesamiento necesarias en la aplicación.

A continuación, se debe agregar el siguiente código para mostrar el formulario:

 func showIzipayPaymentResult(configPayment: ConfigPaymentIzipay) {
        let s = UIStoryboard(name: "IziPayment", bundle: Bundle(for: PaymentFormViewController.self))
        let vc = s.instantiateViewController(withIdentifier: "PaymentFormView") as! PaymentFormViewController
        vc.delegate = self
        vc.configPayment = configPayment
        self.present(vc, animated: true, completion: nil)
    }

Modos de visualización​

Actualmente el SDK cuenta con dos modos de visualización:

  • Modo FullScreen

Para habilitar la funcionalidad de pantalla completa en el SDK, es necesario configurar el campo appearance.visualSettings.presentationMode con el valor 'fullScreen'. A continuación, simplemente debes incluir el siguiente código para activar la visualización del formulario en modo de pantalla completa.

 func showIzipayPaymentResult(configPayment: ConfigPaymentIzipay) {
        // Código anterior de showIzipayPaymentResult ...
        vc.modalPresentationStyle = .fullScreen
        self.present(vc, animated: true, completion: nil)
    }
  • Modo Embebido

Para habilitar el modo embebido en el SDK, es necesario configurar el campo appearance.visualSettings.presentationMode con el valor 'embedded'. A continuación, deberás crear un ViewContainer en el ViewController que alojará el SDK.

@IBOutlet weak var viewContainer: UIView!

La siguiente imagen ilustra cómo se realizaría esta acción al agregar un ViewContainer en un ViewController que está incrustado en un NavigationController.

UIViewUIView

A continuación te mostramos un ejemplo de como invocar el SDK:

  func showIzipayPaymentEmbedded(){
        let s = UIStoryboard(name: "IziPayment", bundle: Bundle(for: PaymentFormViewController.self))
        let vc = s.instantiateViewController(withIdentifier: "PaymentFormView") as! PaymentFormViewController
        vc.delegate = self
        vc.configPayment = self.configIzipay
        addChild(vc)
        vc.view.frame = viewContainer.bounds
        viewContainer.addSubview(vc.view)
        vc.didMove(toParent: self)
    }

Finalmente se invoca al método desde el método viewDidLoad (que existe en todas las clases que descienden de la clase UIViewController)

    override func viewDidLoad() {
        super.viewDidLoad()
        self.showIzipayPaymentResultEmbedded()
    }
importante

  • Este paso de integración es solo un ejemplo en el contexto de utilizar un ViewController embebido en un NavigationController. La clave para la integración en modo embebido radica en ajustar el método showIzipayPaymentEmbedded según los requisitos específicos. Se recomienda su uso solo con conocimientos avanzados en iOS, dada la necesidad de comprender los ciclos de vida de los ViewController y las transiciones entre ellos.

  • Se aconseja asignar un viewcontainer que ocupe todo el ancho de la pantalla y tenga una altura mínima del 80% de la altura de la pantalla, considerando la orientación vertical. Medidas inferiores podrían provocar que el SDK se muestre demasiado pequeño o incorrectamente desde el punto de vista visual.

Paso 5: Agregar los métodos del delegate​

Para completar la integración, es necesario agregar los métodos del delegado IzipayPaymentDelegate. En el método getPaymentResult, se recomienda agregar una implementación similar a la siguiente:

extension ViewController : IzipayPaymentDelegate {

    func getPaymentResult(_ paymentResult: PaymentResult) {

        //Lectura de respuesta del SDK
        print(paymentResult.code ?? "")
        print(paymentResult.message ?? "")

        if let paymentResultCode = paymentResult.code {
            if paymentResultCode == "00" { 00 codigo operacion autorizada - Revisar listado de codigos de respuesta
                //puede validar los demas valores para garantizar la integridad de los datos
                if let safeResponse = paymentResult.response {
                    //puede validar los demas valores para garantizar la integridad de los datos o simplemente leerlos
                } else {
                    //Si el codigo fue 00 pero el objeto response es nulo, consultar/anular orden
                }
            } else {
                //La operacion no se completo o fue rechazada consultar/anular orden
            }
        } else {
            //Si no hay un codigo de error, consultar/anular orden
        }
    }
}

En este código, el método getPaymentResult es invocado por el SDK de Izipay para proporcionar el resultado de la transacción. Dentro de este método, se pueden realizar acciones personalizadas según el resultado, como mostrar un mensaje de confirmación o procesar los datos recibidos.

Es importante revisar los JSON proporcionados en la sección Casos de uso para comprender la estructura de los datos de respuesta y realizar una lectura adecuada de los mismos.

Importante

En el modo embebido, este método también actúa como una notificación de la acción final del SDK. Debe utilizarse como punto de partida para cerrar el SDK. Si no se cierra el SDK al ejecutar este método, ya sea cerrando el ViewController, eliminando el ViewContainer que actúa como contenedor del SDK u otra acción similar, el SDK seguirá activo.

En relación al segundo método, executeProfiling, déjelo vacío. La implementación de este método solo se realiza si se desea utilizar la función de detección de fraude. Para obtener más detalles sobre los pasos requeridos, consulte el capítulo Integración con Cybersource.

func executeProfiling(_ result: IzipayPayButtonSDK.ScoringParams) {

}

Paso 6: Agregar fuente de letra​

Importante

De no agregar este código, los formularios dentro del SDK se verán con estilos de texto más simples.

Agregar el siguiente código en el AppDelegate en el método didFinishLaunchingWithOptions

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
       
        UIFont.registerFontsForIzipayFramework() //Agregar fuentes al SDK
            
        return true
    }

Paso 7: Integración con librerías de Sensory Branding​

Importante

La incorporación de las bibliotecas de Sensory Branding es un requisito obligatorio en el proceso de integración. Estas bibliotecas son funcionalidades optimizadas para iOS 13 y versiones posteriores. Sin embargo, en caso de que su aplicación móvil esté diseñada para versiones más antiguas de iOS, como iOS 11 o iOS 12, no se anticipan inconvenientes, aunque las bibliotecas no se ejecutarán en esos casos.

Para la funcionalidad de sensory branding, primero importa las bibliotecas al proyecto:

  • Agrega las bibliotecas MastercardSonic y VisaSensoryBranding al proyecto de la aplicación.
  • Arrastra los archivos .xcframework al proyecto.
  • En la configuración del comercio, en la pestaña General, ve a la sección Frameworks, Libraries, Embedded Content (el nombre de la sección puede variar según la versión de Xcode).
  • Cambia la marca Embed de las bibliotecas a Embed & Sign.

Agregar las siguientes líneas de código en el archivo donde se realiza el llamado al SDK de Izipay.

  • Añadir los siguientes imports.
import IzipayPayButtonSDK
…
import VisaSensoryBranding
import MastercardSonic
  • Agregar la siguiente variable. (se recomienda que sea como variable de clase)
private let sonicManager: MCSonicController = MCSonicController()

Dentro del método que crea el objeto de configuración (visto en el paso 4) agregar las siguientes lineas de codigo

…
        //Objetos para sensory branding
        let sensoryBrandingVisa = SensoryBranding()
        sensoryBrandingVisa.backdropColor = .white
        sensoryBrandingVisa.isSoundEnabled = true
        sensoryBrandingVisa.isHapticFeedbackEnabled = true
        sensoryBrandingVisa.checkmarkMode = .checkmark

       let sensoryBrandMastercard = MCSonicView()
        sensoryBrandMastercard.background = MCSonicBackground.white

        config.appearance?.sensoryBrand = AppearenceSensoryBrandIzipay()
        config.appearance?.sensoryBrand?.visaSBView = sensoryBrandingVisa
        config.appearance?.sensoryBrand?.mastercardSBView = sensoryBrandMastercard
       …

Agregar las siguientes implementaciones en los métodos executeSensoryBrandVisa y executeSensoryBrandMastercard del delegado IzipayPaymentDelegate

  func executeSensoryBrandVisa(view: UIView) {
        if let visaview = view as? SensoryBranding {
            DispatchQueue.main.asyncAfter(deadline: .now() + 1.0) {
                visaview.animate()
            }
        }
    }

    func executeSensoryBrandMastercard(view: UIView, params: MastercardSonicParams) {
        let merchant = MCSonicMerchant(merchantName: params.name, countryCode: params.country,
                                       city: nil, merchantCategoryCodes: [params.mcc], merchantId: nil)
        if let mastercardview = view as? MCSonicView, let safeMerchant = merchant {
            self.sonicManager.prepare(with: .soundAndAnimation, sonicCue: params.sonicCue,
                                      sonicEnvironment: .production, merchant: safeMerchant) { status in
                if status == .success {
                    self.sonicManager.play(with: mastercardview) { MCSonicStatus in
                        print(MCSonicStatus)
                    }
                }
            }
        }
    }
Nota

Si al probar desde Testflight o el App Store no se ven las animaciones de las librerías. Desactivar la opción Manage Version and Build Number al momento de subir un build al App Store Connect.

(*) Abrir imagen para más detalles.

Paso 8: Integración de Apple Pay​

Importante

Este paso solo es aplicable únicamente cuando se emplea Apple Pay. Si desea obtener detalles adicionales sobre Apple Pay, le invitamos a visitar esta sección.

Para usar Apple Pay en el SDK de Izipay, en la configuración del proyecto se debe de agregar el siguiente Capability (botón + Capability en la imagen):

(*) Abrir imagen para más detalles.

Cuando se haya agregado correctamente, en la lista de Capabilities se mostrará la opción Apple Pay

(*) Abrir imagen para más detalles.

Una vez que haya realizado la adición, el sistema recuperará un listado de los merchantId que estén vinculados a su cuenta de Apple Developer. A continuación, deberá seleccionar el merchantId correspondiente en el portal de comercios de Izipay.

(*) Abrir imagen para más detalles.
Última actualización en