Guide d'integration iOS

Pour intégrer le SDK de paiement à votre application et réaliser un paiement, 4 étapes sont nécessaires :

Sur cette page vous pouvez trouver aussi :

Afin d'optimiser l'analyse en cas de besoin, notre SDK peut envoyer des messages Sentry vers nos serveurs lorsqu'une situation inhabituelle ou un problème survient. Dans ce cas, aucune donnée sensible n'est transférée ni aucune donnée de votre application.

Consulter nos exemples d'intégration

Vous trouverez de nombreux exemples de codes d'intégration de notre SDK dans différents langages dans le dépôt Github

Ajouter le SDK de paiement à votre application

Il existe différentes façons d'intégrer le SDK dans un projet Xcode :

Via CocoaPods

Pour intégrer le SDK dans votre projet Xcode à l'aide de CocoaPods :
- Indiquez le SDK dans votre Podfile :
```
target 'MyApp' do

 use_frameworks!

  pod 'LyraPaymentSDK'
end
```
- Puis installez le SDK avec pod update.

Via Carthage

Pour intégrer le SDK dans votre projet Xcode en utilisant Carthage, indiquez dans votre Cartfile les dépendances nécessaires à notre SDK :

# Payment SDK Mobile & dependencies
binary "https://raw.githubusercontent.com/lyra/Material/1.0.6/LyraMaterial.json" == 1.0.6
binary "https://raw.githubusercontent.com/lyra/Motion/4.0.2/LyraMotion.json" == 4.0.2
github "SnapKit/SnapKit" == 5.7.1
github "getsentry/sentry-cocoa" "8.36.0"
binary "https://raw.githubusercontent.com/lyra/ios-sdk/2.7.4/LyraPaymentSDK.json>" == 2.7.4
binary "https://raw.githubusercontent.com/lyra/sentry-client-cocoa/4.0.2/sentry_client_cocoa.json" == 4.0.2
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.

Pour être informé des nouvelles versions du SDK, vous pouvez consulter régulièrement notre repository GitHub.

Initialiser le 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.

Pour cela, il suffit d'appeler la méthode initialize avec les paramètres suivants et après avoir importé le framework import LyraPaymentSDK :

Paramètre	Format	Description
publicKey	String	Votre clé publique (disponible dans le Back Office Marchand : Paramètres > Boutique > Clés de l’API REST, cf. la page Prérequis).
options	[String: Any]	Dictionnaire qui vous permet de configurer le comportement du SDK.

{: .lita-excluded-col1 .lita-excluded-col2 } Exemple d'appel :

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

Les clés possibles dans ce dictionnaire sont :

Clés	Format valeur	Description	Requis
apiServerName	String	Votre nom du serveur de l’API REST (disponible dans le Back Office Marchand : Paramètres > Boutique > Clés de l’API REST), cf. la page Prérequis).	Requis
cardScanningEnabled	Bool	Active/Désactive la fonctionnalité de scan de la carte, cf. Activer la fonctionnalité de scan de la carte.	Optionnel

Il faut aussi noter que le SDK ne permet pas de faire plusieurs process en parallèle. Durant le traitement du premier appel, les autres appels seront ignorés (pas de callback, pas d'exception).

Réaliser un paiement

La réalisation d'un paiement se décline en 2 étapes : l'initialisation de l'affichage du formulaire de paiement, et le traitement du paiement proprement dit.

Initialisation de l'affichage du formulaire de paiement

Lorsque l'utilisateur décide de payer, vous devez initialiser l'affichage du formulaire de paiement.

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.

Voici un code exemple se basant sur les exemples de code iOS et le serveur marchand mis à votre disposition.

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

    }];

L'étape de validation du panier est une étape cruciale, et il vous revient de vérifier sur vos serveurs que le montant correspond bien au panier avant de nous le transmettre,
Appeler le Web Service depuis l'application mobile revient à mettre à sa disposition (et à des pirates potentiels) vos clés d'appels, ce qui est contraire aux règles de sécurité.

Affichage de l'écran de paiement

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 :

