Headless SDK (Enrollment Android)

Yuno's Headless Android SDK lets you enroll in payment methods and tokenize cards, saving them for future use. However, for more frictionless integration, Yuno recommends using one of the other SDK implementations, such as Full or Lite.

Complete enrollment guide

On this page, you will find all the steps related to using the Headless SDK to enrol in a payment method. For a complete guide, including the customer creation, access Headless SDK (Enrollment).

The following steps describe enrolling a payment method using Yuno's Headless SDK..

Requirements

To execute the enrollment process, you need to provide the customer_session to start the enrollment process in Step 3. To acquire the customer_session, you need to:

  1. Create a customer: A customer is required to enroll in payments. Use the Create Customer endpoint to create new customers. In the response, you will receive the customer id, which you use to create the customer session.
  2. Create the customer session: Use the customer id and the Create Customer Session endpoint to receive the customer_session.

A complete enrollment process description is covered in Headless SDK (Enrollment).

Step 1: Include the library in your project.

The first step is to include Yuno SDK in your project through Gradle.

Android SDK Versions

To check all versions available, you can access the release page from the Yuno Android SDK repository.

Then, you can add the repository source, as shown in the following code block:

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

Next, you need to add the Yuno SDK dependency to your application. To accomplish it, add the code below in the build.gradle file.

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

Permissions

Yuno SDK includes, by default, the INTERNET permission, which is required to make network requests.

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

Step 2: Initialize Headless SDK with the public key

To initialize the Headless SDK, you need to import Yuno and provide a valid PUBLIC_API_KEY. If you don't have your API credentials, access the Developers (Credentials) page to check how to retrieve them from the dashboard.

If you haven't implemented a custom application, create one. Then, in the onCreate() method of your application class, call the Yuno.initialize() function to initialize the SDK. The code block below presents an example of using Yuno.initialize().

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      "your api key",
      config: YunoConfig, // This is a data class to use custom configs in the SDK.
    )
  }
}

Step 3: Create a customer session

To start the enrollment process, you need to provide the customer_session. First, you need to create a customer. You need a customer to enroll payments with. Use the Create Customer endpoint to create new customers. In the response, you will receive the customer id, which you use to create the customer session.

After creating the customer, you can create the customer session. Use the customer id and the Create Customer Session endpoint. The customer_session will be provided in the response. You need a new customer_session every time you enroll in a new payment method.

Step 4: Start the enrollment process

Next, you will start the checkout process using the apiClientEnroll function, providing the necessary configuration parameters. The following table lists all required parameters and their descriptions.

ParameterDescription
country_codeThis parameter determines the country for which the payment process is being configured. The complete list of supported countries and their country_code is available on the Country coverage page.
customer_sessionRefers to the current enrollment's customer session received as a response to the Create Customer Session endpoint.
Example: '438413b7-4921-41e4-b8f3-28a5a0141638'

The following code block presents an example of the parameter configuration.

override fun onCreate(savedInstanceState: Bundle?) {
	val apiClientEnroll = Yuno.apiClientEnroll(
    // country can be one of the following: https://docs.y.uno/docs/country-coverage-yuno-sdk
  	countryCode = "CO",
    
		// The customer_session created in https://docs.y.uno/reference/create-customer-session
    customerSession = "eec6578e-ac2f-40a0-8065-25b5957f6dd3",

    context = this ->  it´s the context of your activity 
  )
 }

Step 5: Generate a vaulted token

After collecting all user information, you can start the enrollment. First, you need to create a vaulted_token using the function apiClientEnroll.continueEnrollment. As it is an asynchronous function, you can use try/catch to ensure you will correctly handle triggered errors. Below, you will find an example of creating a vaulted_token:

/**
 * Create Token
 * This function will trigger an error if there is missing data.
 * You can catch this error using a try/catch block.
 */
apiClientEnroll.continueEnrollment( 
 collectedData = EnrollmentCollectedData(
   	// The customer_session created in https://docs.y.uno/reference/create-customer-session
    customerSession = "customer_session",
   	// The necessary info to use the payment method structure
    paymentMethod = EnrollmentMethod(
           type = "CARD",
           card = CardData(
               save = true,
               detail = Detail(
                   expirationMonth = 11,
                   expirationYear = 55,
                   number = "4111111111111111",
                   securityCode = "123",
                   holderName = "Firstname Lastname",
                 	// Use `CardType.DEBIT` or `CardType.CREDIT` for the card type.
                   type = CardType.DEBIT
               ),
           customer = Customer(
             	 // You can check the object here: https://docs.y.uno/reference/the-customer-object
            	 // You create the customer using the following endpoint: https://docs.y.uno/reference/create-customer
               id = "id",
               merchantCustomerId = "merchant_customer_id",
               firstName = "firstName",
             	  email = "[email protected]",
               country = "CO",
               document = Document(
                   documentType = "PAS",
                   documentNumber = "PAS12312"
               ),
             phone = Phone(
                   number = "321123321123",
                   countryCode = "57"
               )
            )
      )
   ),
  context = this
 )

PCI Compliance

Please bear in mind that you are capturing sensitive card data. Therefore, you need to comply with good practices regarding data management. If you don't have a PCI certification, you can't save any card data other than the token provided by the SDK.

The apiClientEnroll.continueEnrollment function returns an Observable type, which is a subclass of LiveData. As a result, you can observe the response as a common LiveData with the following type SingleLiveEvent<Map<String, Any?>>, which is a LiveData that only emits once. The response type is a Map containing the whole response. The following code block presents an example of a complete response after calling the apiClientEnroll.continueEnrollment function.

[
  vaulted_token: "9104911d-5df9-429e-8488-ad41abea1a4b",
  status: "SUCCEEDED" 
  //Other possible status
      CREATED,
      SUCCEEDED,
      PENDING,
      CANCELED,
      EXPIRED,
      ERROR,
      INTERNAL_ERROR 
  customer: [
    session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
  ]
 ]

The code block below presents an example of observing the response:

apiClientPayment.continueEnrollment(data, context).observe(context) { response ->
   val status = response["status"] as String?
   val vauldtedtoken = response["vaulted_token"] as String?
}

Use Webhooks

Consider using the enrollment status received via Webhooks. Yuno recommends always using this status to base and make business decisions on your platform.

Demo App

In addition to the code examples provided, you can access the Yuno repository for a complete implementation of Yuno Android SDKs.