Lite SDK (Paiement Android)

👍

SDK recommandé

Nous recommandons d'utiliser le SDK Seamless Android  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.

Cette page fournit un guide pour le Lite SDK de Yuno pour les paiements Android. Ce SDK offre un processus d'intégration simplifié avec des fonctionnalités de paiement essentielles, ce qui le rend idéal pour les commerçants qui :

• Ont besoin d'une implémentation rapide avec des exigences de personnalisation minimales
• Veulent se concentrer principalement sur le traitement des paiements par carte
• Préfèrent une interface utilisateur prête à l'emploi qui gère le flux de paiement

Le Lite SDK comprend des fonctionnalités de base telles que :

• Composants d'interface utilisateur de paiement pré-construits
• Traitement des paiements par carte
• Gestion de base du statut de paiement
• Gestion essentielle des erreurs

Pour les commerçants nécessitant des fonctionnalités plus avancées comme plusieurs méthodes de paiement, une interface utilisateur personnalisée ou une prévention avancée de la fraude, veuillez considérer l'utilisation de notre Full SDK.

Prérequis

Avant de commencer l'intégration du SDK Android de Yuno, assurez-vous que votre projet répond aux exigences techniques. De plus, les pré-requis suivants doivent être en place :

• Vous devez disposer d'un compte Yuno actif.
• Vous avez besoin de vos identifiants API Yuno (account_id, public-api-keyet  private-secret-key), que vous pouvez obtenir dans la  Section des identifiants Développeurs du tableau de bord Yuno. Ces identifiants sont requis pour authentifier les requêtes auprès de l'API Yuno. L'API est utilisée pour :
  • Créer un customer, requis avant d'initier les paiements
  • Créer un checkout_session, qui initialise le flux de paiement
  • Créer le paiement associé à la session

📘

Version du SDK

Consultez les Notes de version ou le dépôt du Yuno Android SDK pour vérifier la version actuelle du SDK disponible.

Étape 1 : Créer un client

Créez un client en utilisant le endpoint Créer un client avant d'initier les paiements. Cette étape est requise pour :

• Identifier la personne effectuant le paiement
• Activer la fonctionnalité de carte enregistrée (si activée)
• Suivre l'historique des paiements

L'identifiant du client rretourné par cet endpoint sera utilisé lors de la création de la checkout_session.

Étape 2 : Créer une session de paiement

Créez une nouvelle checkout_session à l'aide du endpoint  Créer une session de paiement pour initialiser le flux de paiement. Assurez-vous de :

• Inclure l'ID du client obtenu à l'étape précédente
• Conservez l'ID de la checkout_session retourné pour l'utiliser à l'Étape 5 de l'intégration
• Le champ checkout_session est unique pour chaque tentative de paiement et ne peut pas être réutilisée

🚧

Gestion du retour du navigateur externe

Si votre flux de paiement envoie les utilisateurs vers un navigateur externe (par exemple, pour l'authentification 3DS ou les redirections bancaires), assurez-vous de définir le callback_url lors de la création de votre session de checkout. Pour un guide étape par étape sur la gestion du retour à votre application, consultez  Gérer le retour du navigateur externe (callback_url).

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

Incluez le fichier du SDK Yuno dans votre projet via Gradle. Ajoutez la source du dépôt :

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

Incluez le code suivant dans le fichier build.gradle pour ajouter la dépendance du SDK Yuno à l'application :

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Permissions

Le SDK Yuno inclut la permission INTERNET par défaut, qui est requise pour effectuer des requêtes réseau.

<uses-permission android:name="android.permission.INTERNET" />

Étape 4 : Initialiser le SDK avec la clé publique

Initialisez le SDK :

1. Obtenez vos clés API publiques depuis le tableau de bord Yuno
2. Créez une classe d'application personnalisée si vous n'en avez pas
3. Initialisez le SDK en appelant Yuno.initialize() dans la méthode onCreate() de votre application, en transmettant votre clé API et la configuration :

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config: YunoConfig,
    )
  }
}

