Guide d'integration iOS

1. Ajouter le SDK mobile à votre application

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

CocoaPods

Indiquez le SDK mobile dans votre Podfile.

target 'MyApp' do

  use_frameworks!

  pod 'LyraPaymentSDK'
  end

Installez le SDK mobile avec pod update.

Carthage

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

...

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).
Ajoutez le LyraPaymentSDK.xcframework à votre projet iOS ainsi que les autres dépendances spécifiées dans votre Cartfile.
Dans votre projet Xcode, encadré Frameworks, Libraries, and Embedded Content, sélectionnez l'option Embed & Sign pour chaque dépendance.

Importez le framework import LyraPaymentSDK.

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

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

Configurez le dictionnaire configurationOptions avec ces paramètres :

Clés	Format	Description	Exemple
apiServerName	String	1^e donnée du tableau des clés API REST. Obligatoire	https://api.scelliuspaiement.labanquepostale.fr
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.

Exemple pour la boutique de démonstration

La fonction initialize est inititalisée avec :

apiServerName valorisé à https://api.scelliuspaiement.labanquepostale.fr
publicKey valorisé à 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];

3. Réaliser un paiement

3.1 Créer un formToken

Requête

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

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

Retrouvez tous les champs et leur description dans le playground.

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

    }];

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

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	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 se déroule 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.

L'application mobile transmet l'objet LyraResponse au serveur marchand.
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. (3^e 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.
Le serveur marchand vérifie le statut du paiement (voir : références de status).
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.

Catégories

Tags