Guía de integración para iOS

Para integrar el SDK de pago en su aplicación y realizar un pago, son necesarios 4 pasos:

En esta página también encontrará:

Con el fin de mejorar la eficacia de nuestro servicio de soporte, nuestro SDK puede enviar mensajes de Sentry a nuestros servidores cuando se presenta un problema o una situación inusual. En este caso, no se transfieren datos confidenciales ni datos de su aplicación.

Consultar nuestros ejemplos de integración

Encontrará varios ejemplos de códigos de integración de nuestro SDK en diferentes idiomas en el repositorio de Github

Añadir el SDK de pago a su aplicación

Existen varias maneras de integrar el SDK en un proyecto Xcode:

  1. Mediante CocoaPods

    Para integrar el SDK a su proyecto Xcode usando CocoaPods, indíquelo en su PodFile:

    target 'MyApp' do
    
     use_frameworks!
    
      pod 'LyraPaymentSDK'
    end
    

    A continuación, instálelo conpod update.

    Nota: de ahora en adelante, como lo indica la advertencia de la línea de comando, siempre debe abrir el proyecto con el archivo .xcworkspace y no con el archivo .xcodeproj. De lo contrario, se producirán errores de compilación.

  2. A través de Carthage

    Para integrar el SDK a su proyecto Xcode usando Carthage, indique en suCartfilelas dependencias necesarias para nuestro SDK:

    # Payment SDK Mobile dependencies
    github "CosmicMind/Material" == 2.16.4
    github "SnapKit/SnapKit" == 4.2.0
    github "getsentry/sentry-cocoa" "6.0.9"
    binary "https://raw.githubusercontent.com/lyra/sentry-client-cocoa/master/sentry_client_cocoa.json"
    
    
    # Your dependencies
    ...
    

    Nuestro SDK implementa elmodule stabilityde Swift 5.1 que permite la distribución de bibliotecas binarias. Dado que esta funcionalidad aún no está integrada en Carthage, no se puede agregar directamente nuestro SDK a suCartfile.module stabilityen Carthageaquí.

    A continuación, descargue la última versión de nuestro SDK desde https://github.com/lyra/ios-sdk/releases.

    Añada elLyraPaymentSDK.frameworka su proyecto iOS así como las dependencias indicadas en suCartfile.

Nota: sin importar de qué forma integre nuestro SDK, una vez que esté integrado a su proyecto, debe seleccionar la opción “Embed & Sign”.

Le recomendamos que actualice periódicamente el SDK de pago para asegurar un nivel de seguridad óptimo para sus pagos.

Para mantenerse informado de las nuevas versiones del SDK, consulte periódicamente nuestro repositorio de GitHub.

Inicializar el SDK

Como se menciona en el capítulo sobre el funcionamiento de la solución, es necesario inicializar el SDK cuando inicie su aplicación, generalmente con el método “didFinishLaunchingWithOptions” de su AppDelegate.

Para hacerlo, simplemente llame al métodoinitializecon los parámetros siguientes y tras la importación del frameworkimport LyraPaymentSDK:

Parámetro Formato Descripción
publicKey String Su clave pública (disponible en el Back Office del vendedor: Configuración->Tienda->Claves de API REST, ver la página Prerrequisitos).
options [String: Any] Diccionario que le permite configurar el comportamiento del SDK.

Ejemplo de llamada:

//Configure SDK options
var configurationOptions = [String : Any]()
configurationOptions[Lyra.apiServerName] = apiServerName

//Initialize Payment SDK
do {
    try Lyra.initialize(publicKey, configurationOptions)
} catch {

}
            
//Configure SDK options
NSMutableDictionary *configurationOptions = [[NSMutableDictionary alloc] init];
[configurationOptions setValue:apiServerName forKey:Lyra.apiServerName];

//Initialize Payment SDK
[Lyra initialize:publicKey :configurationOptions error:&error];
            

Las claves posibles en este diccionario son:

Claves Formato del valor Descripción Obligatorio
apiServerName String El nombre del servidor de la API REST (disponible en el Back Office del vendedor: Configuración >Tienda > Claves de API REST), ver la página Prerrequisitos). Obligatorio
cardScanningEnabled Bool Habilita/Deshabilita la funcionalidad de escaneo de la tarjeta, ver Habilitar la funcionalidad de escaneo de la tarjeta. Opcional

