• France
état des services
démonstrations
assistance
FAQContacter le support
Video tutorials
Rechercher
Catégories
Tags
France
France
Espagne
Europe (Anglais)
Inde
Accueil
Cas d'usage
Créer un paiement
Créer un paiement en plusieurs fois
Proposer un paiement complémentaire
Créer un paiement par alias (token)
Créer un lien de paiement
Créer un abonnement
Gérer vos abonnements
Gérer vos transactions (rembourser,...)
Analyser vos journaux
Docs API
Formulaire embarqué
API REST
Formulaire en redirection
SDK Mobile
Échange de fichiers
Mandats SEPA par API REST
Exemples de code
Moyens de paiement
Modules de paiement
Marketplace
Guides
Back Office Marchand
Back Office Expert
Guides fonctionnels

Guide d'integration iOS

1. Ajouter le SDK mobile à votre application

Le SDK mobile est compatible à partir de la version iOS 15.1

Vous pouvez intégrer le SDK mobile dans votre projet Xcode avec :

CocoaPods

  1. Indiquez le SDK mobile dans votre Podfile.
    target 'MyApp' do
    
      use_frameworks!
    
      pod 'LyraPaymentSDK'
      end
  2. Installez le SDK mobile avec pod update.

Pour éviter les erreurs de compilation, vous devez toujours ouvrir le projet avec le fichier .xcworkspace et non le fichier .xcodeproj, comme indiqué dans l'avertissement de la ligne de commande.

Carthage

  1. Indiquez dans votre Cartfile les dépendances nécessaires à notre SDK mobile.
    # Payment SDK Mobile & dependencies
    
    binary "<https://raw.githubusercontent.com/lyra/ios-sdk/2.7.4/LyraPaymentSDK.json>>" == 2.7.4
    
    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
    
    
    
    
    # Your dependencies
    
    ...
  2. Dans le Cartfile, remplacez le numéro de la version de LyraPaymentSDK par le numéro de la dernière version publiée sur [notre repository GitHub](https://github.com/lyra/ios-sdk/releases).
  3. Ajoutez le LyraPaymentSDK.xcframework à votre projet iOS ainsi que les autres dépendances spécifiées dans votre Cartfile.
  4. Dans votre projet Xcode, encadré Frameworks, Libraries, and Embedded Content, sélectionnez l'option Embed & Sign pour chaque dépendance.

Pour garantir une sécurité optimale de vos paiements, mettez à jour régulièrement le SDK mobile. Pour être informé des nouvelles versions du SDK mobile, consultez régulièrement notre repository GitHub.

2. Initialiser le SDK mobile

  1. Importez le framework import LyraPaymentSDK.
  2. Appelez la méthode initialize avec ces paramètres :

    Il est nécessaire d'effectuer l'initialisation du SDK mobile au lancement de votre application, dans la méthode didFinishLaunchingWithOptions de votre AppDelegate.

    Paramètre Format Description Exemple
    publicKey String 2e clé du tableau des clés API REST. 69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5
    configurationOptions [String: Any] Dictionnaire qui définit le comportement du SDK mobile. Voir étape suivante.
  3. Configurez le dictionnaire configurationOptions avec ces paramètres :
    Clés Format Description Exemple
    apiServerName String 1e donnée du tableau des clés API REST. Obligatoire https://api.lyra.com
    cardScanningEnabled Bool Active/Désactive la fonctionnalité de scan de la carte. Voir : Fonctions du scan de la carte ou du NFC. Facultatif. True

En cas d'échec de l'initialisation du SDK mobile, voir : Gestion des erreurs.

Le SDK mobile ne permet pas de faire plusieurs process en parallèle. Pendant le traitement du premier appel, les autres appels seront ignorés (pas de callback, pas d'exception).

Exemple pour la boutique de démonstration

La fonction initialize  est inititalisée avec :

  • apiServerName valorisé à https://api.lyra.com
  • publicKey valorisé à 69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5
//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];

3. Réaliser un paiement

Vérifiez sur vos serveurs le montant du panier avant la création du formToken.

3.1 Créer un formToken

Requête
  1. Depuis votre serveur marchand, appelez le Web Service Charge/CreatePayment en envoyant le contexte de paiement (montant, devise, numéro de commande, coordonnées de l'acheteur, etc.).

    Pour des raison de sécurité et éviter des erreurs CORS, n'appelez pas le Web Service Charge/CreatePayment depuis votre application mobile.

  2. Valorisez le paramètre formTokenVersion avec le résultat de la méthode getFormTokenVersion du SDK mobile.

Exemple avec la génération du formToken

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

  // 2. Execute getProcessPaymentContext in order to 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"];

    }];

Retrouvez tous les champs et leur description dans le playground : Charge/CreatePayment.

    <p></p>
Réponse

La réponse du Web Service Charge/CreatePayment contient un formToken.

C'est une clé générée par la plateforme de paiement. Elle contient les données du paiement (montant, devise, coordonnées de l'acheteur, etc.).