Utiliser la classe de données YunoConfig pour personnaliser le comportement du SDK. Incluez cette configuration lors de l'appel à Yuno.initialize(). Les options disponibles sont :

classe de données YunoConfig(
    val cardFlow : CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled : Boolean = false,
    val cardFormDeployed : Boolean = false,
    val language : YunoLanguage? = null,
    val styles : YunoStyles? = null,
    val cardNumberPlaceholder : String? = null, // Facultatif : texte de remplacement personnalisé pour le champ du numéro de carte
    val hideCardholderName: Boolean? = null // Facultatif : définir sur true pour masquer le champ du nom du titulaire de la carte
)

Le tableau suivant décrit chaque option de personnalisation :

Vous devez également mettre à jour votre manifeste pour utiliser votre application :

<application android:name=".CustomApplication"></application>

Étape 5 : Démarrer le processus de paiement

Appelez la fonction startCheckout dans la méthode onCreate() de l'activité qui intègre le SDK pour lancer un nouveau processus de paiement avec le Lite SDK :

startCheckout(
 checkoutSession: "checkout_session",
 countryCode: "US",
 callbackPaymentState: ((String?) -> Unit)?,
  merchantSessionId: String? = null
)

Le tableau suivant décrit les paramètres requis pour démarrer le paiement :

État du paiement par rappel

Le champ callbackPaymentState est une fonction qui retourne le processus de paiement actuel. L'envoi de cette fonction n'est pas obligatoire si vous n'avez pas besoin du résultat. Le bloc de code suivant montre les états possibles :

const val PAYMENT_STATE_SUCCEEDED = "SUCCEEDED"
const val PAYMENT_STATE_FAIL = "FAIL"
const val PAYMENT_STATE_PROCESSING = "PROCESSING"
const val PAYMENT_STATE_REJECT = "REJECT"
const val PAYMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val PAYMENT_STATE_STATE_CANCELED_BY_USER = "CANCELED"

Le tableau suivant fournit des informations supplémentaires sur les états possibles :

Validation du statut de paiement

Cette section explique comment le SDK gère le statut des paiements lorsque les utilisateurs annulent ou quittent les flux de paiement, et comment le statut du SDK est lié au statut des paiements backend dans ces scénarios.

Synchroniser les modes de paiement (Google Pay)

Pour les méthodes de paiement synchronisées telles que Google Pay, lorsqu'un utilisateur annule ou ferme l'interface utilisateur du portefeuille avant de recevoir la réponse du prestataire de services de paiement (PSP) :

• Statut du SDK: Retours CANCELED (CANCELLED)
• Statut du paiement backend: Restes PENDING jusqu'à l'expiration du délai PSP ou l'annulation par le commerçant
• Important: Le SDK ne renverra pas REJECT ou PROCESSING dans ce scénario

Cela garantit que le paiement backend reste en attente et peut être correctement traité par le système du commerçant.

Modes de paiement asynchrones (PIX et méthodes basées sur les QR codes)

Pour les méthodes de paiement asynchrones telles que PIX, lorsqu'un utilisateur ferme la fenêtre du code QR (clique sur X) avant d'avoir terminé le paiement :

• Statut du SDK: Retours PROCESSING, éventuellement avec un sous-statut tel que CLOSED_BY_USER
• Statut du paiement backend: Restes PENDING et le code QR reste valide jusqu'à son expiration.
• Réutilisation de la session de paiement: la réouverture de la même session de paiement permet d'afficher le même code QR valide.
• Pas d'annulation automatique: le paiement PIX n'est pas automatiquement annulé lorsque l'utilisateur ferme la fenêtre QR.

Ce comportement permet aux utilisateurs de revenir au flux de paiement et de terminer la transaction à l'aide du même code QR avant son expiration.

Paiements asynchrones expirés

Si un code QR PIX expire naturellement :

• Statut du backend: Mis à jour vers EXPIRED
• Statut du SDK: Les rappels SDK et endpoints d'interrogation endpoints EXPIRED de manière cohérente

