Guide d'integration iOS

1. Ajouter le SDK de paiement à votre application

Dans un projet Xcode, intégrez au choix :

Avec CocoaPods

Pour intégrer le SDK dans votre projet Xcode avec CocoaPods :

Indiquez le SDK dans votre Podfile :

target 'MyApp' do

  use_frameworks!

  pod 'LyraPaymentSDK'
  end

Installez le SDK avec pod update.

Avec Carthage

Pour intégrer le SDK dans votre projet Xcode avec Carthage :

Indiquez dans votre Cartfile les dépendances nécessaires à notre SDK

# 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

...

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](https://github.com/lyra/ios-sdk/releases).
Ajoutez le LyraPaymentSDK.xcframework à votre projet iOS ainsi que les autres dépendances spécifiées dans votre Cartfile.
Après l'intégration du SDK dans votre projet, dans l'encadré "Frameworks, Libraries, and Embedded Content", sélectionnez l'option "Embed & Sign" pour chaque dépendance.

2. Initialiser le SDK

Importez le framework import LyraPaymentSDK

Appelez la méthode initialize avec ces paramètres :

Paramètre	Format	Description	Exemple
publicKey	String	2 ème clé du tableau des clés API REST.	69876357:testpublickey_DEMOPUBLICKEY95me92597fd28tGD4r5
configurationOptions	[String: Any]	Dictionnaire qui définit le comportement du SDK.	Voir étape suivante.

Configurez le dictionnaire configurationOptions avec ces paramètres :

Clés	Format	Description	Exemple
apiServerName	String	1 ère 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, voir : Gestion des erreurs.

Exemple pour la boutique DEMO

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

apiServerName par https://api.lyra.com
publicKey par 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

3.1 Créer un formToken

Requête

Appelez le Web Service Charge/CreatePayment (toujours depuis votre serveur marchand), avec le contexte de paiement (montant, devise, numéro de commande, coordonnées de l'acheteur, etc.).

Dans cette requête, utilisez ce paramètre formTokenVersion correspondant au résultat de la méthode getFormTokenVersion du SDK.

Retrouvez l'intégralité et la description des champs dans notre playground.

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

    }];

Réponse

La réponse de l'appel Web Service REST Charge/CreatePayment correspond au 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.).

Intégrez le formToken pour afficher le formulaire.

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

Paramètre	Format	Description
contextViewController	UIViewController	Correspond au ViewController de l'application client lors du lacement du processus de paiement
formToken	String	Correspond à la réponse du Web Service `Charge/CreatePayment`.
onSuccess	LyraHandlerOnSuccess	Fonction de `callback` appelée si le paiement se déroule correctement.
onError	LyraHandlerOnError	Fonction de callback appelée si le paiement est en échec ou n'a pu être initié. Par ex : si le paiement est refusé ou si une erreur fonctionnelle ou technique survient pendant le paiement. Voir : Gestion des erreurs.

Exemple de code : méthode process

  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 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 dans un objet JSON LyraResponse :

vers la fonction callback onSuccess ou onError, côté application mobile.
vers une IPN, appel de serveur à serveur. Nécessite le paramétrage des règles de notification.

4.1 Structure de la réponse

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 le retour vers l'application mobile.
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 l'intégralité et la description des champs de la réponse : Payment.

4.2 Analyser le résultat, côté application

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

Récupérez le JSON envoyé par la plateforme de paiement
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 : SHA-256.
- 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.

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

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.

Catégories

Tags