Atención: este método puede enviar un error si ha fallado la inicialización. Consulte la página Control de errores para resolver la situación. También debe tener en cuenta que el SDK no permite que se ejecuten múltiples procesos en paralelo. Durante el procesamiento de la primera llamada, las demás llamadas serán ignoradas (no habrá callbacks ni excepciones).

Realizar un pago

La realización de un pago se divide en 2 etapas: la inicialización de la visualización del formulario de pago y el procesamiento del pago en sí.

Inicialización de la visualización del formulario de pago

Cuando el usuario decide pagar, debe inicializar la visualización del formulario de pago.

Para ello, debe llamar a su servidor del vendedor para comprobar las compras del usuario y generar un identificador de formulario (llamado formToken) llamando al servicio web Charge/CreatePayment (desde su servidor del vendedor). En esta solicitud, debe pasar un parámetro formTokenVersion que corresponde al resultado del método getFormTokenVersion del SDK. A continuación, debe reenviar la respuesta del servicio web o el identificador del formulario a su aplicación móvil.

El siguiente código de ejemplo se basa en los ejemplos de código iOS y en el servidor del vendedor a su disposición.

  // 1. Init server comunication class for get createPayment context
  let serverCommunication = ServerCommunication()

  // 2. Execute getProcessPaymentContext for get the formToken (required param in SDK process method)
  serverCommunication.getPaymentContext { (getContextSuccess, formToken, error) in
    ...
    let objectResponse = json as? [String: Any]
    let serverResponse = objectResponse["answer"] as? [String: Any]
    let formToken = serverReponse["formToken"] as? String


  }

            
  // 1. Init server comunication class for get createPayment context
ServerCommunication *serverComunication = [[ServerCommunication alloc] init];

// 2. Execute getProcessPaymentContext for get the formToken (required param in SDK process method)
[_serverComunication getProcessPaymentContext:^(BOOL getContextSuccess, NSString *formToken, NSError* error) {
  ...
  NSDictionary *objectResponse = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
  NSDictionary *serverResponse = [objectResponse objectForKey:@"answer"];
  NSString* formToken = (NSString*)[serverResponse objectForKey:@"formToken"];

    }];

            

Importante: no llame al servicio web Charge/CreatePayment desde su aplicación móvil.

  • La validación del carrito es una etapa crucial: usted es responsable de comprobar en sus servidores que el monto corresponde al carrito antes de enviárnoslo.
  • Llamar al servicio web desde la aplicación móvil significa poner sus claves de llamadas a su disposición (y a disposición de posibles piratas informáticos), lo que va en contra de las normas de seguridad.

Visualización de la pantalla de pago

Una vez que la aplicación móvil haya recibido el formToken, debe transmitirlo a nuestro SDK de pago llamando el métodoprocesocon los parámetros siguientes y tras la importación del frameworkimport LyraPaymentSDK:

Parámetro Formato Descripción
contextViewController UIViewController Corresponde al ViewController de la aplicación cliente desde el cual se iniciará el proceso de pago.
formToken String El formToken, extraído de la respuesta del createPayment llamado anteriormente.
onSuccess LyraHandlerOnSuccess Llamada a la función callback si el pago se ha realizado sin problemas.
onError LyraHandlerOnError Llamada a la función callback si el pago no se pudo iniciar. Esta situación puede ocurrir si el pago ha sido rechazado o si se ha producido un error funcional o técnico durante el pago. Para más información, consulte: Control de errores.

El SDK se encarga de verificar la coherencia del formToken antes de mostrar los medios de pago disponibles.

Ejemplo de llamada:

  Lyra.process(self, formToken,
           onSuccess: { ( _ lyraResponse: LyraResponse) -> Void

          //Verify the payment using your server: Check the response integrity by verifying the hash on your server
          self.verifyPayment(lyraResponse)
  },
          onError: { (_ error: LyraError, _ lyraResponse: LyraResponse?) -> Void

          //TODO: Handle Payment SDK error in process payment request
          self.showMessage("Payment fail: \(error.errorMessage)")
  })

            
  [Lyra processWithContextViewController:self formToken: formToken onSuccess:^(LyraResponse *lyraResponse

      //Verify the payment using your server: Check the response integrity by verifying the hash on your server
      [self verifyPayment:lyraResponse];

  } onError:^(LyraError *lyraError, LyraResponse *lyraResponse) {

      //TODO: Handle Payment SDK error in process payment request
      [self showMessage: [NSString stringWithFormat:@"Payment fail: %@", lyraError.errorMessage]];

  } error:&error];

            