Cela garantit que les commerçants reçoivent des informations précises sur le statut lorsqu'un moyen de paiement a expiré.

Étape 6 : Initier le processus de paiement

Appeler la méthode startPaymentLite pour démarrer un processus de paiement :

startPaymentLite(
 paymentSelected: PaymentSelected,
 callbackOTT:(String?) -> Unit,
 callBackTokenWithInformation:(OneTimeTokenModel?) -> Unit,
 showPaymentStatus: Boolean,
)

Le tableau suivant décrit les paramètres requis pour démarrer le paiement :

Envoyer un paramètre supplémentaire, qui est le token sécurisé  et/ou le type de paiement que l'utilisateur a sélectionné pour effectuer le paiement :

PaymentSelected(
 vaultedToken  String « payment_vaulted_token »,
 paymentMethodType  String « payment_type »,
)

Étape 7 : Obtenir le token à usage unique (OTT)

Le token à usage unique est un identifiant unique qui représente une session de paiement. Ce token est requis pour créer un paiement.

Rappel du Token à Usage Unique

Le Rappel du token à usage unique retourne les paramètres suivants :

🚧

Gestion du Loader

Le commerçant est responsable de la gestion du loader. Yuno offre une option pour utiliser notre loader ; cependant, le commerçant peut utiliser son propre loader et doit effectuer les configurations correspondantes.

Étape 8 : Créer le paiement

Après avoir complété les étapes précédentes, créez un paiement en appelant le endpoint Créer un paiement depuis votre backend. Ce endpoint nécessite :

• Le Token à usage unique obtenu à l'Étape 7.
• Le champ checkout_session obtenue à l'Étape 2

🚧

Intégration de la Méthode continuePayment

Yuno vous  demande  d'intégrer la méthode continuePayment du SDK après la création du paiement, car certaines méthodes de paiement asynchrones nécessitent une action supplémentaire de la part du client pour le compléter. L'API vous informera de ce scénario via le champ sdk_action_required de la réponse, qui sera retourné comme true. La fonction yuno.continuePayment() affichera les écrans supplémentaires aux clients, où ils pourront effectuer les actions nécessaires pour compléter le paiement sans que vous ayez besoin de gérer chaque scénario.

