Enroll Payment Methods

On this page, you will find a walk-through guide on enrolling a payment method into a customer account and get a vauletd_token for future purchases.

📘

Vaulted token

A Vaulted Token is created once a payment method is enrolled and stored with the customer information. You can use the created Vaulted Token to identify the payment method in future payments.

Yuno tokenization service and centralized vault enable you to handle recurring payments, fallbacks, and retries across processors without compromising UX. Today, the following payment methods are available for enrollment in Yuno:

• Cards - Payment Method Type: CARD
• MercadoPago Wallet - Payment Method Type: MERCADO_PAGO_WALLET(Only for SDK integrations)
• Nequi - Payment Method Type: NEQUI(Only for SDK integrations)
• Nupay - Payment Method Type: NU_PAY_ENROLLMENT(Only for SDK integrations)
• Bancolombia Tokenbox - Payment Method Type: BANCOLOMBIA_TOKENBOX(Only for SDK integrations)

Requirements

Before starting the enrollment process, you need to:

• Access your API credentials on the Yuno Dashboard, which are composed by:
  • public-api-key
  • private-secrete-key
  • account_id
• Set up your connections on your Yuno Dashboard account. Add a payment method that requires enrollment.
• Build a route for the payment method to define how it will be processed.
• Configure the checkout builder to make your connected payments available.

Steps summary

To enroll a payment method into a customer account, you will follow the steps listed below.

1. Create a customer
2. Create Customer Session (Exclusive for Checkout workflow)
3. (Optional) Retrieve Payment Methods Available to Enroll - Checkout workflow/Direct workflow
4. Enroll Payment Method Checkout workflow/Direct workflow
5. Retrieve Payment Methods Checkout workflow/Direct workflow

Enroll a payment method

Step 1: Create a customer

Use the Create Customer to register the customer info. You will need to provide personal customer information. In addition, you also need to supply the merchant_customer_id, a unique identifier for the customer used on your system.

At the end of the create a customer process, you will receive an id, which identifies the user within the Yuno system. If you are enrolling a payment method for an existing user, who was previously created and already had an id, you can skip this step.

Step 2: Create a customer session

After creating the customer, you will create a customer session to identify and store customers' information regarding payment preferences. Use the endpoint Create Customer Session to perform the request. Notice that the customer_id required to perform the request is the id you received when creating the customer in Step 1.

From the response of the endpoint Create Customer Session, you will receive the customer_session. It will be used in the payment method enrollment process.

Step 3: Retrieve payment methods to enroll

This is an optional step where you can list all available payment methods the customer can enroll in. If you know which payment method the user will enroll in, you can proceed to Step 4.

To list the available payment methods, you can use one of the available Retrieve Payment Methods To Enroll endpoints. If you are using the Checkout workflow, you will inform the customer_session on the request. While if you are using the Direct workflow, you will provide the customer_id, which refers to the id created in Step 1.

The response to the endpoint Retrieve Payment Methods To Enroll will contain only the payment_methods parameter. It will provide an array of objects with all available payment methods to enroll. You will use the type information to enroll the payment method on the next step.

Step 4: Enroll a payment method

After defining the payment method, you can perform the enrollment using one of the Enroll Payment Method endpoints:

• Checkout workflow: Provide the type related to the chosen payment method to the parameter payment_method_type.
• Direct workflow: Provide the type related to the chosen payment method to the parameter type. (Only available for Card payment methods for PCI compliant merchants)

The user must be redirected to the payment provider page to complete the enrollment process. You will receive this URL in Step 5.

Step 5: Retrieve payment methods

To successfully enroll in the payment method, the customer must provide authorization on the payment provider page. To receive the URL, use one of the following endpoints depending on the workflow you are using:

• Checkout workflow: Use the endpoint Retrieve Payment Method by Customer Session providing the customer_session generated in Step 2. The URL to redirect the user will be available in the parameter provider.redirect.init_url.
• Direct workflow: For the Direct workflow, as it is only available for card enrollments, you will receive the final status in the previous step.

Redirect the user so they provide the required authorization. After the enrollment, you can proceed to the checkout session creation on the next step.

To confirm the enrollment, you can retrieve the enrolled payment methods. The status of the enrolled payment method should be ENROLLED.

📘

Fingerprint

When a credit card is enrolled, you will also find the fingerprint in the API response. It is a field that represents your customer's card throughout your organization. When a customer enrolls a credit card multiple times related to one or many Yuno accounts, multiple vaulted_tokens will be generated, but the fingerprint lets you identify when the same card is used across multiple scenarios.

You will also find the fingerprint in the payment response when a transaction is made using an enrolled credit card.