Headless SDK (Enrollment Android)

This page provides a guide to the Yuno Headless SDK for Android enrollment.

The Yuno Headless SDK for Android provides a flexible, UI-free solution for enrolling payment methods and tokenizing cards.

This SDK offers complete control over the payment method enrollment process, making it ideal for merchants who:

• Need full control over the UI and user experience
• Want to implement custom enrollment flows
• Require advanced integration capabilities

The Headless SDK includes core features like:

• Card tokenization
• Secure payment method enrollment
• Direct API access
• Custom error handling

For merchants requiring a pre-built UI solution or simpler integration, consider using our other SDK implementations:

• Full SDK
• Lite SDK

Requirements

Before starting the Yuno Android SDK integration, ensure your project meets the technical requirements. Also, ensure the following prerequisites are in place:

• You must have an active Yuno account
• You need your Yuno API credentials:
  • account_id
  • public-api-key
  • private-secret-key

You can obtain these credentials from the Developers section of the Yuno dashboard. They are required to:

• Create a customer, which is required before enrolling payment methods
• Create a customer_session, which initializes the enrollment flow

📘

SDK Version Information

Verify the current SDK version by accessing the Release notes or visiting the Yuno Android SDK repository.

Step 1: Create a customer

Create a customer using the Create Customer endpoint before enrolling payment methods.

Prerequisites:

• Active Yuno account
• API credentials

Required for:

• Identifying the person enrolling the payment method
• Enabling saved payment method functionality
• Tracking enrollment history
• Store the customer ID securely for the next step.

Step 2: Create a customer session

Create a new customer_session using the Create Customer Session endpoint:

Prerequisites:

• Customer ID from Step 1
• API credentials

Required actions:

• Include the customer ID in the request
• Store the returned customer_session ID
• Generate a new customer_session for each payment method enrollment.

Step 3: Add the SDK to your project

Prerequisites:

• Android project setup
• Gradle configuration access

1. Add the repository source:

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

2. Add the SDK dependency:

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

📘

Internet Permission Required

The Yuno SDK automatically includes the INTERNET permission, necessary for network requests. Ensure your AndroidManifest.xml contains:

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

Step 4: Initialize Headless SDK with the public key

Retrieve your public API keys from the Yuno dashboard.

If you haven't implemented a custom application, create one. In the onCreate() method of your application class, call the initialize function (Yuno.initialize):

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

Step 5: Create a customer session

To start the enrollment process:

1. Create a customer using the Create Customer endpoint. The response will include the customer id.

2. Create a customer session using:

   • The customer id from step 1
   • The Create Customer Session endpoint

The endpoint response will provide the customer_session value required for enrollment.

🚧

Customer Session Generation

You need to generate a new customer_session each time you enroll a payment method.

Step 6: Create an enrollment payment method object

Create an enrollment payment method object using the Enroll Payment Method endpoint to set up the Headless SDK integration for enrollment. When creating this object, specify which payment method type your customer can enroll in. Currently, the Headless SDK only supports the CARD payment method type.

📘

Card Verification

To verify cards (zero value authorization) before enrollment, include the verify object when creating the payment method object for the customer session. Learn more

Step 7: Start the enrollment process

Use the apiClientEnroll function to start the enrollment process. This function requires configuration parameters that define how the enrollment will be processed. The following table describes the required parameters:

The following code block shows an example of the parameter configuration:

override fun onCreate(savedInstanceState: Bundle?) {
	val apiClientEnroll = Yuno.apiClientEnroll(
  	country_code = "CO",
    
    customerSession = "eec6578e-ac2f-40a0-8065-25b5957f6dd3",

    context = this 
  )
 }

Step 8: Generate a vaulted token

After collecting all required customer information, create a vaulted_token using the apiClientEnroll.continueEnrollment function. Since this is an asynchronous function, use a try/catch block to handle any errors that may occur. The following example shows how to create a vaulted_token:

apiClientEnroll.continueEnrollment( 
 collectedData = EnrollmentCollectedData(
    customerSession = "customer_session",
    paymentMethod = EnrollmentMethod(
           type = "CARD",
           card = CardData(
               save = true,
               detail = Detail(
                   expirationMonth = 11,
                   expirationYear = 55,
                   number = "4111111111111111",
                   securityCode = "123",
                   holderName = "Firstname Lastname",
                   type = CardType.DEBIT
               ),
           customer = Customer(
               id = "id",
               merchantCustomerId = "merchant_customer_id",
               firstName = "firstName",
               email = "[email protected]",
               country = "CO",
               document = Document(
                   documentType = "PAS",
                   documentNumber = "PAS12312"
               ),
             phone = Phone(
                   number = "321123321123",
                   country_code = "57"
               )
            )
      )
   ),
  context = this
 )

The apiClientEnroll.continueEnrollment function returns an Observable type that extends LiveData. You can observe the response as a standard LiveData with type SingleLiveEvent<Map<String, Any?>>. This LiveData emits only once and returns a Map containing the complete response. Below is an example response from calling apiClientEnroll.continueEnrollment:

{
  "vaulted_token": "9104911d-5df9-429e-8488-ad41abea1a4b",
  "status": "SUCCEEDED",
  "customer": {
    "session": "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
  }
}

The following code block shows 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?
}

📘

Webhook Status Tracking

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