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

Headless SDK (Paiement Android)


👍

SDK recommandé

Pour une expérience d'intégration fluide, nous recommandons d'utiliser le SDK Seamless Android. Cette option fournit 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 Headless SDK Android de Yuno pour les paiements.

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

  • Ont besoin d'un contrôle total sur l'interface utilisateur et l'expérience client du paiement
  • Souhaitent créer des flux de paiement personnalisés
  • Nécessitent des capacités d'intégration avancées

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

  • Accès direct à l'API pour le traitement des paiements
  • Génération de Token pour les méthodes de paiement
  • Gestion de l'authentification 3DS
  • Collecte de données sur la prévention de la fraude

Pour les commerçants qui préfèrent une solution d'interface utilisateur préconstruite, veuillez envisager d'utiliser notre Full SDK ou Lite SDK à la place.

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
📘

Dernière version du SDK

Consultez les Notes de version ou visitez le dépôt 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 méthode de paiement 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 dans les étapes ultérieures

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

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

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

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

Ajoutez la dépendance du SDK Yuno à votre application dans le fichier build.gradle :

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

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

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

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

Importez Yuno et fournissez une PUBLIC_API_KEY valide pour initialiser le Headless SDK. Si vous n'avez pas vos identifiants API, consultez la page Développeurs (Identifiants) pour savoir comment les récupérer depuis le tableau de bord.

Créez une classe d'application personnalisée si vous ne l'avez pas déjà fait. Dans la méthode onCreate() de votre classe d'application, initialisez le SDK en appelant la fonction Yuno.initialize() :

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

Étape 5 : Démarrer le processus de paiement

Appelez la fonction apiClientPayment après que votre client ait sélectionné une méthode de paiement pour démarrer le processus de paiement. Cette fonction nécessite des paramètres de configuration et initie la collecte d'informations nécessaires pour l'authentification 3DS et les outils de prévention de la fraude configurés dans votre routage. routage.

Le tableau suivant décrit les paramètres requis :

Paramètres

Description

country_code

  • Ce paramètre détermine le pays pour lequel le processus de paiement est configuré.
  • La liste complète des pays supporter et leur country_code est disponible sur la page  Couverture par Pays .

checkout_session

  • Example: '438413b7-4921-41e4-b8f3-28a5a0141638'

Le bloc de code suivant montre un exemple de configuration des paramètres :

 val apiClientPayment = Yuno.apiClientPayment(
   country_code = "US",
 checkoutSession "74bf4b96-6b35-42a6-8c73-2fe094c34ca9",
   context = this
)

Étape 6 : Générer un token

Après avoir recueilli les informations relatives à l'utilisateur, créez un token à usage unique (OTT) en utilisant la fonction apiClientPayment.generateToken . Comme il s'agit d'une fonction asynchrone, utilisez un bloc try/catch pour gérer les erreurs potentielles. Les exemples suivants montrent deux 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 de carte requises.
  2. Exemple 2: Créer un token à usage unique en utilisant les informations du vaulted_token .

Avantages de l'utilisation d'un token sécurisé

Lorsque vous utilisez un token sécurisé avec le SDK, toutes les informations de fraude des fournisseurs que vous avez configurés dans votre routage de carte sont collectées et attachées au token à usage unique. Vous pouvez également ajouter des informations de versement et un code de sécurité si le fournisseur l'exige.


