指南
状态页面Dashboard预约演示
开始键入搜索...

Headless SDK Payment 网络 Payment


👍

推荐的 SDK

我们建议使用WebSeamless SDK，以获得流畅的集成体验。该选项提供了灵活的支付解决方案，预置了用户界面组件和自定义选项。

Yuno 的Headless SDK 可让您创建付款。请注意，使用Headless SDK 时，您需要通过 API 请求并发送支付提供商在其 API 中生成支付所需的所有必填字段。

Yuno 的Headless SDK 可让您在两种不同的情况下创建支付：

以下步骤介绍了如何使用 Yuno 的Headless SDK 创建付款。

第 1 步：在项目中加入程序库

在继续实施Headless SDK 之前，请参阅SDK 集成概述，了解如何将 SDK 正确集成到项目中的详细说明。

集成指南提供了三种灵活的方法：

  1. 直接包含 HTML 脚本
  2. 动态 JavaScript 注入
  3. 安装 NPM 模块

选择最适合您的开发工作流程和技术要求的集成方法。完成 SDK 集成后，您可以继续执行以下步骤来实现无头结账功能。

📘

TypeScript 库

如果您使用的是 TypeScript，Yuno 提供了一个库，您可以使用该库查看 Yuno Web SDK 中的所有可用方法。

步骤 2：使用公钥Initialize Headless SDK

在您的 JavaScript 应用程序中，创建一个 Yuno 类提供一个有效的 PUBLIC_API_KEY.

const yuno = await YunoinitializePUBLIC_API_KEY)；
📘

证书

更多信息，请参阅全权证书页面： https://docs.y.uno/reference/authentication

步骤 3：开始结账

接下来，您将使用 apiClientPayment 函数，提供必要的配置参数。

参数

使用以下选项配置付款：

参数说明
country_code该参数用于指定正在设置payment 流程的国家。使用 ENUM 值代表所需的国家代码。支持的国家及其相应代码的完整列表可在 覆盖国家 page.
checkout_session指当前付款的结账会话，该会话是使用 创建结账会话 endpoint。例如 '438413b7-4921-41e4-b8f3-28a5a0141638'
const apiClientPayment = yuno.apiClientPayment({
  country_code: "US",
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});

步骤 4：生成token

收集完所有用户信息后，就可以开始付款了。首先，您需要使用函数 apiClientpayment.generateToken.由于这是一个异步函数，您可以使用 try/catch 以确保正确处理触发的错误。以下示例展示了创建一次性token的不同情况：

  1. 例 1：使用银行卡作为支付方式创建一次性token ，并包含所有必要的银行卡信息。
  2. 示例 2:使用 vaulted_token 信息。
📘

使用拱顶Token的好处

当您使用 SDK 的保险库token 时，您在卡路由中配置的提供商的所有欺诈信息都会被收集并附加到一次性token中。此外，如果提供商需要，您还可以添加分期付款信息和安全代码。

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: null,
    card: {
      save: false,
      detail: {
        expiration_month: 11,
        expiration_year: 25,
        number: "4111111111111111",
        security_code: "123",
        holder_name: "ANDREA B",
        type: "DEBIT"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    },
    customer: {},
    device_fingerprint: "0753b47f-bb43-86ab-647b-d735b67baac6",
    third_party_session_id: "QbJU2KolVUm1fhQR0s9qgrS0ArEQmEfE"
  }
});

例 1 的参数

参数说明
checkout_session使用创建结账会话endpoint创建的结账会话
payment_method.type付款方式类型，设置为 "卡"
payment_method.vaulted_token可选：如果您以前注册过付款方式，请使用该选项
card.save可选：设置为 "true "可为卡生成一个保险库token
card.detail卡信息，包括卡号、有效期、安全码和持卡人姓名
card.detail.type卡类型："借记卡 "或 "信用卡
card.installment可选：仅在配置分期付款计划时才需要
customer可选：客户信息对象
device_fingerprint可选：仅在配置了欺诈筛查时才需要
third_party_session_id可选：仅在存在第三方配置时才需要
const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: "aad8578e-ac2f-40a0-8065-25b5957f6555",
    card: {
      detail: {
        security_code: "123"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    }
  }
});

例 2 的参数

