Guides
Page de StatutTableau de bordRéserver une Démo
Commencez à taper pour rechercher...

Headless SDK (Paiement iOS)


👍

SDK recommandé

Nous recommandons d'utiliser le SDK Seamless iOS pour une expérience d'intégration fluide. Cette option offre une solution de paiement flexible avec des composants d'interface utilisateur (UI) pré-construits et des options de personnalisation.

Le Headless iOS SDK de Yuno vous permet de créer des paiements et d'enregistrer des méthodes de paiement simultanément. Notez que lorsque vous utilisez le Headless SDK, vous devez demander et envoyer via l'API tous les champs obligatoires que le fournisseur de paiement exige pour générer un paiement dans son API.

Le SDK Headless de Yuno vous permet de créer des paiements selon deux scénarios différents :

  • Créer un Token à usage unique à l'aide des informations de carte de crédit ou des méthodes de paiement alternatives, puis créer un paiement.
  • Créer un Token à usage unique à l'aide d'un vaulted_token provenant d'une méthode de paiement précédemment enregistrée pour collecter des informations pertinentes pour les fournisseurs de fraude, puis créer un paiement.

Les étapes suivantes décrivent la création d'un paiement à l'aide du SDK Headless de Yuno.

Étape 1 : Inclure la bibliothèque dans votre projet

La première étape consiste à installer Yuno SDK dans votre projet iOS.

📘

Vérifier les versions du SDK iOS

Pour consulter toutes les versions disponibles, visitez la page des versions sur le référentiel Yuno iOS SDK.

Vous pouvez installer Yuno SDK de deux manières :

  • Cocoapodes: Si vous n'avez pas de Podfile, suivez le guide suivant CocoaPods pour en créer un. Après avoir créé le Podfile, vous intégrerez le Yuno SDK avec Cocoapods en ajoutant la ligne ci-dessous à votre Podfile : 
    pod 'YunoSDK', '~> {last_version}'
  • Swift Package Manager: Configurez le package Swift, puis ajoutez Yuno SDK en tant que dépendance, comme présenté dans le bloc de code suivant : 
    dependencies: [
    .package(url: "https://github.com/yuno-payments/yuno-sdk-ios.git", .upToNextMajor(from: "{last_version}"))
]

Étape 2 : Initialiser le SDK Headless avec la clé publique

Pour initialiser le Headless SDK, vous devez importer Yuno et fournir une PUBLIC_API_KEY valide. Si vous n'avez pas vos identifiants API, accédez à la page Développeurs (Identifiants) pour savoir comment les récupérer depuis le tableau de bord.

🚧

Initialisation de UISceneDelegate

Si votre application utilise un UISceneDelegateassurez-vous de placer le code d'initialisation de Yuno dans votre SceneDelegate. En savoir plus

Le bloc de code ci-dessous présente un exemple d'importation et d'initialisation du Yuno.

import YunoSDK

Yuno.initialize(
    apiKey: "PUBLIC_API_KEY"
)

Étape 3 : Démarrer le processus de paiement

Ensuite, vous démarrerez le processus de paiement en utilisant la fonction apiClientPayment en fournissant les paramètres de configuration nécessaires. Vous devez appeler cette fonction une fois que votre client a sélectionné la méthode de paiement. En conséquence, le SDK commencera à collecter les informations pertinentes pour la 3DS et les outils de prévention de la fraude que vous avez configurés dans votre  routage.

Paramètres

Le tableau suivant répertorie tous les paramètres requis et leurs descriptions.

ParamètresDescription
countryCodeCe paramètre détermine le pays pour lequel le processus de paiement est configuré. La liste complète des pays pris en charge et leurs countryCode est disponible sur la page  Couverture par Pays .
checkout_sessionFait référence à la session de paiement en cours créée à l'aide du l'endpoint Créer une session de paiement. Exemple: '438413b7-4921-41e4-b8f3-28a5a0141638'

Le bloc de code suivant présente un exemple de configuration des paramètres.

