Enroll Payment Methods

On this page, you will find a walk-through guide on enrolling a payment method into a customer account.

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.

Create a customer
Create Customer Session (Exclusive for Checkout workflow)
(Optional) Retrieve Payment Methods Available to Enroll - Checkout workflow/Direct workflow
Enroll Payment Method Checkout workflow/Direct workflow
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.

Customer complementary information

When creating a Customer, certain information is not required but can improve the user's payment experience if provided. Phone, billing address, and shipping address are examples of not mandatory data you can provide.

If you add optional information, be aware of the required mandatory fields.

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

Customer session requirement

Only the Checkout workflow requires the utilization of a customer session. If you are using the Direct workflow (Only available for PCI complaint merchants), you may proceed directly to Step 3 since you will solely be using the id generated in Step 1.

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.

Which payment methods will be available?

When you retrieve the payment methods available to enroll, only the ones which you have connected, created a route, and added to you checkout will be present on the response.

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.