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

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

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

Example:

Copy

Full screen

Small screen

headlessCheckout.form.onNextAction((nextAction) => {
  switch (nextAction.type) {
    case 'show_fields':
      this.handleShowFieldsAction(nextAction);
  }
});

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

Example:

Copy

Full screen

Small screen

private handleShowFieldsAction(nextAction: ShowFieldsAction): void {
  this.form.fields = nextAction.data.fields;
  this.updateForm(this.form);
}

private updateForm(form: Form): void {
  const visibleFields = form.fields.filter((field) => {
    return field.isVisible === '1';
  });

  const controls = visibleFields.map((field) => {
    if (field.type === 'select') {
      return this.getSelectControl(field);
    }

    if (field.type === 'check') {
      return this.getCheckboxControl(field);
    }

    if (field.type === 'text') {
      if (field.name === 'card_number') {
        return this.getCardNumberControl(field);
      }

      if (field.name === 'phone') {
        return this.getPhoneControl(field);
      }

      return this.getTextControl(field);
    }

    return null;
  });

  this.renderForm(controls);
}

private getSelectControl(field: Field): HTMLElement {
  const control = new SelectComponent();
  control.setAttribute('name', field.name);
  return control;
}

private getCheckboxControl(field: Field): HTMLElement {
  const control = new CheckboxComponent();
  control.setAttribute('name', field.name);
  return control;
}

private getCardNumberControl(field: Field): HTMLElement {
  const control = new CardNumberComponent();
  control.setAttribute('name', field.name);
  control.setAttribute('icon', 'true');
  return control;
}

private getPhoneControl(field: Field): HTMLElement {
  const control = new PhoneComponent();
  control.setAttribute('name', field.name);
  control.setAttribute('showFlags', 'true');
  return control;
}

private getTextControl(field: Field): HTMLElement {
  const control = new TextComponent();
  control.setAttribute('name', field.name);
  return control;
}

private renderForm(controls: Array<HTMLElement | null>): void {
  const formContainer = document.querySelector('#form-container');
  formContainer.nativeElement.innerHTML = '';

  controls.forEach((control) => {
    if (!control) return;
    formContainer.nativeElement.append(control);
  });
}

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

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

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

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

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

headlessCheckout.form.onNextAction((nextAction) => {
  switch (nextAction.type) {
    case 'redirect':
      this.handleRedirectAction(nextAction);
  }
});

private handleRedirectAction(redirectAction: RedirectAction): void {
  const url = this.buildRedirectUrl(redirectAction);
  window.location.href = url; // redirect to 3-D Secure page
}

private buildRedirectUrl(redirectAction: RedirectAction): string {
  const url = new URL(redirectAction.data.redirect.redirectUrl);
  const params = Object.entries(redirectAction.data.redirect.data);
  params.forEach((entry) => {
    const [key, value] = entry;
    url.searchParams.append(key, value);
  });
  return url.toString();
}

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

Example:

Copy

Full screen

Small screen

headlessCheckout.form.onNextAction((nextAction) => {
  switch (nextAction.type) {
    ...
    case '3DS': {
      show3DS = true;
    }
  }
});

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

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

Thank you for your feedback!

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

Last updated: March 3, 2025

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

Your browser is not supported. Please try a different browser

Headless checkout

Bank cards

Additional user data entry

3-D Secure verification