> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless SDK (Enrollment Web)

<Warning>
  **Orientation: Choosing Your Integration Flow**, before you begin, please review the [Official Integration Flow](/docs/sdks/overview/understanding-flows).

  * **Standard Flow ([Full Checkout](/docs/sdks/full-checkout/web-payments))**: Recommended for most merchants. Yuno handles the UI, security, and automatic updates for payment methods.
  * **Custom Flow (This SDK)**: Use this only if you require full control over the UX. **Note**: You will be responsible for manually handling payment statuses, 3DS transitions, and fraud routing data collection.
</Warning>

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](#step-3-create-a-customer-session). To acquire the `customer_session`, you need to:

1. **Create a customer**: A customer is required to enroll in payments. Use the [Create Customer](/reference/customers/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](/reference/customer-sessions-enrollment/create-customer-session) endpoint to receive the `customer_session`.

## Step 1: Include the library in your project

Before proceeding with the Headless SDK implementation, see the [SDK Integration Overview](/docs/sdks/overview/quickstart) for detailed instructions on how to properly integrate the SDK into your project.

The integration guide provides three flexible methods:

1. Direct HTML script inclusion
2. Dynamic JavaScript injection
3. 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.

<Note>
  **TypeScript Library**

  If you are using TypeScript, Yuno provides a [library](https://www.npmjs.com/package/@yuno-payments/sdk-web-types) that you can use to see all available methods in the Yuno Web SDK.
</Note>

## 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`.

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const yuno = await Yuno.initialize(PUBLIC_API_KEY);
```

<Note>
  **Credentials**

  See the credentials page for more information: [/reference/getting-started/authentication](/reference/getting-started/authentication)
</Note>

## 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](/reference/customers/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](/reference/customer-sessions-enrollment/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](/reference/payment-methods-checkout/enroll-payment-method-checkout) 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.

<Warning>
  **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.
</Warning>

## Step 5: Start the enrollment process

Next, you will start the enrollment 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](/docs/sdks/resources/country-coverage) page. |
| `customer_session` | Refers to the current enrollment's [customer session](/docs/basic-concepts/sessions) received as a response to the [Create Customer Session](/reference/customer-sessions-enrollment/create-customer-session) endpoint. Example: `'438413b7-4921-41e4-b8f3-28a5a0141638'`                             |

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const apiClientEnroll = await 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`:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
 "vaulted_token": "9104911d-5df9-429e-8488-ad41abea1a4b",
 "customer": {
   "session": "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
 },
 "status": "ENROLLED"
}
```

<Note>
  **Possible Status Values**

  The `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`
</Note>

<Note>
  **Demo App**

  In addition to the code examples provided, you can access the [Demo App](https://github.com/yuno-payments/yuno-sdk-web) for a complete implementation of Yuno SDKs (clone from the repository).
</Note>

## Error handling

Handle errors returned by the SDK in your app (e.g. failed enrollment, validation errors). For HTTP status and response codes, see [Status and response codes](/reference/getting-started/response-codes) in the API reference.

## Stay Updated

Visit the [changelog](/changelog/web#v1-6-0) for the latest SDK updates and version history.