Headless SDK (Enrollment Android)
The Yuno Headless SDK for Android provides a flexible, UI-free solution for enrolling payment methods and tokenizing cards.
Recommended SDKs
We recommend using the Android Full SDK or the Android Lite SDK for a smooth integration experience. These options provide a complete solution with built-in forms and validation.
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:
Requirements
Before starting the Yuno Android SDK integration, make sure your project meets the technical requirements. In addition, ensure the following prerequisites are in place:
- You must have an active Yuno account
- To perform the integration, you'll 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
Access the Release notes or the Yuno Android SDK repository to verify the last SDK version available.
Step 1: Create a customer
Before enrolling payment methods, you need to create a customer using the Create Customer endpoint.
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; you'll need it 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
- Add the repository source:
maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }
- Add the SDK dependency:
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 4: Initialize Headless SDK with the public key
First, 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
) as shown in the example below:
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 5: Create a customer session
To start the enrollment process, you need to:
-
Create a customer using the Create Customer endpoint. The response will include the customer
id
. -
Create a customer session using:
- The customer
id
from step 1 - The Create Customer Session endpoint
- The customer
The endpoint response will provide the customer_session
value required for enrollment.
You need to generate a new customer_session
each time you enroll a payment method.
Step 6: Create an enrollment payment method object
To set up the Headless SDK integration for enrollment, you need to create an enrollment payment method object using the Enroll Payment Method endpoint. 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.
Verify card
If you want to verify cards (zero value authorization) before enrollment, you need to provide the verify
object when creating the payment method object for the customer session.
Step 7: Start the enrollment process
To start the enrollment process, use the apiClientEnroll
function. This function requires configuration parameters that define how the enrollment will be processed. The following table describes the required parameters.
Parameter | Description |
---|---|
country_code | This 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_session | Refers 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 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 demonstrates how to create 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 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 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.
Updated 15 days ago