Paramètre	Format	Description
contextViewController	UIViewController	Correspond au ViewController de l'application client à partir duquel le processus de paiement sera lancé.
formToken	String	Le formToken, extrait de la réponse du createPayment précédemment appelé.
onSuccess	LyraHandlerOnSuccess	Fonction de callback appelée si le paiement s'est déroulé correctement.
onError	LyraHandlerOnError	Fonction de callback appelée si le paiement est en échec ou n'a pu être initié. Cette situation peut se produire si le paiement a été refusé ou si une erreur fonctionnelle ou technique est survenue pendant le paiement. Pour en savoir plus consulter : Gestion des erreurs.

Le SDK se charge alors de vérifier la cohérence du formToken puis affiche les moyens de paiements disponibles.

Exemple d'appel :

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

Description de l'objet LyraResponse

L'objet LyraResponse est retourné dans les deux cas : onSuccess et onError. C'est un objet de type JSON Object. En cas de succès, il est nécessaire de vérifier son intégrité avant d'afficher le résultat du paiement.

Dans le cas où la transaction a été initiée côté serveur, il sera possible de récupérer simplement les informations du paiement.

Exemple :

{
   "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 réponse contient les mêmes éléments que ceux envoyés dans l'IPN :

Paramètre	Description
kr-hash	Hash de l'objet JSON stocké dans kr-answer. Il permet de vérifier l'authenticité de la réponse
kr-hash-algorithm	Algorithme utilisé pour calculer le hash
kr-hash-key	Clé utilisée pour signer kr-answer
kr-answer-type	Type de l'objet JSON contenu dans kr-answer
kr-answer	Objet contenant les objets transactions complets encodés en JSON

L'objet kr-answer contient les éléments décrits ici.

Dans certains cas, il se peut que la transaction n'ait pu être initiée côté serveur. Il sera possible de retrouver l'erreur renvoyée par l'API dans le json (vous trouverez le format ici : Codes d'erreur ).

Vérifier le statut de la transaction

Une fois le paiement terminé, qu'il soit accepté ou refusé, vous serez notifié de 2 manières :

par un appel (IPN) vers votre serveur marchand, si ce dernier est enregistré auprès de notre plateforme de paiement,
par l'appel des callback onSuccess ou onError côté application mobile.

Il est nécessaire de vérifier l'intégrité du message (voir ici pour plus de détails), et de lancer les traitements métiers côté serveur (lors de la réception de l'IPN).

Nos exemples de code fournissent un exemple de contrôle d'intégrité du message via votre serveur marchand, il s'agit du endPoint verifyResult appelé dans la méthode verifyResult de l'application.

Voici un code exemple se basant sur les exemples de code iOS et le serveur marchand mis à votre disposition.

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

Personnaliser le SDK

Thème

Il est possible de personnaliser le SDK, de sorte que les vues générées à partir du SDK (formulaire de paiement) soient affichées avec les mêmes couleurs et la même police que celles utilisées dans votre application.

Vous pouvez définir :

une couleur principale,
une couleur secondaire,
la police à utiliser sur l'ensemble des textes affichés dans le SDK.

La couleur principale permet de modifier :

la couleur de fond de l'entête,
la couleur de fond du bouton "Payer",
la couleur de mot de fermeture de la popup d'aide au CVV,
la couleur de mot de fermeture de la popup du choix de la marque,
la couleur du surlignage et libellé du champ lorsque celui-ci est édité,
la couleur du texte dans le message de paiement en cours,
la couleur du spinner dans le message de paiement en cours.

La couleur secondaire permet de modifier :

la couleur du logo de la flèche de retour arrière dans l'entête du SDK,
la couleur des textes dans l'entête du SDK,
la couleur du texte dans le bouton "Payer".

Pour personnaliser le SDK de paiement, il vous suffit d'ajouter un fichier PaymentSdkTheme.plist dans votre projet et spécifier dans ce fichier les couleurs à utiliser en hexadécimal:

<?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>

Il est également possible de modifier la police utilisée avec la clé PaymentSDKFont.

Textes

Il est aussi possible de personnaliser certains textes. Pour cela, spécifier le paramètre optionnel "options" lors de l'appel au Lyra.process().

Bouton PAYER

Le texte du bouton PAYER peut être personnalisé.

