Seamless SDK (Paiement Android)

Cette page fournit un guide d'intégration du SDK Seamless de Yuno pour les paiements Android.

👍

SDK recommandé

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

Ce SDK est idéal pour les commerçants qui :

• Composants d'interface utilisateur de paiement pré-construits avec options de personnalisation
• Ont besoin de personnaliser l'expérience de paiement tout en maintenant la conformité PCI
• Exigent un équilibre entre la vitesse d'implémentation et la personnalisation

Le SDK Seamless inclut des fonctionnalités telles que :

• Composants de l'interface utilisateur pour les paiements prédéfinis avec options de personnalisation
• Support de multiples méthodes de paiement
• Gestion avancée du statut de paiement
• Gestion complète des erreurs

Pour les commerçants nécessitant un contrôle complet de l'interface utilisateur ou des fonctionnalités plus avancées, 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 Développeurs du tableau de bord Yuno. Ces identifiants sont requis pour authentifier les requêtes auprès de l'API Yuno, 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

📘

Vérifier la 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 6

💳

Contrôle de l'authentification par rapport à la capture par envoi payment_method.detail.card.capture dans la session de paiement : false = autoriser uniquement, true = capturer immédiatement.

Paramètres clés

🚧

Utilisation de la session de paiement

Le champ checkout_session est unique pour chaque tentative de paiement et ne peut pas être réutilisée.

Étape 3 : Ajouter le SDK à votre projet

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

Étape 4 : Configurer les permissions

Le SDK Yuno nécessite des permissions réseau. Assurez-vous que la permission INTERNET est incluse dans votre AndroidManifest.xml:

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

Étape 5 : Initialiser le SDK

Récupérez vos clés API publiques depuis le Tableau de bord Yuno.

Si vous n'avez pas implémenté une classe Application personnalisée, créez-en une. Dans la méthode onCreate() de votre classe d'application, appelez la fonction d'initialisation (Yuno.initialize) :

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

Utilisez l'endpoint  YunoConfig pour définir des configurations supplémentaires pour le SDK. Le tableau suivant énumère et décrit les options de personnalisation :

Le bloc de code suivant montre un exemple de YunoConfig:

classe de données YunoConfig(
    val cardFlow : CardFormType  CardFormType.ONE_STEP,
    val saveCardEnabled : 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
)

Étape 6 : Démarrer le 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 SDK Seamless :

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

Les états de paiement possibles retournés par callbackPaymentState sont :

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 7 : Obtenir un token à usage unique (OTT) du paiement

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

startPaymentSeamlessLite(
 paymentSelected: PaymentSelected,
 callbackPaymentState: ((String?) -> Unit)?,
 showPaymentStatus: Boolean,
)

Le tableau suivant décrit les paramètres permettant de lancer le paiement :

Vous recevrez le statut de paiement via callbackPaymentState, indiquant si le paiement a réussi ou si un problème est survenu.

Étape 8 : Créer le paiement

Appeler la méthode startPaymentSeamlessLite avec la méthode de paiement sélectionnée pour terminer le processus de paiement :

startPaymentSeamlessLite(
 paymentSelected: PaymentSelected,
 callbackPaymentState: ((String?) -> Unit)?,
 showPaymentStatus: Boolean,
)

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 5, pour appliquer 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:

📘

Accès à l'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.