var apiClientPayment : YunoPaymentHeadless ?

apiClientPayment = Yuno.apiClientPayment(
 countryCode: « CO »,
 checkoutSession: « 438413b7-4921-41e4-b8f3-28a5a0141638 »
)

Étape 4 : Générer un token

Après avoir collecté toutes les informations utilisateur, vous pouvez démarrer le paiement. Tout d'abord, vous devez créer un token à usage unique (OTT) à l'aide de la fonction  apiClientPayment.generateToken. Comme il s'agit d'une fonction asynchrone, vous pouvez utiliser do/catch pour vous assurer que vous gérerez correctement les erreurs déclenchées. Ci-dessous, vous trouverez deux exemples de scénarios différents pour créer un token à usage unique :

  1. Exemple 1: créer un token à usage unique en utilisant une carte comme méthode de paiement et en incluant toutes les informations nécessaires sur la carte.
  2. Exemple 2: Créer un token à usage unique en utilisant les informations du vaulted_token .
👍

Avantages d'utiliser un Token sécurisé

L'utilisation d'un token sécurisé avec le SDK garantit que toutes les informations de fraude de vos fournisseurs configurés sont collectées et attachées au token à usage unique. De plus, vous pouvez inclure les détails des versements et un code de sécurité si le fournisseur l'exige.

let tokenCollectedData: TokenCollectedData = TokenCollectedData(
 checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
    paymentMethod : CollectedData(
        type : « CARD »,
 vaultedToken: nil,
        card : CardData(
            save : true,
            detail : CardData.Detail(
                number : « 4111111111111111 »,
                expirationMonth : 12,
                expirationYear : 25,
                securityCode : « 123 »,
                holderName : « Andrea »,
                type : .credit
            ),
            installment: CardData.Installment(
                id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
                value: 1
            )
        ),
        customer: Customer()
    )
)

let result = try await apiClientPayment.generateToken(
    data: tokenCollectedData
)
let tokenCollectedData: TokenCollectedData = TokenCollectedData(
 checkoutSession: "438413b7-4921-41e4-b8f3-28a5a0141638",
    paymentMethod: CollectedData(
        type: "CARD",
 vaultedToken: « c8bb2bd8-8abf-4265-b478-0ec4e3c10cd5 »,
        card : CardData(
            installment : CardData.Installment(
                id : « 64ceacef-0886-4c81-9779-b2b3029c4e8b »,
                value : 1
            )
        ),
        client : Client()
    ))


let résultat = try await apiClientPayment.generateToken(
    données : tokenCollectedData
)

Le bloc de code suivant présente les réponses de la fonction apiClientPayment.generateToken pour les deux exemples ci-dessus. La réponse est un dictionnaire de type [String: Any].

 ["token" : "9ee44ac7-9134-4598-ae28-a26fec03099d",
     "type" : "CARD",
     "customer" : ["billing_address" : nil,
                  "first_name" : nil,
                  "gender" : "",
                  « phone » : nil,
                  « browser_info » : [« color_depth » : nil,
                                   « language » : « en »,
                                   « accept_header » : « */* »,
                                   « browser_time_difference » : nil,
                                   « accept_content » : nil,
                                   « accept_browser » : nil,
                                   « java_enabled » : nil,
                                   « user_agent » : « YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0 »,
                                   « screen_height » : « 844.0 »,
« screen_width » : « 390.0 »,
« javascript_enabled » : nil],
                  « document » : nil,
                  « last_name » : nil,
                  « device_fingerprint » : nil,
                  «email » : nil],
     « country » : « BR »,
     « vaulted_token » : nil,
     « installment » : [« rate » : « »,
                     « id » : « cca80084-961b-4212-9c34-54f03f4f10ae »,
                     « value » : 24,
                     « amount » : nil],
     « card_data » : nil]

["token" : "9ee44ac7-9134-4598-ae28-a26fec03099d",
     "type" : "CARD",
     "customer" : ["billing_address" : nil,
                  "first_name" : nil,
                  "gender" : "",
                  « phone » : nil,
                  « browser_info » : [« color_depth » : nil,
                                   « language » : « en »,
                                   « accept_header » : « */* »,
                                   « browser_time_difference » : nil,
                                   « accept_content » : nil,
                                   « accept_browser » : nil,
                                   « java_enabled » : nil,
                                   « user_agent » : « YunoSDK_Example/1 CFNetwork/1406.0.4 Darwin/22.6.0 »,
                                   « screen_height » : « 844.0 »,
« screen_width » : « 390.0 »,
« javascript_enabled » : nil],
« document » : nil,
« last_name » : nil,
« device_fingerprint » : nil,
«email » : nil],
     « country » : « BR »,
     « vaulted_token » : « a1c7c5d1-b260-4dc6-909a-8368704233cf »,
     « installment » : [« rate » : « »,
                     « id » : « cca80084-961b-4212-9c34-54f03f4f10ae »,
                     « value » : 24,
                     « amount » : nil],
     « card_data » : nil]

