Headless SDK (Enrollment Web)
Recommended SDKWe recommend using the Web Seamless SDK for a smooth integration experience. This option provides a flexible payment solution with pre-built UI components and customization options.
Yuno's Headless SDK lets you enroll in payment methods and tokenize cards, saving them for future usage.
The following steps describe creating a payment 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:
- 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. - Create the customer session: Use the customer
id
and the Create Customer Session endpoint to receive thecustomer_session
.
Step 1: Include the library in your project
Before proceeding with the Headless SDK implementation, see the SDK Integration Overview for detailed instructions on how to properly integrate the SDK into your project.
The integration guide provides three flexible methods:
- Direct HTML script inclusion
- Dynamic JavaScript injection
- NPM module installation
Choose the integration method that best suits your development workflow and technical requirements. After completing the SDK integration, you can proceed with the following steps to implement the headless enrollment functionality.
TypeScript LibraryIf you are using TypeScript, Yuno provides a library that you can use to see all available methods in the Yuno Web SDK.
Step 2: Initialize Headless SDK with the public key
In your JavaScript application, create an instance of the Yuno
class by providing a valid PUBLIC_API_KEY
.
const yuno = await Yuno.initialize(PUBLIC_API_KEY);
CredentialsSee the credentials page for more information: https://docs.y.uno/reference/authentication
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: Create an enrollment payment method object
You need an enrollment payment method object to set Headless SDK integration for enrollment. You can create one using the Enroll Payment Method endpoint. While creating the payment method object, you need to define which payment method your customer can enroll in. Currently, only CARD is available for Headless SDK.
Verify CardIf 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 5: Start the enrollment process
Next, you will start the checkout process using the apiClientEnroll
function, providing the necessary configuration parameters.
Parameters
Configure the enrollment with the following options:
Parameter | Description |
---|---|
country_code | This parameter specifies the country for which the payment process is being set up. Use an ENUM value representing the desired country code. You can find the full list of supported countries and their corresponding codes 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' |
const apiClientEnroll = yuno.apiClientEnroll({
country_code: "CO",
customer_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});
Step 6: 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. The following example shows how to create a vaulted_token
:
const vaultedTokenResponse = await apiClientEnroll.continueEnrollment({
customer_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
payment_method: {
type: "CARD",
card: {
detail: {
expiration_month: 11,
expiration_year: 25,
number: "4111111111111111",
security_code: "123",
holder_name: "ANDREA B",
type: "DEBIT"
}
},
customer: {
}
}
});
After enrolling the new card, you will receive the vaulted_token
, which you can use to make payments in the future without asking for your customer's card information. The following code block shows an example of a response from the apiClientEnroll.continueEnrollment
function:
{
vaulted_token: "9104911d-5df9-429e-8488-ad41abea1a4b",
customer: {
session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
},
status: "ENROLLED"
}
Possible Status ValuesThe
status
field can have one of the following values:
CREATED
EXPIRED
REJECTED
READY_TO_ENROLL
ENROLL_IN_PROCESS
UNENROLL_IN_PROCESS
IN_PROCESS
ENROLLED
DECLINED
CANCELED
ERROR
UNENROLLED
Demo AppIn addition to the code examples provided, you can access the Demo App for a complete implementation of Yuno SDKs.
Related Links
Find more information and version history for the Web SDK below:
- Web SDK v1.3: The latest version with improved UI grouping and multilingual support.
- Web SDK v1.2: Updated
continuePayment
method and optional initialization parameters.
Updated 2 days ago