Solidgate • Customize payment form

Customize payment form

Customize payment form appearance with CSS overrides, theme configuration, font selection, and layout adjustments to match your brand

The Solidgate Payment Form offers exceptional adaptability and comprehensive customization options to meet diverse payment processing needs across regions. With its capability to integrate additional transaction-specific fields and control field visibility, it ensures a personalized customer experience.

Apply these options after you Guide
Set up the Solidgate payment form with step-by-step instructions for script loading, container mounting, and payment request configuration. initialize the form. To change transaction parameters such as amount, product, or checkout line items on an initialized form, use Guide
Update an initialized payment form's amount, currency, or product, or change checkout line items, discounts, and trial terms for subscriptions. update payment form.

Through the form, take the opportunity to:

choose one of the four ready-made templates default, flat, card or inline
fine-tune every element via the styles object to match your brand
hide or show any optional field to streamline the checkout flow
rename field labels and placeholders in a single place with formParams
replace the built-in submit button and trigger payments programmatically with form.submit()

Template

Solidgate offers several default form templates with pre-configured styles. Using a template for a payment form from Solidgate simplifies the payment acceptance process on your website.

Templates offer a pre-designed and functional form, eliminating the need for customization. This ensures compliance with industry standards for both security and customer experience.

default

This traditional design with clearly defined input fields provides a simple, straightforward customer experience. It is ideal for businesses seeking a familiar, accessible interface without unnecessary features.

This template can easily adjust to different screen sizes, making it suitable for various devices.

flat

With a clean, modern aesthetic, the flat template removes shadows and textures to emphasize simplicity and minimalism.

It is ideal for businesses looking for a contemporary look that aligns with a flat design digital branding strategy.

card

This template offers a bold, eye-catching design with depth and contrast, using shadows and highlights to create a sense of layering.

It is perfect for businesses that want to provide a dynamic and immersive customer experience, possibly for younger or tech-savvy demographics.

inline

The inline template provides a condensed, efficient layout, ideal for quick interactions and minimal scrolling.

This is ideal for businesses wanting to simplify payment processing or embed a compact payment form within a webpage section.

Styles

Payment Form offers a styles object with nested CSS properties. This approach allows flexible styling of your website without changing HTML or JavaScript.

CSS custom styles

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

styles: {
  form_body: {
    'font-family': 'Open Sans'
  },
  card_brands: {
    transform: 'scale(1.2)',
    display: 'flex',
    'justify-content': 'space-evenly',
    i: {
      'border-radius': '2px'
    }
  },
  secure_info: {
  ...
  },
  form_title: {
    display: 'flex',
      width: '100%',
      'justify-content': 'center',
      'font-weight': '500',
      'font-size': '28px',
      color: '#3D4251'
  },
  submit_button: {
    'display': 'none',
      'background-color': '#46D47F',
      height: '50px',
      ':disabled': {
      'background-color': '#576574'
    },
    '.title': {
      '::before': {
        'object-fit': 'contain',
      }
    }
  },
  card_number: {
    '.error input': {
      'border-color': '#FC9494',
        color: '#FC9494'
    },
    '.error .label': {
      color: '#FC9494',
    },
    '.error-text': {
      color: '#FC9494',
        '.triangle': {
        'border-color': 'transparent transparent #ff6b6b'
      }
    },
    input: {
      'border-color': '#c8d6e5',
        'color': '#222f3e',
        ':focus': {
        'border-color': '#8395a7',
      },
        '::placeholder': {
        color: '#8395a7',
          'font-style': 'italic'
      }
    },
    '.label': {
      color: '#222f3e'
    },
    i: {
      display: 'none !important',
    }
  },
  card_cvv: {
    '.error input': {
      'border-color': '#FC9494'
    },
    '.error .label': {
      color: '#FC9494'
    },
    '.error-text': {
      color: '#FC9494',
        '.triangle': {
        'border-color': 'transparent transparent #3498db'
      }
    },
    input: {
      'border-color': '#c8d6e5',
        'color': '#222f3e',
        ':focus': {
        'border-color': '#8395a7',
      }
    },
    '.label': {
      color: '#3D4251'
    }
  },
  expiry_date: {
    '.error input': {
      'border-color': '#FC9494'
    },
    '.error .label': {
      color: '#FC9494'
    },
    '.error-text': {
      color: '#FC9494',
        '.triangle': {
        'border-color': 'transparent transparent #3498db'
      }
    },
    input: {
      'border-color': '#c8d6e5',
        'color': '#222f3e',
        ':focus': {
        'border-color': '#8395a7',
      }
    },
    '.label': {
      color: '#3D4251'
    }
  },
  zip_code: {
    '.error input': {
      'border-color': '#FC9494'
    },
    '.error .label': {
      color: '#FC9494'
    },
    '.error-text': {
      color: '#FC9494',
        '.triangle': {
        'border-color': 'transparent transparent #3498db'
      }
    },
    input: {
      'border-color': '#c8d6e5',
        'color': '#222f3e',
        ':focus': {
        'border-color': '#8395a7',
      }
    },
    '.label': {
      color: '#3D4251'
    }
  },
}