参数说明
checkout_session使用创建结账会话endpoint创建的结账会话
payment_method.type付款方式类型，设置为 "卡"
payment_method.vaulted_token使用之前注册的支付方式中的保险库token
card.detail.security_code注册卡的安全码
card.installment可选：仅在配置分期付款计划时才需要

下面的代码块显示了 apiClientPayment.generateToken 上述两个示例的函数响应：

{
  "token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
  "vaulted_token": null,
  "vault_on_success": false,
  "type": "CARD",
  "card_data": {
    "holder_name": "ANDREA B",
    "iin": "41111111",
    "lfd": "1111",
    "number_length": 16,
    "security_code_length": 3,
    "brand": "VISA",
    "type": "CREDIT",
    "category": "CREDIT",
    "issuer_name": "JPMORGAN CHASE BANK N A",
    "issuer_code": null
  },
  "customer": {
    "first_name": "Cesar",
    "last_name": "Sanchez",
    "email": "[email protected]",
    "gender": "",
    "phone": null,
    "billing_address": null,
    "document": null,
    "browser_info": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "accept_header": "*/*",
      "accept_content": "*/*",
      "accept_browser": "*/*",
      "color_depth": "24",
      "screen_height": "1080",
      "screen_width": "2560",
      "javascript_enabled": true,
      "java_enabled": false,
      "browser_time_difference": "300",
      "language": "en-US"
    },
    "device_fingerprint": "19764508-c9df-a90b-a365-83b2d718c12e"
  },
  "installment": null,
  "country": "CO"
}
{
  token: 'ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d',
  vaulted_token: aad8578e-ac2f-40a0-8065-25b5957f6555,
  vault_on_success: false,
  type: 'CARD',
  card_data: {
    holder_name: 'ANDREA B',
    iin: '41111111',
    lfd: '1111',
    number_length: 16,
    security_code_length: 3,
    brand: 'VISA',
    type: 'CREDIT',
    category: 'CREDIT',
    issuer_name: 'JPMORGAN CHASE BANK N A',
    issuer_code: null,
  },
  customer: {
    first_name: 'Cesar',
    last_name: 'Sanchez',
    email: '[email protected]',
    gender: '',
    phone: null,
    billing_address: null,
    document: null,
    browser_info: {
      user_agent:
        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
      accept_header: '*/*',
      accept_content: '*/*',
      accept_browser: '*/*',
      color_depth: '24',
      screen_height: '1080',
      screen_width: '2560',
      javascript_enabled: true,
      java_enabled: false,
      browser_time_difference: '300',
      language: 'en-US',
    },
    device_fingerprint: '19764508-c9df-a90b-a365-83b2d718c12e',
  },
  installment: null,
  country: 'CO',
}

步骤 5：创建Payment

收到一次性token后，您可以使用 创建支付endpoint 以获取最终付款结果。您将在 步骤 4 通过请求的 payment_method.token 参数。以下代码块显示了创建付款的请求示例：

{
  "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"
  }
}

endpoint 响应提供 sdk_action_required 参数，用于定义是否需要采取额外行动来完成支付：

  • 如果客户选择的是同步支付方式，则会立即完成支付。在这种情况下，字段 sdk_action_required 在 API 响应中将是 false付款流程到此结束。
  • 当需要 SDK 的额外交互来完成支付流程时、 sdk_action_required 将 true.如果是这种情况，您需要按照以下说明进行操作 步骤 6.

步骤 6：获取 3DS 挑战 URL

如 "3DS卡验证"页面所述，使用3DS付款可能需要额外的验证，以检查客户的身份。如果需要与3DS验证挑战相关的额外验证步骤，创建支付 endpoint 的响应将包含以下信息：

  • A THREE_D_SECURE 交易类型。
  • 状态等于 PENDING 和子状态等于 WAITING_ADDITIONAL_STEP.
  • "(《世界人权宣言》) sdk_action_required 设为 true.

要获取 3DS 挑战 URL，应调用 getThreeDSecureChallenge 功能，提供 checkoutSession 用于创建付款。

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

如果该卡不需要验证客户身份的挑战，则 url 将返回 null.

在网络浏览器中，可以在新标签页或 IFrame 中打开 URL。要在 iframe 中打开 URL，必须设置参数 embedded = true.如果没有，可以省略该参数，其默认值为 false.以下代码块显示了在 IFrame 中显示 3DS 挑战内容的示例：

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';
   }
});

