Guide d'integration iOS

Étapes d'intégration

• Ajouter le SDK
• Initialiser le SDK
• Réaliser un paiement
• Analyser le résultat du paiement

Ajouter le SDK de paiement à votre application

Dans un projet Xcode, intégrez au choix  :

Avec CocoaPods

    ```ruby
    target 'MyApp' do

    use_frameworks!

    pod 'LyraPaymentSDK'
    end
    ```

    - Puis installez le SDK avec `pod update`.

Avec Carthage

    ```ruby
    # 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
    # Your dependencies

    ...

    ```

    Dans le <no-translate>`Cartfile`</no-translate> assurez-vous de remplacer le numéro de la version de <no-translate>**LyraPaymentSDK**</no-translate> par le numéro de la dernière version publiée sur [notre repository GitHub](https://github.com/lyra/ios-sdk/releases)

    Ajoutez le <no-translate>`LyraPaymentSDK.xcframework`</no-translate> à votre projet iOS ainsi que les autres dépendances spécifiées dans votre <no-translate>`Cartfile`</no-translate>.

Mettez à jour régulièrement le SDK de paiement et consultez régulièrement notre repository GitHubpour être informé des nouvelles versions du SDK.

Initialiser le SDK

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

Pour le dictionnaire configurationOptions, utilisez ces paramètres :

Exemple pour la boutique DEMO

Avec les clés de la boutique de DEMO, valorisez dans la fonction initialize :

• apiServerName par https://api.scelliuspaiement.labanquepostale.fr
• publicKey par 42229744:testpublickey_tPXxrUVsoGkggk9LuO8o0PBRdWg8jWUhWmYMURwCbc8ap

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

• En cas d'echec de l'initialisation du SDK, voir : Gestion des erreurs.

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

Le SDK 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).

Réaliser un paiement

A. Créer un formToken

Exemple avec la génération du formToken

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

    }];

B. Afficher l'écran de paiement

• Importez le framework import LyraPaymentSDK
• Transmettez le formToken lors de l'appel de la méthode Lyra.process avec ces paramètres :

  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 se charge alors de vérifier la cohérence du formToken puis affiche les moyens de paiements disponibles.

C. Procéder au paiement

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

Pour passer en mode PRODUCTION, voir : lien.

Analyser le résultat du paiement

La plateforme de paiement envoie le résultat du paiement dans un JSON Object LyraResponse :

• vers la fonction callback onSuccess ou onError, côté application mobile.

• vers une IPN (Instant Payment Notification), appel de serveur à serveur. Voir le paramétrage : "IPN".

A. Structure 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 l'intégralité et la description des champs de la réponse : Payment.

B. Analyse du résultat, côté application

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

1. Récupérez le JSON envoyé par la plateforme de paiement

2. Calculez 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 :sha256.
   • Clé secrète :Clé HMAC-SHA-256. (**3 ème** clé du tableau des clés API REST)
   • Base d'encodage :héxadécimale (base 16).

   Si le calcul de votre kr-hash est égal à celui de la plateforme alors le message est authentique.

3. Vérifiez le statut du paiement (voir : références de status).

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

C. Analyse du résultat depuis l'IPN

Intégrez l'IPN : Analyse de l'IPN (URL de notification).

D. Gestion des erreurs

Voir : Codes d'erreur .