Pour les méthodes de paiement qui nécessitent des actions client supplémentaires (telles que les défis d'authentification 3DS) ou un traitement asynchrone (comme les virements bancaires), vous devrez intégrer la méthode continuePayment du SDK après avoir créé le paiement. La réponse de l'API "Créer un paiement" inclut un champ sdk_action_required qui indique si cette étape est nécessaire :

• Si TRUE: Appelez yuno.continuePayment() pour afficher des écrans supplémentaires pour les actions client (par exemple, authentification 3DS, pages de redirection bancaire)
• Si FALSEIgnorez cette étape car aucune interaction client supplémentaire n'est requise.

Le bloc de code suivant montre comment implémenter le flux de continuation de paiement :

continuePayment(
 showPaymentStatus: Boolean = true,
 checkoutSession: String? = null,
 countryCode: String? = null,
 callbackPaymentState: ((String?) -> Unit)? = null
)

Envoyez FALSE dans le paramètre showPaymentStatus pour afficher vos écrans de statut de paiement. Ensuite, obtenez l'état du paiement par Rappel.

Mode de rendu (intégration avancée)

Pour les développeurs nécessitant un contrôle avancé de l'interface utilisateur, le Lite SDK prend également en charge l'intégration en mode rendu. Ce mode fournit des composants d'interface utilisateur basés sur des fragments que vous pouvez intégrer dans des mises en page personnalisées, offrant plus de flexibilité tout en conservant la fonctionnalité simplifiée du Lite SDK.

Configuration de base du mode rendu

Utilisez startPaymentRender pour une intégration avancée de l'interface utilisateur :

fun Activity.startPaymentRender(
 checkoutSession: String? = null,
 countryCode: String? = null,
    coroutineScope: CoroutineScope,
 paymentSelected: PaymentSelected,
    listener: YunoPaymentRenderListener,
): YunoPaymentFragmentController

Exemple d'Implémentation

class PaymentActivity : Activity() {

    private lateinit var fragmentController: YunoPaymentFragmentController

    private fun initializeRenderMode() {
        fragmentController = startPaymentRender(
            checkoutSession = checkoutSessionId,
            countryCode = "US",
            coroutineScope = lifecycleScope,
            paymentSelected = PaymentSelected.CARD,
            listener = object : YunoPaymentRenderListener {
                override fun showView(fragment: Fragment) {
                    supportFragmentManager.beginTransaction()
                        .replace(R.id.payment_container, fragment)
                        .commit()
                }

                override fun returnOneTimeToken(oneTimeToken: String, additionalData: OneTimeTokenModel?) {
                    processPayment(oneTimeToken) {
                        fragmentController.continuePayment()
                    }
                }

                override fun returnStatus(resultCode: Int, paymentStatus: String) {
                    handlePaymentResult(paymentStatus)
                }

                override fun loadingListener(isLoading: Boolean) {
                    updateLoadingUI(isLoading)
                }
            }
        )
    }
}

Avantages Clés

• Intégration d'Interface Utilisateur Personnalisée: Intégrez les composants de paiement dans vos mises en page existantes
• Compatibilité avec les fragments: Fonctionne à la fois avec XML et Jetpack Compose
• Contrôle du flux: Gérez manuellement la soumission du formulaire et la continuation du paiement

🚧

Fonctionnalité avancée

Le mode rendu est conçu pour les développeurs qui ont besoin d'une intégration d'interface utilisateur personnalisée. Pour des implémentations plus simples, utilisez les méthodes standard du Lite SDK décrites dans les étapes précédentes.

Fonctionnalités Complémentaires

Le SDK Android de Yuno fournit des services et des configurations supplémentaires que vous pouvez utiliser pour améliorer l'expérience de vos clients. Utilisez la personnalisation du SDK pour changer l'apparence du SDK afin qu'il corresponde à votre marque ou pour configurer le loader.

styles

Avec l'option de personnalisation styles , vous pouvez définir des styles visuels globaux via un objet YunoStyles . Il vous permet d'appliquer une image de marque cohérente dans tout le SDK en personnalisant l'apparence des boutons et la typographie.

classe de données YunoStyles(
    val buttonStyles: YunoButtonStyles? = null,
    val fontFamily: FontFamily? = null
)

Le champ YunoButtonStyles vous permet de définir des paramètres spécifiques pour l'apparence des boutons :

data class YunoButtonStyles(
    val backgroundColor : Couleur ? = null,
    val contentColor : Couleur ? = null,
    val cornerRadius : Dp ? = null,
    val elevation : Dp ? = null,
    val padding : Dp ? = null,
    val fontFamily : FontFamily ? = null,
    val fontSize : TextUnit ? = null,
    val fontStyle : FontStyle ? = null
)

Utilisez l'endpoint  YunoConfig , décrite à l'Étape 4, pour utiliser l'option de personnalisation des styles .

Loader

La fonctionnalité du loader est contrôlée par le paramètre keepLoader dans la classe de données YunoConfig qui est documentée en ligne dans la section de configuration du SDK ci-dessus.

Sauvegarde de carte pour les futurs paiements

Vous pouvez également afficher une case à cocher pour sauvegarder ou enregistrer des cartes en utilisant cardSaveEnable: true. Les exemples suivants montrent la case à cocher pour les deux rendus de formulaire de carte :

Options de rendu

Vous pouvez choisir entre deux options de rendu de formulaire de carte. Les captures d'écran suivantes montrent la différence entre cardFormType ONE_STEP  et  STEP_BY_STEP:

Personnalisation du SDK

Vous pouvez modifier l'apparence du SDK pour qu'elle corresponde à votre marque. Pour plus d'informations, consultez la page de personnalisation du SDK.

📘

Application Démo

En plus des exemples de code fournis, vous pouvez consulter le dépôt Yuno pour l'implémentation complète des SDK Android de Yuno.