Headless SDK (Payment Web)

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

const apiClientPayment = await yuno.apiClientPayment({
  country_code: "US",
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});

// Wrong: calling everything at "Pay" click time
payButton.onclick = async () => {
  const apiClientPayment = await yuno.apiClientPayment({ country_code, checkout_session });
  const oneTimeToken = await apiClientPayment.generateToken({ checkout_session, payment_method });
};
// The fraud provider's beacon may not have loaded in time, so the fingerprint can be missing from the token

// Correct: preload the fraud fingerprint when the form renders
await yuno.executeFraudCheck({ checkout_session, country_code });

// Later, when the customer clicks "Pay":
payButton.onclick = async () => {
  const apiClientPayment = await yuno.apiClientPayment({ country_code, checkout_session });
  const oneTimeToken = await apiClientPayment.generateToken({ checkout_session, payment_method });
  // The fingerprint is already cached, no race condition
};

{
  "merchant_order_id": "0000022",
  "country": "US",
  "account_id": "<Your account_id>",
  "description": "Test",
  "amount": {
    "currency": "USD",
    "value": 500
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79"
  },
  "checkout": {
    "session": "<checkout session>"
  },
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "type": "CARD",
    "token": "2cd31999-e44e-4de3-bbe4-179981ff4295"
  }
}

const data = await apiClientPayment.getThreeDSecureChallenge(checkoutSession?: string): Promise<{url: string}>

document.querySelector('#element').innerHTML = `
   <iframe
     src="${data.url}&embedded=true"
     height="700px"
     width="100%"
     border="0"
     frameBorder="0">
   </iframe>
 `;

window.addEventListener('message', (event) => {
   if (
        !event.origin.toLocaleLowerCase().includes('sdk-3ds') ||
        event?.data?.origin !== 'CHALLENGE'
   ) {
     return
   }
   document.querySelector('#element').innerHTML = '';
   if (event.data.status === 'ERROR') {
     document.querySelector('#element').innerHTML = 'There was an error';
   } else {
     document.querySelector('#element').innerHTML = 'Challenge was finished';
   }
});

const data = await apiClientPayment.getContinuePaymentAction({ checkoutSession: string }): Promise<ContinuePaymentAction>

type ContinuePaymentAction = {
  type: Provider.Type;
  action: Provider.Action;
  payment_code?: {
    code: string;
    reference: string;
    expiration_time?: number;
  };
  image?: {
    type: string;
    value: string;
    reference: string;
    expiration_time?: number;
    additional_data?: Record<string, undefined>;
  };
  redirect?: {
    init_url: string;
    success_url: string;
    error_url: string;
  };
  otp?: {
    length: number;
    expiration_time: number;
    retries: {
      accepts: boolean;
      number: number;
    };
    resend: {
      timer: number;
      number: number;
    };
    payment_instructions: string;
  };
  three_d_secure_redirect?: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
  transaction_id?: string;
  request_html?: {
    body?: Record<string, string>;
    headers?: Record<string, string>;
    method?: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
    url: string;
  };
  sdk_provider?: {
    client_id?: string;
    intent?: string;
    components?: string;
    gateway: string;
    init_url?: string;
    merchant_id: string;
    amount: {
      currency: string;
      value: number;
    };
    protocol_version?: string;
    provider_id?: string;
    payment_methods?: string[];
    supported_networks?: string[];
    session?: {
      epoch_timestamp: number;
      expires_at: number;
      merchant_session_identifier: string;
      nonce: string;
      merchant_identifier: string;
      domain_name: string;
      display_name: string;
      signature: string;
      operational_analytics_identifier: string;
      retries: number;
      psp_id: string;
    };
    provider_token_id?: string;
  };
  render_html?: {
    content?: string;
    redirect_url?: string;
  };
  info?: {
    screen_info?: string;
  };
  render_iframe: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
};

export declare namespace Provider {
  enum Type {
    MERCADO_PAGO = "MERCADO_PAGO",
    WOMPI = "WOMPI",
    PAYMENTEZ = "PAYMENTEZ",
    GETNET = "GETNET",
    TRANSFEERA = "TRANSFEERA",
    CYBERSOURCE_3DS = "CYBERSOURCE_3DS",
    NETCETERA_3DS = "NETCETERA_3DS",
    XENDIT_3DS = "XENDIT_3DS",
    DLOCAL = "DLOCAL",
    CIELO = "CIELO",
    INSWITCH = "INSWITCH",
    PAGALEVE = "PAGALEVE",
    UNLIMINT_3DS = "UNLIMINT_3DS"
  }

  enum Action {
    PAYMENT_CODE = "PAYMENT_CODE",
    IMAGE = "IMAGE",
    REDIRECT_URL = "REDIRECT_URL",
    FORM = "FORM",
    INFO = "INFO",
    OTP = "OTP",
    SDK_PROVIDER = "SDK_PROVIDER",
    THREE_D_SECURE_REDIRECT_URL = "THREE_D_SECURE_REDIRECT_URL",
    REQUEST_HTML = "REQUEST_HTML",
    RENDER_HTML = "RENDER_HTML",
    RENDER_IFRAME = "RENDER_IFRAME"
  }
}

if (data.action === "REDIRECT_URL") {
  window.location.href = data.redirect.init_url;
}

const compositeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  total: { currency: "USD", value: 100 },
  payment_method: [
    {
      type: "CARD",
      amount: { currency: "USD", value: 60 },
      card: {
        detail: {
          expiration_month: 11,
          expiration_year: 29,
          number: "4111111111111111",
          security_code: "123",
          holder_name: "ANDREA B",
          type: "CREDIT"
        }
      }
    },
    {
      type: "CARD",
      amount: { currency: "USD", value: 40 },
      vaulted_token: "aad8578e-ac2f-40a0-8065-25b5957f6555",
      card: {
        detail: {
          security_code: "123"
        }
      }
    }
  ]
});

{
  "token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
  "checkout_session": "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  "expires_at": "2026-10-22T15:30:00Z"
}

{
  "merchant_order_id": "0000023",
  "country": "US",
  "account_id": "<Your account_id>",
  "description": "Order paid with two cards",
  "amount": {
    "currency": "USD",
    "value": 100
  },
  "customer_payer": {
    "first_name": "Andrea",
    "last_name": "B",
    "email": "andrea.b@example.com"
  },
  "checkout": {
    "session": "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
  },
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
    "capture": true
  },
  "callback_url": "https://merchant.example.com/checkout/return"
}

// showChallenge renders the URL in an iframe, as in Step 6,
// and resolves with event.data.status when the CHALLENGE message arrives.
// waitForCardResult asks your server to poll GET /v2/payments/{payment_id}
// until the THREE_D_SECURE transaction of that card is no longer PENDING.
async function runCardChallenges(checkoutSession, paymentId, cardCount) {
  for (let sequence = 1; sequence <= cardCount; sequence++) {
    const { url } = await apiClientPayment.getThreeDSecureChallenge(checkoutSession);

    if (!url) {
      return; // No card is waiting for 3DS
    }

    const status = await showChallenge(url);

    if (status === 'ERROR') {
      return; // The payment has ended: do not offer the other card
    }

    await waitForCardResult(paymentId, sequence);
  }
}