Headless Checkout

Build your own checkout UI with full control over the payment experience

Headless Checkout gives you complete control over the checkout UI. You build the entire payment form, and Yuno handles tokenization, 3DS challenges, and PCI compliance behind the scenes.

This is the most complex SDK integration. Consider Full Checkout or Seamless Checkout unless you need complete UI control.

How it works

1. You build and render your own payment form
2. Collect card data or use a vaulted token
3. Call generateToken() to create a one-time token via Yuno’s SDK (PCI-safe)
4. Create the payment server-side using the token
5. Handle any 3DS or provider challenges

Integration steps

1. Create a checkout session

Create a checkout session from your server using the Create Checkout Session endpoint.

2. Initialize the SDK

const yuno = await Yuno.initialize({
  publicApiKey: "YOUR_PUBLIC_API_KEY",
});

3. Create the Headless client

const apiClientPayment = yuno.apiClientPayment({
  countryCode: "US",
  checkoutSession: "your-checkout-session-id",
});

4. Generate a one-time token

From raw card data:

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "your-checkout-session-id",
  payment_method: {
    type: "CARD",
    vaulted_token: null,
    card: {
      save: false,
      detail: {
        expiration_month: 11,
        expiration_year: 25,
        number: "4111111111111111", // Yuno sandbox test card number
        security_code: "123",
        holder_name: "ANDREA B",
        type: "DEBIT",
      },
    },
  },
});

From a vaulted token (saved card):

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "your-checkout-session-id",
  payment_method: {
    type: "CARD",
    vaulted_token: "your-vaulted-token",
    card: {
      detail: { security_code: "123" },
    },
  },
});

5. Create the payment (server-side)

await createPayment({
  checkout_session: "your-checkout-session-id",
  one_time_token: oneTimeToken.token,
});

6. Handle 3DS challenges

const challengeData = await apiClientPayment.getThreeDSecureChallenge(
  checkoutSession
);

// Redirect the customer to complete 3DS
window.location.href = challengeData.url;

Check for additional actions after payment creation:

const continueData = await apiClientPayment.getContinuePaymentAction({
  checkoutSession: "your-checkout-session-id",
});

Key methods

Method	Description
yuno.apiClientPayment(config)	Initialize the Headless client
apiClientPayment.generateToken(payload)	Create a one-time token from card data or vaulted token
apiClientPayment.getThreeDSecureChallenge(session)	Get the 3DS challenge URL
apiClientPayment.getContinuePaymentAction(config)	Check for additional actions needed

Card vaulting

Set save: true in the card object to vault the card on successful payment.

Next steps

Full Checkout

Let Yuno handle the entire UI.

Seamless Checkout

SDK convenience with payment method control.