Descripción del objeto LyraResponse

El objeto LyraResponse se devuelve en ambos casos: onSuccess y onError. Es un objeto de tipo JSONObject. En caso de éxito, es necesario comprobar su integridad antes de mostrar el resultado del pago.

En caso de que la transacción haya sido iniciada por el lado del servidor, es posible obtener la información del pago de manera sencilla.

Ejemplo:

{
   "kr-hash":"80f5188e757c1828e8d4ccab87467eb50c4299e4057fa03b3f3185342f6d509c",
   "kr-hash-algorithm":"sha256_hmac",
   "kr-answer-type":"V4\/Payment",
   "kr-answer": "{
      "shopId":"65512466",
      "orderCycle":"CLOSED",
      "orderStatus":"PAID",
      "serverDate":"2019-03-01T10:54:45+00:00",
      "orderDetails":{
         "orderTotalAmount":1100,
         "orderEffectiveAmount":1100,
         "orderCurrency":"EUR",
         "mode":"TEST",
         "orderId":null,
         "_type":"V4\/OrderDetails"
      },
      "customer":{
         "billingDetails":{
            "address":null,
            "category":null,
            "cellPhoneNumber":null,
            ...
         },
         "email":null,
         "reference":null,
         "shippingDetails":{
            "address":null,
            "address2":null,
            "category":null,
            ...
         },
         "extraDetails":{
            "browserAccept":null,
            "fingerPrintId":null,
            "ipAddress":"77.136.84.251",
            "browserUserAgent":"{\"deviceName\":\"Xiaomi Mi MIX 2S\",\"os\":\"Android\",\"osVersion\":\"[9]\",\"sdkVersion\":28,\"isMobile\":true}",
            "_type":"V4\/Customer\/ExtraDetails"
         },
         "shoppingCart":{
            "insuranceAmount":null,
            "shippingAmount":null,
            "taxAmount":null,
            "cartItemInfo":null,
            "_type":"V4\/Customer\/ShoppingCart"
         },
         "_type":"V4\/Customer\/Customer"
      },
      "transactions":[
         {
            "shopId":"65512466",
            "uuid":"64d704a9bb664898954c3ef537982f99",
            "amount":1100,
            "currency":"EUR",
            "paymentMethodType":"CARD",
            "status":"PAID",
            "detailedStatus":"AUTHORISED",
            "operationType":"DEBIT",
            "creationDate":"2019-03-01T10:54:44+00:00",
            ...
         }
      ],
      "_type":"V4\/Payment"
   }"
}
            

La respuesta contiene los mismos elementos que los enviados en la IPN:

Parámetro Descripción
kr-hash Hash del objeto JSON almacenado en kr-answer. Así podrá confirmar la autenticidad de la respuesta
kr-hash-algorithm Algoritmo utilizado para calcular el hash
kr-hash-key Clave utilizada para firmar kr-answer
kr-answer-type Tipo del objeto JSON almacenado en kr-answer
kr-answer Objeto que contiene los objetos transacciones completos codificados en JSON

El objeto kr-answer contiene los elementos descritos aquí.

En algunos casos, puede que no se haya podido iniciar la transacción por el lado del servidor. Encontrará el error devuelto por la API en el json (cuyo formato encontrará aquí: Códigos de error ).

Verificar el estado de la transacción

Una vez el pago finalizado, haya sido aceptado o rechazado, se le notificará de dos maneras:

  • mediante una llamada (IPN) al servidor del vendedor, si este último está registrado en nuestra plataforma de pago,
  • mediante llamada de las callback onSuccess u onError por parte de la aplicación móvil.

Es necesario comprobar la integridad del mensaje (consulte aquí para obtener más detalles) e iniciar el procesamiento comercial del lado servidor (al recibir la IPN).