Spécifier la clé LyraPaymentOptions.customPayButtonLabel.

Entête

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".

Spécifier la clé LyraPaymentOptions.customHeaderLabel.

Le texte de la popup qui s'ouvre suite au clic sur le bouton PAYER peut aussi être personnalisé.

Spécifier la clé 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"])

Moyens de paiement proposés

Par défaut, l’appel au Lyra.process() propose tous les moyens de paiement disponibles. Cependant, il est possible de modifier ce comportement pour proposer un moyen de paiement spécifique en utilisant le paramètre optionnel "options". Pour cela :

Spécifiez la clé LyraPaymentOptions.paymentMethodType.
Utilisez l'enum LyraPaymentMethods pour la valeur :

cardPayment : le formulaire de paiement par carte est presenté par le SDK.
applePay : l'écran de paiement via ApplePay est presenté par le SDK.
all : s'il y a plusieurs moyens de paiement, l'écran de sélection de moyens de paiements est presenté. Sinon, le formulaire de paiement par carte est affiché. Cette valeur correspond au même comportement que l'appel au Lyra.process() sans la clé LyraPaymentOptions.paymentMethodType dans le paramètre "options".

Annuler un paiement en cours

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 :

Le processus de paiement peut être annulé :
- le formulaire de paiement se ferme correctement.
- le handler onError qui est passé au Lyra.process() est appelé avec l'erreur MOB_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) :
- le formulaire de paiement reste affiché.
- le handler onError qui est passé au Lyra.process() est appelé avec l'erreur MOB_013 - Payment cannot be cancelled, indiquant que le processus de paiement ne peut pas être annulé.
- le comportement normal du SDK se poursuit :
  - 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é.
S'il n'y a pas de processus de paiement en cours, l'appel au Lyra.cancelProcess() n'aura aucun effet.

Activer la fonctionnalité de scan de la carte

Il est possible, dans le SDK, d’activer la fonctionnalité de scan de la carte. Cette fonctionnalité permet à un utilisateur de ne pas saisir manuellement les informations de sa carte mais d'utiliser la caméra de son appareil mobile pour les scanner et remplir automatiquement le formulaire de paiement.

Pour activer cette fonctionnalité, vous devez :

Intégrer la librairie LyraCardsRecognizer dans votre projet Xcode :
1. Via CocoaPods
  
  Pour intégrer la librairie à votre projet Xcode à l'aide de CocoaPods, indiquez-la dans votre Podfile :
```
target 'MyApp' do
pod 'LyraCardsRecognizer'
end
```
  Puis installez-la avec pod update.
2. Via Carthage
  
  Pour intégrer la librairie LyraCardsRecognizer dans votre projet Xcode en utilisant Carthage, indiquez-la dans votre Cartfile :
```
binary "https://raw.githubusercontent.com/lyra/ios-cards-camera-recognizer/2.0.0/LyraCardsRecognizer.json" == 2.0.0
```
  Ajoutez le fichier LyraCardsRecognizer.xcframework à votre projet 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[LyraInitOptions.cardScanningEnabled] = true

    //Active card scan
    [configurationOptions setValue:[NSNumber numberWithBool:true] forKey:LyraInitOptions.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.

Catégories

Tags

Guide d'integration iOS

Consulter nos exemples d'intégration

Ajouter le SDK de paiement à votre application

Initialiser le SDK

Réaliser un paiement

Initialisation de l'affichage du formulaire de paiement

Affichage de l'écran de paiement

Vérifier le statut de la transaction

Personnaliser le SDK

Thème

Textes

Bouton PAYER

Entête

Moyens de paiement proposés

Annuler un paiement en cours

Activer la fonctionnalité de scan de la carte

Catégories

Tags

Guide d'integration iOS

Consulter nos exemples d'intégration

Ajouter le SDK de paiement à votre application

Initialiser le SDK

Réaliser un paiement

Initialisation de l'affichage du formulaire de paiement

Affichage de l'écran de paiement

Vérifier le statut de la transaction

Personnaliser le SDK

Thème

Textes

Bouton PAYER

Entête

Popup de paiement

Moyens de paiement proposés

Annuler un paiement en cours

Activer la fonctionnalité de scan de la carte