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á:

Para optimizar el análisis cuando sea necesario, nuestro SDK puede enviar mensajes Sentry a nuestros servidores cuando surge una situación o problema inusual. En este caso no se transfieren datos sensibles ni ningún dato 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:

Vía CocoaPods

Para integrar el SDK en su proyecto Xcode usando CocoaPods:
- Indique el SDK en su Podfile:
```
target 'MyApp' do

 use_frameworks!

  pod 'LyraPaymentSDK'
end
```
- Luego instale el SDK conpod update.

Vía Carthage

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

# Payment SDK Mobile & dependencies
binary "https://raw.githubusercontent.com/lyra/Material/1.0.5/LyraMaterial.json" == 1.0.5
binary "https://raw.githubusercontent.com/lyra/Motion/4.0.1/LyraMotion.json" == 4.0.1
github "SnapKit/SnapKit" == 5.6.0
github "getsentry/sentry-cocoa" "8.13.0"
binary "https://raw.githubusercontent.com/lyra/ios-sdk/2.6.7/LyraPaymentSDK.json>" == 2.6.7
binary "https://raw.githubusercontent.com/lyra/sentry-client-cocoa/4.0.0/sentry_client_cocoa.json" == 4.0.0
binary "https://raw.githubusercontent.com/lyra/ios-cards-camera-recognizer/2.0.1/LyraCardsRecognizer.json" == 2.0.1

# Your dependencies

...

En el Cartfile asegúrese de reemplazar el número de versión de LyraPaymentSDK por el número de la última versión publicada en nuestro repositorio de GitHub

Agregue LyraPaymentSDK.xcframework a su proyecto de iOS junto con las otras dependencias especificadas en su Cartfile.

Le recomendamos que actualice el SDK de pago periódicamente para garantizar una seguridad óptima de sus pagos.

Para estar informado de las nuevas versiones del SDK, puedes consultar periódicamente nuestro repositorio de GitHub.

Inicializar el SDK

Comme indiqué dans le chapitre sur le fonctionnement de la solution , il est nécessaire d'effectuer l'initialisation du SDK au lancement de votre application, typiquement dans la méthode didFinishLaunchingWithOptions de votre AppDelegate.

Para hacer esto, simplemente llame al método initialize, con los siguientes parámetros y luego de importar el framework import LyraPaymentSDK, :

CARACTERÍSTICAS	Formato	Descripción
publicKey	String	Su clave pública (disponible en bom: Configuración > Tienda > Claves API REST; consulte la página Requisitos previos ).
options	[String: Any]	Diccionario que le permite configurar el comportamiento del SDK.

Ejemplo de llamada :

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

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

}

//Configure SDK options
NSMutableDictionary *configurationOptions = [[NSMutableDictionary alloc] init];
[configurationOptions setValue:apiServerName forKey:LyraInitOptions.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 de su servidor API REST (disponible en bom: Configuración > Tienda > Claves API REST), cf. página Requisitos previos ).	OBLIGATORIO
cardScanningEnabled	Bool	Activa/desactiva la función de escaneo de mapas, véase Activar la función de escaneo de tarjetas.	Opcional

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.

Pour cela, vous devez appeler votre serveur marchand, pour y vérifier les achats de l'utilisateur, puis générer un identifiant de formulaire (appelé formToken) en appelant le Web Service Charge/createPayment (toujours depuis votre serveur marchand). Dans cette requête, vous devez passer un paramètre formTokenVersion qui correspond au résultat de la méthode getFormTokenVersion du SDK. La réponse du Web Service ou cet identifiant de formulaire doit ensuite être renvoyé à votre application mobile.

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"];

    }];

La etapa de validación del carrito es una etapa crucial, y es su responsabilidad verificar en sus servidores que el monto corresponde bien al carrito antes de enviárnoslo
Llamar al Web Service 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 recibido el formToken en la aplicación móvil, deberá pasarlo a nuestro SDK de pago llamando al método process, con los siguientes parámetros y luego de importar el framework import LyraPaymentSDK, :

CARACTERÍSTICAS	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 saber más, consulte el capítulo . Manejo 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 los dos casos: onSuccess y onError. Es un objeto de tipo JSON Object. 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:

CARACTERÍSTICAS	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 contenido 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 del lado del servidor. El error devuelto por la API se encuentra en el JSON (consulte el formato 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:

para una llamada (IPN) al servidor de 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.

Se recomienda verificar todo el mensaje (consulte aquí para más información) e iniciar los procesamientos automatizados 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

Tema

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

Textos

También es posible personalizar determinados textos. Para hacer esto, especifique el parámetro opcional "options" al llamar al Lyra.process().

Botón PAGAR

El texto del botón PAGAR puede personalizarse.

Especifique la clave LyraPaymentOptions.customPayButtonLabel.

Cabecera

Si le texte est forcé et qu'il n'y a pas d'orderId, il remplacera le texte par défaut qui est "Paiement" ou "Enregistrement de la carte".
Par contre, si un <orderId est précisé alors, on continuera à afficher sa valeur. Exemple : "Commande CM-12345".

Especifique la clave LyraPaymentOptions.customHeaderLabel.

Ventana de pago

También se puede personalizar el texto de la ventana emergente que se abre al pulsar el botón PAGAR.

Especifique la clave LyraPaymentOptions.customPopupLabel.

        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)")
          }, [LyraPaymentOptions.customPayButtonLabel: "MyPayButtonLabel", LyraPaymentOptions.customHeaderLabel: "MyHeaderLabel", LyraPaymentOptions.customPopupLabel: "MyPopupLabel"])

Métodos de pago ofrecidos

De forma predeterminada, la llamada a Lyra.process() ofrece todos los métodos de pago disponibles. Sin embargo, es posible modificar este comportamiento para ofrecer un método de pago específico utilizando el parámetro opcional "options". Para eso:

Especifique la claveLyraPaymentOptions.paymentMethodType.
Usa la enumeraciónLyraPaymentMethodspor el valor:

cardPayment: el formulario de pago con tarjeta lo presenta el SDK.
applePay: la pantalla de pago a través de ApplePay la presenta el SDK.
todos: si hay varios métodos de pago, se presenta la pantalla de selección de método de pago. En caso contrario se muestra el formulario de pago con tarjeta. Este valor corresponde al mismo comportamiento que la llamada aLyra.process()sin la llaveLyraPaymentOptions.paymentMethodTypeen el parámetro "options".

Cancelar un pago en curso

Es posible cancelar un pago en curso utilizando el método Lyra.cancelProcess(). En general, este método sale correctamente del formulario de pago, pero existen diferentes escenarios:

El proceso de pago puede cancelarse:
- el formulario de pago se cierra correctamente.
- elhandler onErrorquien pasó aLyra.process()se llama con el errorMOB_009 - Payment cancelled, indicando que el proceso de pago ha sido cancelado.
El proceso de pago no se puede cancelar. Si se invoca Lyra.cancelProcess() mientras el SDK está en comunicación con la plataforma de pago (el usuario acaba de hacer clic en el botón de pago):
- el formulario de pago permanece en pantalla.
- elhandler onErrorquien pasó aLyra.process()se llama con el errorMOB_013 - Payment cannot be cancelled, indicando que el proceso de pago no se puede cancelar.
- el comportamiento normal del SDK continúa:
  - si el pago se completa correctamente, entonces elhandler onSuccesssera llamado.
  - si el pago no tiene éxito. Dependiendo del error, el formulario de pago permanece mostrado o elhandler onErrorsera llamado.
Si no hay ningún proceso de pago en curso, llamar a Lyra.cancelProcess() no tendrá ningún efecto.

Habilitar la funcionalidad de escaneo de la tarjeta

Es posible, en el SDK, activar la función de escaneo de tarjetas. Esta función permite al usuario no ingresar manualmente la información de su tarjeta, sino usar la cámara de su dispositivo móvil para escanearla y completar automáticamente el formulario de pago.

Para habilitar esta funcionalidad, debe:

Integre la biblioteca LyraCardsRecognizer en su proyecto Xcode:
1. . Vía CocoaPods
  
  Para integrar la biblioteca en tu proyecto Xcode usando CocoaPods, indícalo en tu Podfile:
```
target 'MyApp' do
pod 'LyraCardsRecognizer'
end
```
  Luego instálelo con pod update.
2. A través de Carthage
  
  Para integrar la biblioteca,LyraCardsRecognizer, en tu proyecto Xcode usando Carthage, indícalo en tu Cartfile, :
```
binary "https://raw.githubusercontent.com/lyra/ios-cards-camera-recognizer/2.0.0/LyraCardsRecognizer.json" == 2.0.0
```
  Agregue el archivo LyraCardsRecognizer.xcframework a su proyecto de iOS.
Al inicializar el SDK, envíe true como valor a la clave cardScanningEnabled en el diccionario de opciones de configuración (consulte Inicializar SDK ).

    //Active card scan
    configurationOptions[LyraInitOptions.cardScanningEnabled] = true

    //Active card scan
    [configurationOptions setValue:[NSNumber numberWithBool:true] forKey:LyraInitOptions.cardScanningEnabled];

En el archivoInfo.plistde su aplicación, agregue la claveNSCameraUsageDescriptiony describa el motivo por el que utiliza la cámara.

Categoria

Tags