The properties for input fields on the Payment Form could be applied for the following states. Each state is a classname, so write it with a leading dot as the key of a nested object, for example

.error input :

.not-empty - indicates a state where the input or field is populated with a value.
.error - represents a state where an error or validation issue has occurred.
.valid - signifies a state where the input or field has passed validation.
default - the initial state, which carries no state classname.

In case the state is not specified, properties are applied for all states.

Any standard CSS pseudo-class or pseudo-element can also be styled using a nested object inside a variant. Keep the CSS spelling exactly: a single colon for pseudo-classes, a double colon for pseudo-elements. Commonly used ones:

:hover - applies when the customer hovers over an element with the mouse.
:focus - applies when an element gains focus, such as when a customer clicks into a text input.
:disabled - applies when an element is disabled, such as the submit button before the form is valid.
::placeholder - applies styles to the placeholder text within an input field.
::before and ::after - apply styles to the generated content of an element.

There is no support for transferring images - neither via link nor via data-uri.

For the Payment Form, applying CSS styles allows control over the visibility of form elements, providing control over the display of specific properties within the form.

Please note that hiding price-related fields on the payment form might impact the form functioning. Thorough testing is recommended to ensure the form still functions correctly.

CSS for hiding elements

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

styles: {
  card_number: {
    display: 'none'
  },
  expiry_date: {
    display: 'none'
  },
  card_cvv: {
    display: 'none'
  },
  // other fields you want to hide
}

Label and placeholder customization

To customize all labels on the payment form, add the parameter fieldNameLabel with the new label name in the formParams object for each desired field.

To customize all placeholders on the payment form, add the parameter fieldNamePlaceholder with the new label name in the formParams object for each desired field.

Card data fields parameters

1
2
3
4
5
6
7
8

cardExpiryDateLabel
cardCvvLabel
cardNumberLabel
cardHolderLabel
cardExpiryDatePlaceholder
cardCvvPlaceholder
cardNumberPlaceholder
cardHolderPlaceholder

To get the value of fieldNameLabel or fieldNamePlaceholder for additional fields, you need to take the Field Class name on the table. Change it into camelcase, and add a Label or Placeholder at the end.

For example, bolivia_ci becomes boliviaCiLabel, and argentina_dni becomes argentinaDniLabel

Label customisation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

PaymentFormSdk.init({
  ...restData,
  formParams: {
    ...restFormParamsIfPresent,
    cardExpiryDateLabel: 'Expiration Date',
    cardExpiryDatePlaceholder: 'MM/YY',
    argentinaDniLabel: 'DNI',
    boliviaCiLabel: 'CI'
  }
})

Custom submission

Payment Form provides two options for payment submission:

click on the payment button
use the form.submit method

The option to display a custom payment button below the form is available, allowing for the collection of additional customer data.

To hide the payment form submit button, set the allowSubmit display property in formParams to false during initialization. This action not only hides the button but also blocks form submission via the enter key.

React

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import React, { FC } from 'react'
import ReactDOM from 'react-dom';
import Payment, { InitConfig, ClientSdkInstance } from "@solidgate/react-sdk"

const formParams = {
  allowSubmit: false
}

export const MyPayment: FC<{
  merchantData: InitConfig['merchantData']
}> = (props) => {
  return (
    <Payment
      merchantData={props.merchantData}
      formParams={formParams}
    />)
}

JavaScript

1
2
3
4
5
6
7

const form = PaymentFormSdk.init({
  ...restData,
  formParams: {
    ...restFormParamsIfPresent,
    allowSubmit: false
  }
})

Vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<template>
  <Payment
      :merchant-data="merchantData"
      :form-params="formParams"
      width="100%"
  />
</template>

<script lang="ts" setup>
import { defineAsyncComponent } from 'vue'
import { InitConfig } from '@solidgate/vue-sdk'
const Payment = defineAsyncComponent(() => import('@solidgate/vue-sdk'))

const merchantData: InitConfig['merchantData'] = {
  merchant: '<<--YOUR MERCHANT ID-->>',
  signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
  paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
}

const formParams: InitConfig['formParams'] = {
  allowSubmit: false
}
</script>

Angular

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import {Component} from '@angular/core';

import {InitConfig} from "@solidgate/angular-sdk";

@Component({
  selector: 'app-root',
  template: `
    <ngx-solid-payment
      [formParams]="formParams"
      [merchantData]="merchantData"
      width="100%"
    ></ngx-solid-payment>
  `
})
export class AppComponent {
  merchantData: InitConfig['merchantData'] = {
    merchant: '<<--YOUR MERCHANT ID-->>',
    signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
    paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
  }

  formParams: InitConfig['formParams'] = {
    allowSubmit: false
  }
}

Svelte

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

<!-- MyPayment.svelte -->
<script lang="ts">
  import type { Action } from 'svelte/action'
  import { SdkLoader, type ClientSdk, type InitConfig } from '@solidgate/client-sdk-loader'

  let { merchantData }: { merchantData: InitConfig['merchantData'] } = $props()

  const containerId = $props.id()
  const formParams: InitConfig['formParams'] = { allowSubmit: false }

  const payment: Action = (node) => {
    node.id = containerId

    let sdk: ClientSdk | null = null
    let cancelled = false

    void (async () => {
      sdk = await SdkLoader.load()
      if (!sdk || cancelled) return

      sdk.init({ merchantData, formParams, iframeParams: { containerId, width: '100%' } })
    })()

    return {
      destroy () {
        cancelled = true
        sdk?.destroy()
      }
    }
  }
</script>

<div use:payment></div>

To submit the payment form without a Solidgate button, call the form submit method.

React

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

import React, { FC, useRef, useCallback } from 'react'
import ReactDOM from 'react-dom';
import Payment, { InitConfig, ClientSdkInstance } from "@solidgate/react-sdk"

const formParams = {
  allowSubmit: false
}

export const MyPayment: FC<{
  merchantData: InitConfig['merchantData']
}> = (props) => {
  const [isMounted, setIsMounted] = useState(false);
  const [form, setForm] = useState<ClientSdkInstance | null>(null);

  const handleOnReadyPaymentInstance = useCallback((form: ClientSdkInstance) => {
    setForm(form)
  }, [])

  const handleMounted = useCallback(() => {
    setIsMounted(true)
  }, [])

  return (
    <div>
        <Payment
          merchantData={props.merchantData}
          formParams={formParams}
          onReadyPaymentInstance={handleOnReadyPaymentInstance}
          onMounted={handleMounted}
        />
      {mounted && (
        <button type="button" onClick={() => {
          form?.submit()
        }}>
          {"Submit"}
        </button>
      )}
    </div>
  )
}

