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:
- Añadir el SDK de pago a su aplicación
- Inicializar el SDK
- Realizar un pago
- Verificar el estado de la transacción
En esta página también encontrará:
- Consultar nuestros ejemplos de integración
- Personalizar el SDK
- Cancelar un pago en curso
- Habilitar la funcionalidad de escaneo de la tarjeta
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:
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 con
pod update
.
A través de Carthage
Para integrar el SDK en su proyecto Xcode usando Carthage, indique en su
Cartfile
las dependencias necesarias para nuestro SDK:# Payment SDK Mobile & dependencies github "CosmicMind/Material" == 3.1.8 github "CosmicMind/Motion" == 3.1.3 github "SnapKit/SnapKit" == 5.6.0 github "getsentry/sentry-cocoa" "8.13.0" binary "<https://raw.githubusercontent.com/lyra/ios-sdk/2.6.5/LyraPaymentSDK.json>" == 2.6.5 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 ...
Dans le Cartfile
assurez-vous de remplacer le numéro de la version de LyraPaymentSDK par le numéro de la dernière version publiée sur notre repository GitHub
Ajoutez le LyraPaymentSDK.xcframework
à votre projet iOS ainsi que les autres dépendances spécifiées dans votre Cartfile
.
Nous vous recommandons de mettre à jour régulièrement le SDK de paiement, afin de garantir une sécurité optimale de vos paiements.
Para mantenerse informado de las nuevas versiones del SDK, consulte periódicamente nuestro repositorio de GitHub<.
Inicializar el SDK
Comme mentionné 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.
Pour cela, il suffit d'appeler la méthode ,initialize
, avec les paramètres suivants et après avoir importé le framework import LyraPaymentSDK
, :
CARACTERÍSTICAS | Formato | Descripción |
---|---|---|
publicKey | String | Votre clé publique (disponible dans le |
options | [String: Any] | Diccionario que le permite configurar el comportamiento del SDK. |
{: .lita-excluded-col1 .lita-excluded-col2 } Exemple d'appel :
//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 | Votre nom du serveur de l'API REST (disponible dans le | 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
Une fois le formToken reçu dans l'application mobile, vous devez le transmettre à notre SDK de paiement en appelant la méthode ,process
, avec les paramètres suivants et après avoir importé le 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
Il est aussi possible de personnaliser certains textes. Pour cela, spécifier le paramètre optionnel "options" lors de l'appel au Lyra.process()
.
Botón PAGAR
- El texto del botón PAGAR puede personalizarse.
Especifique la clave Lyra.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 <orderIdest précisé alors, on continuera à afficher sa valeur. Exemple : "Commande CM-12345".
Especifique la clave Lyra.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 Lyra.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)") }, [Lyra.customPayButtonLabel: "MyPayButtonLabel", Lyra.customHeaderLabel: "MyHeaderLabel", Lyra.customPopupLabel: "MyPopupLabel"])
Cancelar un pago en curso
Il est possible d'annuler un paiement en cours en utilisant la méthode Lyra.cancelProcess()
. En général, cette méthode permet de quitter correctement le formulaire de paiement mais il existe différents scénarios :
El proceso de pago puede cancelarse:
- el formulario de pago se cierra correctamente.
- el
handler onError
qui est passé auLyra.process()
est appelé avec l'erreurMOB_009 - Payment cancelled, indiquant que le processus de paiement a été annulé.
Le processus de paiement ne peut pas être annulé. Si le
Lyra.cancelProcess()
est invoqué pendant que le SDK est en communication avec la plateforme de paiement (l'utilisateur vient de cliquer sur le bouton payer) :- el formulario de pago permanece en pantalla.
- el
handler onError
qui est passé auLyra.process()
est appelé avec l'erreurMOB_013 - Payment cannot be cancelled, indiquant que le processus de paiement ne peut pas être annulé. - el comportamiento normal del SDK continúa:
- si le paiement se termine correctement alors le
handler onSuccess
sera appelé. - si le paiement est en échec. Suivant l'erreur, le formulaire de paiement reste affiché ou le
handler onError
sera appelé.
- si le paiement se termine correctement alors le
S'il n'y a pas de processus de paiement en cours, l'appel au
Lyra.cancelProcess()
n'aura aucun effet.
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:
Intégrer la librairie LyraCardsRecognizer dans votre projet Xcode
Mediante CocoaPods
Para integrar la biblioteca a su proyecto Xcode utilizando CocoaPods, indíquelo en su PodFile:
target 'MyApp' do pod 'LyraCardsRecognizer' end
A continuación, instálelo con
pod update
.A través de Carthage
Pour intégrer la librairie ,LyraCardsRecognizer, dans votre projet Xcode en utilisant Carthage, indiquez-le dans votre
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.
Lors de l'initialisation du SDK, envoyez true comme valeur à la clé
cardScanningEnabled
dans le dictionnaire des options de configuration (Voir Initialiser le SDK).
//Active card scan configurationOptions[Lyra.cardScanningEnabled] = true
//Active card scan [configurationOptions setValue:[NSNumber numberWithBool:true] forKey:Lyra.cardScanningEnabled];
- Dans le fichier
Info.plist
de votre application, ajoutez la cléNSCameraUsageDescription
et décrivez la raison de l'utilisation de la caméra.