Le formToken est utilisé pour afficher le formulaire dans l'étape suivante.

3.2 Afficher l'écran de paiement

  1. Importez le framework import LyraPaymentSDK.
  2. Transmettez le formToken lors de l'appel de la méthode Lyra.process avec ces paramètres :
    Paramètre Format Description
    contextViewController UIViewController ViewController de l'application client lors du lancement du processus de paiement.
    formToken String Réponse du Web Service Charge/CreatePayment.
    onSuccess LyraHandlerOnSuccess Fonction de callback appelée lorsque le paiement s'est déroulé correctement.
    onError LyraHandlerOnError Fonction de callback appelée lorsque le paiement n'a pu être initié ou a été refusé.

Si la fonction onError retourne un objet LyraError, consultez : Gestion des erreurs.

Exemple

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

Le SDK mobile vérifie la cohérence du formToken et affiche les moyens de paiement disponibles.

3.3 Procéder au paiement

En mode test, des exemples de cartes de test sont disponibles : Cartes de test.

Pour passer en mode production, consultez la procédure.

4. Analyser le résultat du paiement

La plateforme de paiement envoie le résultat du paiement :

  • au SDK mobile en envoyant un objet LyraResponse à l'une des fonctions de callback onSuccess ou onError

  • au serveur marchand en appelant l'IPN. Nécessite le paramétrage des règles de notification.

4.1 Structure de la réponse

L'objet LyraResponse ainsi que l'objet JSON transmis dans l'IPN contiennent les données ci-dessous :

Paramètre Description
kr-hash-key Type de clé pour signer le kr-answer. Les valeurs possibles sont :
  • password pour l'IPN
  • sha256_hmac pour les fonctions de callback
kr-hash-algorithm Algorithme utilisé pour calculer le hash. Sa valeur est sha256_hmac.
kr-answer Objet contenant le résultat du paiement, encodé en JSON.
kr-answer-type Type de l'objet JSON contenu dans kr-answer.
kr-hash Hash de l'objet JSON stocké dans kr-answer. Il permet de vérifier l'authenticité de la réponse.

Exemple de réponse

{
   "kr-hash":"80f5188e757c1828e8d4ccab87467eb50c4299e4057fa03b3f3185342f6d509c",
   "kr-hash-algorithm":"sha256_hmac",
   "kr-answer-type":"V4\/Payment",
   "kr-answer": "{
      "shopId":"65512466",
      "orderCycle":"CLOSED",
      "orderStatus":"PAID",
     (...)
      "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,
            ...
         },
         (...)
         "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",
            ...
         }
      ],
      "_type":"V4\/Payment"
   }"
}

Retrouvez tous les champs et leur description dans le playground.

4.2 Analyser le résultat transmis à l'application

kr-answer est l'objet contenant le résultat du paiement, encodé en JSON.

  1. L'application mobile transmet l'objet LyraResponse au serveur marchand.
  2. Le serveur marchand calcule le kr-hash en utilisant la fonction hash_hmac et la clé HMAC-SHA-256 pour vérifier l'authenticité de la réponse.

    • Algorithme de chiffrement : SHA-256
    • Clé secrète : Clé HMAC-SHA-256 (3e clé du tableau des clés API REST)
    • Base d'encodage : héxadécimale (base 16)

    Si la valeur du kr-hash calculée par le serveur marchand est égale à celle contenue dans l'objet LyraResponse, alors le message est authentique.

  3. Le serveur marchand vérifie le statut du paiement (voir : références de status).
  4. Le serveur marchand communique le résultat à l'application mobile pour qu'elle l'affiche à l'acheteur.

Exemple de code sans le calcul du kr-hash

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

4.3 Analyser le résultat depuis l'IPN

Voir : Analyse de l'IPN (URL de notification).

4.4 Gérer les erreurs

Voir : Codes d'erreur.

Nous recrutons
Mentions légales
Charte de Protection des Données Personnelles
25.18-1.11