JavaScript

1

document.getElementById('yourCustomSubmitButtonId').addEventListener('click', () => form.submit())

Vue

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

<template>
  <Payment
      :merchant-data="merchantData"
      @mounted="onMounted"
      @ready-payment-instance="onReadyPaymentInstance"
  />
  <button
      v-if="mounted"
      @click="submit">
    Submit
  </button>
</template>

<script lang="ts" setup>
import { defineAsyncComponent, ref } from 'vue'
import { InitConfig, ClientSdkInstance } from '@solidgate/vue-sdk'
const Payment = defineAsyncComponent(() => import('@solidgate/vue-sdk'))

const merchantData: InitConfig['merchantData'] = {
  merchant: '<<--YOUR MERCHANT ID-->>',
  signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
  paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
}

let mounted = ref(false)

let formResolve: (form: ClientSdkInstance) => void = () => {}
const formPromise = new Promise<ClientSdkInstance>(resolve => {
  formResolve = resolve
})

function onReadyPaymentInstance(form: ClientSdkInstance): void {
  formResolve(form)
}

function onMounted(): void {
  mounted.value = true
}

function submit(): void {
  formPromise.then(form => form.submit())
}
</script>

Angular

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import {Component} from '@angular/core';
import {BehaviorSubject, filter} from 'rxjs'
import {InitConfig, SdkMessage, MessageType} from '@solidgate/angular-sdk';

@Component({
  selector: 'app-root',
  template: `
    <ngx-solid-payment
      [merchantData]="merchantData"
      (mounted)="mounted = true"
      (readyPaymentInstance)="formSubject$.next($event)"
    ></ngx-solid-payment>
    <button *ngIf="mounted" type="button" (click)="submit()"></button>
  `
})
export class AppComponent {
  isMounted = false;

  formSubject$ = new BehaviorSubject<ClientSdkInstance | null>(null)

  merchantData: InitConfig['merchantData'] = {
    merchant: '<<--YOUR MERCHANT ID-->>',
    signature: '<<--YOUR SIGNATURE OF THE REQUEST-->>',
    paymentIntent: '<<--YOUR PAYMENT INTENT-->>'
  }

  private form$ = this.formSubject$.pipe(filter(Boolean))

  submit(): void {
    this.form$.subscribe(form => form.submit())
  }
}

Svelte

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

<!-- MyPayment.svelte -->
<script lang="ts">
  import type { Action } from 'svelte/action'
  import { SdkLoader, MessageType, type ClientSdk, type ClientSdkInstance, type InitConfig } from '@solidgate/client-sdk-loader'

  let { merchantData }: { merchantData: InitConfig['merchantData'] } = $props()

  const containerId = $props.id()
  const formParams: InitConfig['formParams'] = { allowSubmit: false }

  let form = $state.raw<ClientSdkInstance | null>(null)
  let mounted = $state(false)

  const payment: Action = (node) => {
    node.id = containerId

    let sdk: ClientSdk | null = null
    let cancelled = false

    void (async () => {
      sdk = await SdkLoader.load()
      if (!sdk || cancelled) return

      form = sdk.init({ merchantData, formParams, iframeParams: { containerId, width: '100%' } })
      form.on(MessageType.Mounted, () => (mounted = true))
    })()

    return {
      destroy () {
        cancelled = true
        sdk?.destroy()
      }
    }
  }
</script>

<div use:payment></div>

{#if mounted}
  <button type="button" onclick={() => form?.submit()}>Submit</button>
{/if}

Actual submission does not occur if:

additional fields require display due to a validation error for the new field
some fields are awaiting validation because there are validation errors on the form
validation errors exist in form fields, which must be resolved before the form can be submitted

Otherwise, the form is submitted.

Looking for help? Contact us

Stay informed with Changelog