apiClientPayment.generateToken(
   collectedData = TokenCollectedData(
 checkoutSession "checkout_session",
       paymentMethod = PaymentMethod (
           type = "CARD",
 vaultedToken  null,
           card = CardData(
               save = true,
               detail = Detail(
                   expirationMonth = 11,
                   expirationYear = 55,
                   number = "4111111111111111",
                   securityCode = "123",
                   holderName = "Prénom Nom",
                   type = CardType.DEBIT
               ),
               installment = Installment(
                   id = "id",
                   value = 12
               )
           ),
client = Client(
id = « id »,
merchantCustomerId = « merchant_customer_id »,
prénom = « prénom »,
nom = « nom »,
sexe = Sexe.NB,
dateDeNaissance = « JJ/MM/AAAA »,
 email  «[email ] »,
               country = "US",
document = Document(
documentType = "PAS",
documentNumber = "PAS12312"),

phone = Phone(
number = "321123321123",
country_code = "1")
)
),

context = this
)


apiClientPayment.generateToken(
   collectedData = TokenCollectedData(
 checkoutSession "checkout_session",
       paymentMethod = PaymentMethod(
           type = "CARD",
 vaultedToken "a1c7c5d1-b260-4dc6-909a-8368704233cf",
           card = CardData(
               save = true,
               detail = Detail(
                   expirationMonth = 11,
                   expirationYear = 55,
                   number = "4111111111111111",
                   securityCode = "123",
                   holderName = "Prénom Nom",
                   type = CardType.DEBIT
               ),
               installment = Installment(
                   id = « id »,
                   value = 12
               )
           ),
           customer = Customer(
               id = « id »,
               merchantCustomerId = « merchant_customer_id »,
               firstName = « firstName »,
               lastName = « lastName »,
               lastName = « lastName »,
               gender = Gender.NB,
               dateOfBirth = « JJ/MM/AAAA »,
 email  «[email ] »,
               country = « CO »,
               document = Document(
                   documentType = « PAS »,
                   documentNumber = « PAS12312 »
               ),
               phone = Phone(
                   number = "321123321123",
 countryCode "57"
               )
           )
       )
   ),
   context = this
)

Le champ apiClientPayment.generateToken  retourne un type Observable, qui est une sous-classe de LiveData. Vous pouvez observer la réponse comme un  LiveData commun de type SingleLiveEvent<Map<String, Any?>>qui est un LiveData qui n'émet qu'une seule fois. Le type de réponse est une Map contenant la réponse complète. Le bloc de code suivant montre des exemples de réponses après l'appel de la fonction apiClientPayment.generateToken .

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

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

La réponse du endpoint fournit le paramètre sdk_action_required qui définit si des actions supplémentaires sont nécessaires.

Le bloc de code suivant montre un exemple d'observation de la réponse :

apiClientPayment.generateToken(data, context).observe(context) { response ->
   val token = response[token"] as String ?
   val error = response["error"] as String ?
}

Étape 7 : Créer le paiement

Après avoir généré le token à usage unique, créez le paiement en appelant le endpoint  Créer Paiement. Incluez le token à usage unique obtenu à  l'Étape 6 dans le paramètre payment_method.token de votre requête. Le bloc de code suivant montre un exemple de requête de création de paiement :

{
  "merchant_order_id": "0000022",
  "country": "US",
  "account_id": "<Your account_id>",
  "description": "Test",
  "amount": {
    "currency": "USD",
    "value": 500
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79"
  },
  "checkout": {
    "session": "<checkout session>"
  },
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "type":"CARD",
    "token": "2cd31999-e44e-4de3-bbe4-179981ff4295"
  }
}

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 false dans la réponse de l'API et le processus de paiement se termine
  • Pour les flux de paiement nécessitant une interaction SDK supplémentaire, sdk_action_required sera true. Lorsque cela se produit, passez à  l'Étape 8  pour les étapes suivantes.

Étape 8 : Obtenir l'URL du défi 3DS (si requis)

Lorsqu'un paiement nécessite une authentification 3DS, un défi supplémentaire peut être nécessaire pour vérifier l'identité du client. Pour plus de détails sur ce processus, voir la page 3D Secure. Si un défi de vérification 3DS est requis, la réponse du l'endpoint Créer un paiement inclura :

  • A THREE_D_SECURE .
  • Un statut égal à PENDING et un sous-statut égal à WAITING_ADDITIONAL_STEP
  • sdk_action_required = true

Appelez la fonction getThreeDSecureChallenge et fournissez la checkoutSession utilisée pour créer le paiement afin d'obtenir l'URL du défi 3DS. Après avoir obtenu l'URL, redirigez votre client pour qu'il complète le défi. Le bloc de code suivant montre comment utiliser la fonction getThreeDSecureChallenge :

fun ApiClientPayment.getThreeDSecureChallenge(
   context: Context,
   checkoutSession: String? = null,
): SingleLiveEvent<ThreeDSecureChallengeResponse>

Le champ getThreeDSecureChallenge retourne la classe de données ThreeDSecureChallengeResponse , décrite dans le bloc de code suivant :

data class ThreeDSecureChallengeResponse(
   val type : Chaîne,
   val data : Chaîne,
)

Le champ type peut retourner ERROR ou URL, définissant si la fonction a retourné une URL valide pour le défi :

  • Si type = URL, data contiendra l'URL à laquelle votre client doit accéder pour compléter le défi 3DS.
  • Si type = ERROR, data contiendra le message d'erreur, informant de la source du problème.

Le bloc de code suivant montre un exemple de la façon dont vous pouvez observer la réponse de ThreeDSecureChallengeResponse:

apiClientPayment.getThreeDSecureChallenge(this) ?.observe(this) {
   if (it.type == "URL") {
   } else 
}

Lorsque le type de réponse est "URL", vous pouvez charger l'URL du défi 3DS dans la vue de votre choix (WebView, onglet personnalisé ou navigateur). Si le type de réponse n'est pas "URL", cela indique qu'une erreur s'est produite et vous devez la traiter de manière appropriée en affichant un message d'erreur à l'utilisateur.

Pour terminer le défi 3DS, redirigez les clients vers l'URL renvoyée par getThreeDSecureChallenge(context). Une fois l'opération réussie, les clients sont automatiquement redirigés vers le callback_url que vous avez spécifié lors de la création de la checkout_session à l'aide du endpoint  Créer une session de paiement . L'exemple suivant montre comment charger l'URL du défi 3DS dans une WebView :

val webView = WebView(this)
webViewContainer.addView(
   webView,
   ConstraintLayout.LayoutParams(
       ConstraintLayout.LayoutParams.MATCH_PARENT,
       ConstraintLayout.LayoutParams.MATCH_PARENT
   )
)
webView.settings.javaScriptEnabled = true
webView.addJavascriptInterface(
   object {
       @JavascriptInterface
       fun messageFromWeb(data: String?) {
       }
   },
   "Android"
)
webView.loadUrl(url)

L'interface JavaScript doit utiliser le nom messageFromWeb(data : String?) et être ajoutée avec le nom Android. Cela vous permet de capturer les événements de défi et de déterminer quand ils se terminent.

Pour finaliser le flux de paiement du Headless SDK :

  1. Utilisez les Webhooks Yuno pour recevoir des notifications concernant :

    • Le résultat du défi 3DS
    • Le statut final du paiement

  2. Optionnellement, récupérez les détails du paiement à l'aide de l'endpoint Récupérer le paiement par identifiant.

Pour le guide d'implémentation de paiement complet, consultez Headless SDK (Paiement).

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.

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.

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.

📘

Accéder à 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.

Mise à jour il y a 3 mois