银行卡

要设置银行卡支付，您可以按照基本设置说明进行操作。如果用户需要输入额外数据才能完成支付（例如使用巴西的银行卡付款）或需要通过3-D Secure验证，请按照以下说明操作。

额外用户数据输入

添加支付UI表单容器。

示例：

Copy

Full screen

Small screen

1<div id="form-container"></div>

添加show_fields事件处理以显示新字段。

示例：

Copy

Full screen

Small screen

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    case 'show_fields':
4      this.handleShowFieldsAction(nextAction);
5  }
6});

创建用于输入额外数据的支付UI字段，例如持卡人姓名或账单地址。

通过submitButtonText字段，可为支付表单的每个步骤设置默认按钮文案，例如继续。

示例：

Copy

Full screen

Small screen

 1private handleShowFieldsAction(nextAction: ShowFieldsAction): void {
 2  this.form.fields = nextAction.data.fields;
 3  if (nextAction.data.submitButtonText) {
 4    this.updateSubmitButton(nextAction.data.submitButtonText);
 5  }
 6  this.updateForm(this.form);
 7}
 8
 9private updateForm(form: Form): void {
10  const visibleFields = form.fields.filter((field) => {
11    return field.isVisible === '1';
12  });
13
14  const controls = visibleFields.map((field) => {
15    if (field.type === 'select') {
16      return this.getSelectControl(field);
17    }
18
19    if (field.type === 'check') {
20      return this.getCheckboxControl(field);
21    }
22
23    if (field.type === 'text') {
24      if (field.name === 'card_number') {
25        return this.getCardNumberControl(field);
26      }
27
28      if (field.name === 'phone') {
29        return this.getPhoneControl(field);
30      }
31
32      return this.getTextControl(field);
33    }
34
35    return null;
36  });
37
38  this.renderForm(controls);
39}
40
41private getSelectControl(field: Field): HTMLElement {
42  const control = new SelectComponent();
43  control.setAttribute('name', field.name);
44  return control;
45}
46
47private getCheckboxControl(field: Field): HTMLElement {
48  const control = new CheckboxComponent();
49  control.setAttribute('name', field.name);
50  return control;
51}
52
53private getCardNumberControl(field: Field): HTMLElement {
54  const control = new CardNumberComponent();
55  control.setAttribute('name', field.name);
56  control.setAttribute('icon', 'true');
57  return control;
58}
59
60private getPhoneControl(field: Field): HTMLElement {
61  const control = new PhoneComponent();
62  control.setAttribute('name', field.name);
63  control.setAttribute('showFlags', 'true');
64  return control;
65}
66
67private getTextControl(field: Field): HTMLElement {
68  const control = new TextComponent();
69  control.setAttribute('name', field.name);
70  return control;
71}
72
73private renderForm(controls: Array<HTMLElement | null>): void {
74  const formContainer = document.querySelector('#form-container');
75  formContainer.nativeElement.innerHTML = '';
76
77  controls.forEach((control) => {
78    if (!control) return;
79    formContainer.nativeElement.append(control);
80  });
81}

3-D Secure验证

3-D Secure验证可通过收单方内置机制处理，也可通过外部商户插件(MPI)处理，由其完成持卡人身份认证并将结果转发至收单方。

当验证由收单方内置机制处理时，用户将被重定向至外部URL。此场景下，需配置redirect事件的处理逻辑。

通过MPI进行的验证使用psdk-3ds组件实现，该组件基于WebSocket。需配置3DS事件的处理逻辑，以确保验证流程正常运行，因为此验证流程需要用户执行额外操作以确认交易。

验证类型取决于用户所属银行。

创建支付状态页面，用户在完成3-D Secure验证后将被重定向到该页面。例如：https://example.com/return-page.html。
在支付UI的HTML标记中添加psdk-status组件以显示支付状态。

示例：

Copy

Full screen

Small screen

1@if (showStatus) {
2  <psdk-status></psdk-status>
3}

创建用于显示支付UI的页面。例如：https://example.com/form-page.html。
指定支付方式ID和状态页面URL来初始化支付UI。

示例：

Copy

Full screen

Small screen

1await headlessCheckout.form.init({
2  paymentMethodId: 1380, // Bank card payment ID
3  returnUrl: 'http://example.com/return-page.html',
4});

添加redirect事件处理以将用户重定向到外部页面进行3-D Secure验证。验证成功后，用户将被重定向到支付状态页面(https://example.com/return-page.html)。

示例：

Copy

Full screen

Small screen

 1headlessCheckout.form.onNextAction((nextAction) => {
 2  switch (nextAction.type) {
 3    case 'redirect':
 4      this.handleRedirectAction(nextAction);
 5  }
 6});
 7
 8private handleRedirectAction(redirectAction: RedirectAction): void {
 9  const url = this.buildRedirectUrl(redirectAction);
10  window.location.href = url; // redirect to 3-D Secure page
11}
12
13private buildRedirectUrl(redirectAction: RedirectAction): string {
14  const url = new URL(redirectAction.data.redirect.redirectUrl);
15  const params = Object.entries(redirectAction.data.redirect.data);
16  params.forEach((entry) => {
17    const [key, value] = entry;
18    url.searchParams.append(key, value);
19  });
20  return url.toString();
21}

添加3DS事件处理以进行3-D Secure验证。

只有在启动验证流程时才会触发3DS事件。此验证过程需要用户执行额外操作来确认交易，例如输入通过短信收到的验证码。

示例：

Copy

Full screen

Small screen

1headlessCheckout.form.onNextAction((nextAction) => {
2  switch (nextAction.type) {
3    ...
4    case '3DS': {
5      show3DS = true;
6      challenge = JSON.stringify(nextAction.data.data);
7    }
8  }
9});

在支付UI的HTML标记中添加psdk-3ds组件以处理3-D Secure验证。

示例：

Copy

Full screen

Small screen

1@if (show3DS) {
2  <psdk-3ds [attr.data-challenge]="challenge" text="Continue"></psdk-3ds>
3}

感谢您的反馈！

我们会查看您的留言并运用它改进用户体验。

上次更新时间: 2026年4月30日

发现了错别字或其他内容错误？请选择文本，然后按Ctrl+Enter。

额外用户数据输入
3-D Secure验证