Nuestros ejemplos de código proporcionan un ejemplo de comprobación de la integridad de los mensajes a través de su servidor de vendedor: el endPoint verifyResult llamado en el método verifyResult de la aplicación.

El siguiente código de ejemplo se basa en los ejemplos de código iOS y en el servidor del vendedor a su disposición.

    func verifyPayment(_ lyraResponse: LyraResponse) {
        serverCommunication.verifyPayment(lyraResponse, onVerifyPaymentCompletion: { (paymentVerified, isConnectionError) in

            if paymentVerified {
                self.showMessage("Payment success")
            } else {
                self.showMessage("Payment verification fail")
            }
        })
    }
                
    - (void) verifyPayment:(LyraResponse*) lyraResponse  {
        [_serverComunication verifyPayment:lyraResponse withCompletion:^(BOOL paymentVerified, BOOL isErrorConnection) {
            if(paymentVerified)
                [self showMessage: @"Payment success"];
            else
                [self showMessage: @"Payment verification fail"];
        }];
    }
                

Personalizar el SDK

Se puede personalizar el SDK de modo que las vistas generadas desde el SDK (formulario de pago) se muestren en los mismos colores y la misma fuente que las utilizadas en su aplicación.

Puede definir:

  • un color principal,
  • un color secundario,
  • la fuente a utilizar en todos los textos que se muestran en el SDK.

El color principal permite modificar:

  • el color de fondo del encabezado,
  • el color de fondo del botón “Pagar”,
  • el color del mensaje de cierre de la ventana emergente de ayuda sobre el CVV,
  • el color del mensaje de cierre de la ventana emergente de ayuda sobre la elección de la marca,
  • el color de resalte y descripción del campo cuando se edita,
  • el color del texto en el mensaje de pago en curso,
  • el color del indicador giratorio en el mensaje de pago en curso.

El color secundario permite modificar:

  • El color del logotipo de la flecha de retroceso en el encabezado del SDK,
  • el color de los textos en el encabezado del SDK,
  • el color del texto en el botón “Pagar”.

Para personalizar el SDK de pago, simplemente añada un archivo PaymentSDkTheme.plist a su proyecto e indique en este archivo los colores a utilizar en código hexadecimal:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>PaymentSDKColor</key>
	<dict>
		<key>PaymentSDK_PrimaryColor</key>
		<string>#293C7A</string>
		<key>PaymentSDK_SecondaryColor</key>
		<string>#FFFFFF</string>
	</dict>
</dict>
</plist>

También se puede cambiar la fuente utilizada con la clavePaymentSDKFont.Atención:

Habilitar la funcionalidad de escaneo de la tarjeta

En el SDK, es posible habilitar la funcionalidad de escaneo de la tarjeta. Esta característica le evita al usuario tener que ingresar la información de la tarjeta manualmente, y en su lugar usar la cámara en su dispositivo móvil para escanearla y completar automáticamente el formulario de pago.

Para habilitar esta funcionalidad, debe:

  1. Integrar la biblioteca LyraCardsRecognizer en su proyecto Xcode

    1. Mediante CocoaPods

    Para integrar la biblioteca a su proyecto Xcode utilizando CocoaPods, indíquelo en su PodFile:

    target 'MyApp' do
      pod 'LyraCardsRecognizer', '~> 1.0.0'
    end
    

    A continuación, instálelo conpod update.

    1. A través de Carthage

    Para integrar la bibliotecaLyraCardsRecognizera su proyecto Xcode usando Carthage, indíquelo en suCartfile

    binary "https://raw.githubusercontent.com/lyra/ios-cards-camera-recognizer/master/LyraCardsRecognizer.json"
    

    Añada el archivoLyraCardsRecognizer.frameworka su proyecto iOS.

  2. Al inicializar el SDK, envíe true como valor para la clave cardScanningEnabled en el diccionario de las opciones de configuración (consulte Inicialización del SDK).

     //Active card scan
     configurationOptions[Lyra.cardScanningEnabled] = true
                 
     //Active card scan
     [configurationOptions setValue:[NSNumber numberWithBool:true] forKey:Lyra.cardScanningEnabled];
                 
  3. En el archivo Info.plist de su aplicación, añada la clave NSCameraUsageDescription y describa la razón para usar la cámara.

Derechos de autor