Étape 5 : Créer le paiement

Une fois que vous avez effectué les étapes décrites précédemment, vous pouvez créer un paiement. La création d'un paiement back-to-back doit être effectuée à l'aide du l'endpoint Créer un paiement. Le commerçant doit appeler son backend pour créer le paiement dans Yuno, en utilisant le token à usage unique et la session de paiement.

La réponse de l'endpoint inclut le paramètre sdk_action_required qui indique si des actions supplémentaires sont nécessaires pour compléter le paiement :

Pour les méthodes de paiement synchrones, le paiement est complété instantanément. Dans ce cas, sdk_action_required sera faux dans la réponse API et le processus de paiement prendra fin. Si le paiement nécessite une interaction supplémentaire de la part du SDK pour terminer le flux, sdk_action_required sera vrai ; dans ce cas, passez à l'étape 6 pour obtenir des instructions.

Étape 6 : Traiter les paiements asynchrones (Facultatif)

Un paiement avec 3DS peut nécessiter un défi supplémentaire pour vérifier l'identité du client, comme décrit sur la page Vérification de la carte 3DS. Si un défi de vérification 3DS est nécessaire, la réponse du endpoint Créer un paiement contiendra :

  • Un statut égal à PENDING et un sous-statut égal à WAITING_ADDITIONAL_STEP
  • sdk_action_required = true
  • A redirect_url défini dans payment.payment_method.payment_method_detail.card

Pour effectuer le défi et finaliser le paiement, vous avez deux options d'intégration :

Obtenir l'URL du défi 3DS

Pour obtenir l'URL du défi 3DS, vous devez appeler la fonction getThreeDSecureChallenge , en fournissant la checkoutSession. La checkoutSession n'est requise que si vous n'utilisez pas celle utilisée pour créer le paiement. Ci-dessous, vous trouverez un exemple d'utilisation de la fonction getThreeDSecureChallenge . Comme getThreeDSecureChallenge est une fonction asynchrone, vous pouvez utiliser do/catch pour vous assurer que vous gérerez correctement les erreurs déclenchées.

func getThreeDSecureChallenge(checkoutSession: String?) async throws -> ThreeDSecureChallengeResponse

Le champ getThreeDSecureChallenge renverra la ThreeDSecureChallengeResponse, présentée dans le bloc de code suivant :

public struct ThreeDSecureChallengeResponse {
    public let url: String
}

Le champ url contiendra une URL valide vers laquelle vous devez rediriger votre client pour compléter le défi.

Vous êtes responsable de rediriger vos clients vers l'URL fournie par la fonction getThreeDSecureChallenge() pour compléter le défi. Une fois que le client a réussi le défi 3DS, il sera automatiquement redirigé vers la callback_url, que vous avez fournie lors de la création de la checkout_session avec l'objet  Créer une session de paiement .

Pour confirmer que le défi a été complété, vous pouvez ouvrir une vue web pour charger l'URL fournie et écouter l'événement messageFromWeb . Voici un exemple de code montrant comment écouter cet événement.