您有责任将客户重定向到由 redirect_url 来完成挑战。一旦客户成功完成 3DS 挑战，他们将自动跳转到 callback_url时提供的 checkout_session 与 创建结账会话 endpoint。

要完成Headless SDK 支付流程，您需要使用Yuno Webhooks，它会及时通知您 3DS 挑战的结果和最终支付状态。使用网络钩子可确保您收到有关支付交易进度的实时更新。除网络钩子外，您还可以使用 "按 ID 检索付款"endpoint检索付款信息。

第 7 步：获取付款行动

有时，付款可能需要额外的操作才能继续付款流程。要确定需要执行什么操作，应调用 getContinuePaymentAction 方法，提供 checkoutSession 用于创建付款。

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

"(《世界人权宣言》) getContinuePaymentAction 方法返回一个 ContinuePaymentAction 对象，该对象描述了继续付款流程所需的具体操作，具体取决于提供商和所需的具体步骤。

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;
  };
};

ContinuePaymentAction 字段

现场说明
type付款提供商类型（如 MERCADO_PAGO、DLOCAL 等）
action继续付款所需的具体操作（如 REDIRECT_URL、OTP 等）
payment_code当支付提供商为现金支付发出支付代码时使用
image在必须向用户显示图像（如 QR 码）时使用
redirect当第三方支付流需要重定向时使用
otp在流程需要 OTP（一次性密码）验证时使用
three_d_secure_redirect用于将用户重定向到安全验证步骤的 3DS 流程
transaction_id唯一交易 ID（如有
request_html用于渲染带有动态 HTML 和页眉的付款表单
sdk_provider用于基于 SDK 的提供商（如 Apple Pay、Google Pay）
render_html用于在应用程序中直接显示 HTML 内容
info一般信息或消息（如显示确认消息）
render_iframe当提供程序需要渲染一个 iframe 供用户交互时使用

提供商类型和操作

以下枚举定义了支持的支付提供商和可能的操作：

导出声明命名空间 Provider {
  枚举类型 {
    mercado_pago = "mercado_pago"、
    wompi = "wompi"、
    payez = "payez"、
    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" }.
  }

  枚举动作 {
    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".
  }
}

提供商类型和操作

提供商类型说明
MERCADO_PAGOMercado Pago 支付服务提供商
WOMPIWompi 支付提供商
PAYMENTEZPaymentez 支付服务提供商
GETNETGetnet 支付提供商
TRANSFEERATransfeera 支付服务提供商
CYBERSOURCE_3DS网络资源 3DS 提供商
NETCETERA_3DSNetcetera 3DS 提供商
XENDIT_3DSXendit 3DS 提供商
DLOCAL本地支付提供商
CIELOCielo 支付提供商
INSWITCHInswitch 支付提供商
PAGALEVEPagaleve 支付提供商
UNLIMINT_3DS无限制 3DS 提供商
行动类型说明
PAYMENT_CODE向用户显示付款代码
IMAGE显示图像（如 QR 码）
REDIRECT_URL将用户重定向到外部页面
FORM渲染表单以收集用户输入
INFO显示信息屏幕
OTP要求用户输入 OTP
SDK_PROVIDER使用 SDK 处理付款
THREE_D_SECURE_REDIRECT_URL启动 3DS 验证
REQUEST_HTML提交 HTML 表格请求
RENDER_HTML在应用程序中渲染静态 HTML
RENDER_IFRAME为提供商用户界面渲染 iframe

处理不同的操作类型

根据 action 字段，就应该相应地处理每种类型的操作：

REDIRECT_URL 行动

行动时 REDIRECT_URL中提供的 URL。 data.redirect.init_url:

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

其他行动类型

每种操作类型都需要根据所提供的数据进行特定处理：

  • PAYMENT_CODE：向用户显示付款代码和参考信息
  • 图像：向用户显示二维码或其他图像
  • OTP： 向用户显示 OTP 输入表单
  • SDK_PROVIDER：Initialize 特定提供商的 SDK
  • RENDER_IFRAME：显示带有提供程序界面的 iframe
📘

付款操作处理

处理每种操作类型的具体实现取决于应用程序的用户界面框架和要求。确保您能处理配置的支付提供商可能返回的所有操作类型。

📘

演示应用程序

除提供的代码示例外，您还可以访问演示应用程序，了解 Yuno SDK 的完整实施过程。

保持更新

请访问更新日志，了解最新的 SDK 更新和版本历史。

3 个月前已更新