Headless SDK (Payment)

The Headless SDK provides a solution for creating payments while enabling you to have complete control over the UX/UI using our payment_method_token. You can create payments by providing the payment method information or a vaulted token from your customer's previously enrolled payment method. To use the Headless SDK to create payments, follow the next steps.

Step 1: Create a customer

To initiate the payment process, you need to create a customer. You can create a customer by using the Create Customer endpoint. As a response to the API call, you will receive the customer's id created by Yuno.

You can skip this step if you have created the customer before.

Step 2: Create a checkout session

Using the customer id created in Step 1, you will create the checkout_session, which is used to process the payment and grant you access to all payment methods available for the customer, whether they are previously enrolled or not. To create the checkout_session, use the Create Checkout Session endpoint.

Step 3: Retrieve the payment methods available

After creating the checkout_session, you will retrieve all payment methods available to your customer using the Retrieve Payment Methods endpoint. You can configure which payments will be available through the Yuno dashboard.

Enrolled Payment Method

If your customer previously enrolled in one or more payment methods, you will also receive them when using the Retrieve Payment Methods endpoint. You will use the received vaulted_token for those enrolled payment methods to create the One-Time Token and the payment. For additional information on how to enrol payment methods access Headless SDK (Enrollment).

Step 4: Capture the payment method selected

If all payment methods are available, you can display them to your customers so they can select the one to perform the payment. You are responsible for identifying the selected payment method and its details.

When utilizing the Headless SDK, you are responsible for showcasing the available payment methods and collecting the customer's selection. You're also responsible for collecting all necessary information about the payment method. For card payments, you must collect all the required card details.

Step 5: Implement Payment Headless SDK

After capturing the information on the selected payment method, you will use the Headless SDK to generate a One-Time Token. To create the One-Time Token using the Headless SDK, follow the steps below where you need to inform your credentials and the checkout_sessioncreated previously:

  1. Include the library in your project.
  2. Initialize the SDK with your public key, which you will find in the Developers section of the Yuno dashboard.
  3. Start the checkout process by calling the function yuno.apiClientPayment using the desired configuration. This function must be called once the payment method is selected. Once this function is called, the SDK will start collecting all relevant information for 3DS and fraud prevention tools configured in your routing.
  4. Obtain the One-Time Token using the apiClientPayment.generateToken function. At this step, you need to provide all the card and customer information collected on your end.

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.

For more detailed information on how to initiate Yuno's SDK, refer to one of the following sections according to the corresponding platform:




Step 6: Create the payment

Once you receive the One-Time Token, you can use it to create a payment by calling the Create Payment endpoint. The endpoint response will provide the parameter sdk_action_required, which you need to evaluate based on the following conditions:

  • The API response will provide the final payment status when the selected payment method is synchronous. In this scenario, the sdk_action_required is false, so the payment process concludes at this step.
  • Additional SDK actions are necessary for asynchronous payment methods. To inform you about this situation, sdk_action_required will be set to true.

Below is an example of a request used to create a payment. The One-Time Token acquired in Step 5 is informed using payment_method.token.

  "merchant_order_id": "0000022",
  "country": "CO",
  "account_id": "<Your account_id>",
  "description": "Test",
  "amount": {
    "currency": "COP",
    "value": 52000
  "customer_payer": {
    "customer_id": "cfae0941-7234-427a-a739-ef4fce966c79"
  "checkout": {
    "session": "<checkout session>"
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "token": "2cd31999-e44e-4de3-bbe4-179981ff4295"


Yuno advises using the payment status and sub_status as your primary reference for the payment's state during integration. Since a payment might have multiple associated transactions, checking the payment status/sub_status ensures you're informed of the most recent state. The status and substatus provide a clear basis for decision-making regardless of the number of transactions involved.

Step 7: Receive the payment result through a webhook

Yuno recommends configuring Webhooks in the dashboard. Webhooks are the best way to ensure your system is up-to-date with payment progress and status. Since the event notifications trigger automatically, your system won't need to perform recurrent requests to Yuno.