Bank cards

To set up payments using bank cards, you can follow the basic setup instructions. If the user needs to enter additional data to complete payment, e.g., when paying with Brazilian cards, or pass the 3-D Secure verification, use the instructions provided below.

Additional user data entry

Add a container for the payment UI form.

Example:

Copy

Full screen

Small screen

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

Add the handling of the show_fields event for the new fields display.

Example:

Copy

Full screen

Small screen

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

Create the payment UI fields for entering additional data, e.g., a cardholder name or billing address.

Example:

Copy

Full screen

Small screen

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

3-D Secure verification

Create a payment status page where the user will be redirected after passing the 3-D Secure verification. For example, https://example.com/return-page.html.
Add the psdk-status component to the HTML markup of the payment UI to display a payment status.

Example:

Copy

Full screen

Small screen

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

Create a page to display the payment UI. For example, https://example.com/form-page.html.
Initialize the payment UI specifying the payment method ID and status page URL.

Example:

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

Add the handling of the redirect event to redirect the user to an external page for 3-D Secure verification. After successful verification, the user is redirected to the payment status page (https://example.com/return-page.html).

Example:

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}

Add the handling of the 3DS event for the 3-D Secure verification.

The 3DS event is triggered only when the challenge flow is initiated. This verification process requires an additional user action to confirm the transaction, such as completing two-factor authentication.

Example:

Copy

Full screen

Small screen

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

Add the psdk-3ds component to the HTML markup of the payment UI to process the 3-D Secure verification.

Example:

Copy

Full screen

Small screen

1@if (show3DS) {
2  <psdk-3ds></psdk-3ds>
3}

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: September 23, 2025

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

Additional user data entry
3-D Secure verification

Your browser is not supported. Please try a different browser

Bank cards

Additional user data entry

3-D Secure verification