Guide d'integration iOS

Étapes d'intégration

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

Avec 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
# 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.

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 :

Paramètre	Format	Description	Ex
publicKey	String	2 ème clé du tableau des clés API REST	73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ
configurationOptions	[String: Any]	Dictionnaire pour configurer le comportement du SDK.	Voir tableau ci-dessous

Pour le dictionnaire configurationOptions, utilisez ces paramètres :

Clés	Format	Description	Ex
apiServerName	String	1 ère donnée du tableau des clés API REST. Obligatoire	https://api.systempay.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

Exemple pour la boutique DEMO

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

apiServerName par https://api.systempay.fr
publicKey par 73239078:testpublickey_Zr3fXIKKx0mLY9YNBQEan42ano2QsdrLuyb2W54QWmUJQ

Méthode initialize

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

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. Voir : 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.

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 :

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

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.

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

Le 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 :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.

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 .

Catégories

Tags