class HeadlessWebView: UIViewController, WKScriptMessageHandler, WKNavigationDelegate {

    private var webView: WKWebView!
    private var url: String = ""
    private let configuration = WKWebViewConfiguration()

    init(url: String) {
        self.url = url
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        nil
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .white
        webViewConfig()
    }

    func webViewConfig() {
   
        configuration.preferences.javaScriptEnabled = true
        configuration.userContentController.add(self, name: "messageFromWeb")
        webView = WKWebView(frame: view.bounds, configuration: configuration)
        webView.navigationDelegate = self

        guard let url = URL(string: url) else {
            return
        }
        let request = URLRequest(url: url)
        webView.load(request)

    }

    func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
        if message.name == "messageFromWeb", let messageBody = message.body as? String {
            self.dismiss(animated: true)

        }
    }

    override func viewDidDisappear(_ animated: Bool) {
        super.viewDidDisappear(animated)
        self.configuration.userContentController.removeScriptMessageHandler(forName: "messageFromWeb")
    }

}

La réponse informera du statut du défi, qui peut être COMPLETED ou ERROR. Le bloc de code suivant présente des exemples pour chaque option possible.

{
   "origin":"CHALLENGE",
   "status":"COMPLETED",
   "data":"callback_url"
}
{
   "origin":"CHALLENGE",
   "status":"ERROR",
   "data":"Invalid 3DS provider"
}

Pour compléter le flux de paiement du Headless SDK , vous devez utiliser les Webhooks Yuno, qui vous informeront rapidement du résultat du défi 3DS et du statut final du paiement. L'utilisation de webhooks garantit que vous recevez des mises à jour en temps réel sur la progression de la transaction de paiement. En plus des webhooks, vous pouvez récupérer les informations de paiement à l'aide du endpoint Récupérer Paiement par ID.

Pour finaliser l'implémentation du paiement et comprendre les étapes restantes, accédez à Headless SDK (Paiement).

Étape 7 : Gérer le statut du paiement (Facultatif)

🚧

Liens Profonds et Mercado Pago Checkout Pro

Cette étape n'est requise que si vous utilisez une méthode de paiement qui repose sur des liens profonds ou Mercado Pago Checkout Pro. Si vos méthodes de paiement n'utilisent pas de liens profonds, vous pouvez ignorer cette étape.

Certaines méthodes de paiement font sortir les utilisateurs de votre application pour finaliser la transaction. Une fois le paiement terminé, l'utilisateur est redirigé vers votre application à l'aide d'un lien profond. Le SDK utilise ce lien profond pour vérifier ce qui s'est passé (paiement réussi, échec ou annulation) et peut afficher un écran de statut à l'utilisateur.

Pour gérer cela, vous devez mettre à jour votre AppDelegate pour transmettre l'URL entrante au SDK Yuno. Cela permet au SDK de lire le résultat et éventuellement d'afficher le statut du paiement. Le code suivant montre comment l'ajouter à votre application :

func application(_ app: UIApplication,
                 open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {

  guard url.scheme == "yunoexample" else { return false }

  return Yuno.receiveDeeplink(url, showStatusView: true)
}

Ce code est à l'écoute des liens profonds qui ouvrent votre application. Lorsqu'une URL est reçue, il vérifie si le schéma correspond à celui que vous avez utilisé le callback_url lors de la configuration de la session de paiement. Si cela correspond, l'URL est transmise au SDK Yuno via Yuno.receiveDeeplink(...). Le SDK lit ensuite le résultat du paiement et, si showStatusView est fixé à true, affiche l'écran de statut approprié à l'utilisateur.

Assurez-vous que le url.scheme dans ce code correspond au callback_url que vous avez fourni lors de la création de la checkout_session.

📘

Application Démo

En plus des exemples de code fournis, vous pouvez accéder au dépôt Yuno pour une implémentation complète des SDK iOS de Yuno.

Mise à jour il y a 26 jours