Customize Payment Form

Use SolidGate Payment Form functionality to build custom payment forms on the web. SolidGate Payment Form is our foundational JavaScript library for building payment flows.

With SolidGate Payment Form, you can also tokenize sensitive information and handle 3-D Secure authentication. All sensitive information is handled by SolidGate Payment Form, so it features PCI-DSS compliance.

Setup SolidGate Payment Form

To start with you need to include the SolidGate Payment Form (SolidGate SDK) on your checkout page by adding the script tag at the end of the <body> tag of the page of your HTML file.

Please, do not import it and use the link from SolidGate SDN, the script could be modified.

<script src="https://cdn.solidgate.com/js/solid-form.js"></script>

The next step is to create the object on your page where the payment form should be. Note that the id name can be different if you change it in the script tag.

Please, do not limit the size of the object on your page. SolidGate Payment Form could change dynamically, depending on the BIN country.

The following example specifies a default id of the SolidGate SDK.

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

ID Name Definition Sample
                                    const data = {
  iframeParams: {
    containerId: 'id'
  }
}
                                

Signature Generation

To initialize the SolidGate Payment Form, you need to generate the Signature parameter on your backend.

The signature allows verifying whether the request from the merchant is genuine on the payment gateway server. It's generated not from JSON but the paymentIntent encrypted String.

The process of generating the SolidGate Payment Form initialization signature is presented in the following article.

PaymentIntent parameters

Parameters for the paymentIntent object are described in the following table.

Parameter	Mandatory	Type	Description	Example
order_id	M	string(100)	Order ID specified in merchant system	123443334
amount	M	integer	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents.	1020
currency	M	string(3)	Currency amount. 3 letter currency code under ISO-4217	USD
order_description	M	string(255)	A description of the payment	Premium package
order_date	O	string(50)	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2018-08-07 11:21:30
order_items	O	string(255)	Order items in UTF-8 code	item 1, item 2
order_number	O	integer	Number of payments by user	1
subscription_product_id	O	string(36)	Product ID in SolidGate subscription service	faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
callback_url	O	string(255)	URL of merchant page, where response with payment result will be sent	http://merchant.example/callback
fail_url	O	string(255)	URL of merchant page, which a customer will be redirected in case of unsuccessful payment	http://merchant.example/fail
success_url	O	string(255)	URL of merchant page, which a customer will be redirected in case of successful payment	http://merchant.example/success
settle	M	object
settle: delay_hours	M	integer	Time (in hours) when auto-settle should be done	24
website	O	string(255)	Website from which transaction took place	http://merchant.example
processing_mid	M	string(255)	Use this field to route your payment to specified MID	b0651d75db2
dynamic_descriptor	O	string(50)	The descriptor for the transaction	payhere.com
three_ds	O	object	Information required for 3D Secure payments
three_ds: force	O	boolean	Flag whether to send user for 3DS Flow	FALSE
three_ds: attempt_non_secure	O	boolean	Determines whether to attempt a 3D Secure payment as non-3D Secure should the card issuer not be enrolled	FALSE
customer	M	object	Details of the customer to associate with the source
customer: user_id	M	string(100)	The identifier of an existing customer	cuid_y343t4mf46fdzuxjbcn2giaqnb44
customer: email	M	string(100)	An optional email address to associate with the customer	user@solidgate.us
customer: ip_address	M	string(50)	The IP address used to make the payment. Required for risk checks	8.8.8.8
customer: first_name	O	string(100)	The customer's first name	Chack
customer: last_name	O	string(100)	The customer's last name.	Blank
customer: phone_number	O	string(50)	The payment source owner's phone number	+1415 555 2671
customer: date_of_birth	O	string(50)	Birthdate in YYYY-MM-DD format.	2000-11-21
customer: ip_country	O	string(3)	ISO-code of the country that was sent in the request	USA
customer: delivery_address	O	object	The delivery address
customer: delivery_address: line1	O	string(100)	The delivery address line 1	15 William St
customer: delivery_address: line2	O	string(100)	The delivery address line 2
customer: delivery_address: city	O	string(100)	City of the delivery address	New York
customer: delivery_address: state	O	string(100)	State of the delivery address	WA
customer: delivery_address: zip	O	string(10)	ZIP code of the delivery address	10005
customer: delivery_address: country	O	string(3)	ISO country code of the delivery address	USA
payment_form	O	object
payment_form: language	O	string(2)	Language code of requested Payment form	EN

Form Request

After completing these steps, you need to create a new <script> tag on your page (after Solid.js Script). This script creates a form request object.

Please, add the following objects to your script tag.

Object	Mandatory	Description
merchantData	Yes	The main object required to init the form. Contains all the information for creating payment on the SolidGate side.
formParams	No	An object that allows you to control not mandatory parameters on the form (f.e. - Cardholder Name). In this object, you can also select a SolidGate Payment Form template. The list of templates is here.
styles	No	An object that allows you to manage the styles of your payment form.

The list of parameters that each of the objects can contain is described below.

Merchant Data Object should contain the following parameters:

Parameter	Description	Example
merchant	Unique merchant identification. Shall be shared at the moment of registration.	Test_Merchant
signature	Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.	MjNiYjVj…ZhYmMxMzNiZDY=
paymentIntent	The encrypted aes-cbc-256 string of JSON request data with random IV (16bytes) and private key is first 32bytes of merchant private key.	E5FKjxw5vRjjIZ....vmG2YFjg5xcvuedQ==

Detailed information on optional objects is provided under the <script> example.

Form Request Data Object Sample
                                    const data = {
  merchantData: {
    merchant: 'test_merchant',
    signature: 'MjliMzU4ODE3ZDVlM2E1YWZmYzI1NmU4MzU3YjhlODRkMTJmZTk1NjIxOWNiYzFmNDk0N2NkNjk5YTA5Y2Q4NzIzOWIwMTgxZTQwOGExZjFmYWQ1NzQyYjc3ZGRjMzE0MTczYTQ2OGEyMTlmNGI4YzA5ZmNhMTczZDI0ZDBkZmM=',
    paymentIntent: 'E5FKjxw5vRjjIZBKtH_Q9oN1Wmn5icMn720prO4nPB3cYpzC9wLAHwq9IwstmD-YFLFPsdq2Rk9YzRJhxdPEq2KI19fFt1QotX-smH5_xWxGfYcv9rf2Y4v4KWgbjzJylHTDM6eCXVvbdZyVU54vD3sxntN3gFiyuhEzMn8mKoDV0UdIqLN_VsTAdehBUrqk7aPNzXCfSqpy9pCBlpdFNCfgOyHoDXGGS_Z9fK3gCw7usF2v0IU96mQGzdtyEUs1Z2MJYwle7sjEkWNEb9SkpW1zUXEZCFMF8Cu-dn6fWe4cVE2Ok1MDeTE43dySgw9e8GzMxgPmG2YFjg5xcvuedQ=='
  },
  formParams: {
    submitButtonText: 'Pay',
    isCardHolderVisible: true,
    headerText: 'Enter your debit or credit card details (from merchant)',
    titleText: 'Card info (from merchant)',
    formTypeClass: 'default',
    googleFontLink: '//fonts.googleapis.com/css2?family=DM+Sans:ital@1&display=swap'
  },
  styles: {
    submit_button: {
      'background-color': 'red',
      'font-size': '16px',
      'font-weight': 'bold',
      ':hover': {
        'background-color': 'green'
      },
     form_body: {
       'font-family': 'DM Sans' 
    }
  }
}
                                

The formParams object allows you to select the SolidGate Payment Form template. You can also control the text on the Pay button, control the display of the optional Cardholder Name parameter, etc.

Parameters that you could modify from the formParams object are in the table below.

Parameter	Type	Description	Example
submitButtonText	string	The text on the Submit Button	Pay Now
isCardHolderVisible	boolean	Visibility of the Card Holder field on the form	true
headerText	string	The text on the header of the payment form	Enter your payment data
titleText	string	The text on the title of the payment form	Card info
formTypeClass	string	Template of the SolidGate Payment Form. The list of templates is beloved the table.	default
isSolidGateLogoVisible	boolean	Visibility of the Powered by SolidGate logo. By default is false.	true
cardBrands	array	Array with list of card brands, that could display on the Payment Form.	['verve', 'visa', 'mastercard', 'maestro', 'american-express', 'jcb', 'diners-club', 'discover', 'aura', 'elo', 'hipercard', 'mir'],
secureBrands	array	Array with list of secure brands, that could display on the Payment Form.	['visa-secure', 'mcc-id-check', 'ssl', 'pci-dss', 'norton', 'mc-affee']
font-family	string	Font-family for your payment form. To use it, please add google Font Link on the formParams object.	DM Sans

SolidGate Payment Form template

If you don't want to customize your payment form styles, you could always use the template of the SolidGate Payment Form.

Available templates:

card;
inline;
flat;
dafault.

The appearance of the default template is presented below.

SolidGate Payment Form Styles

You can customize the SolidGate Payment Form to fit perfectly within your checkout page. SolidGate SDK eliminates the need for hosted payment pages and gives you the building blocks to create your checkout form.

SolidGate Payment Form is styled using a styles object consisting of CSS properties nested under objects.

The CSS properties are supported in the following classes:

Allowed Classes	Description
form_body	Parameter responsible for the body of the form
card_number	Card number field parameter
expiry_date	Expiry date field parameter
card_cvv	Card CVV field parameter
card_holder	Cardholder parameter field parameter
card_cpf	CPF field parameter
zip_code	ZIP code field parameter
card_dni	DNI field parameter
card_pin	PIN field parameter
card_curp	CURP field parameter
submit_button	Submit button field parameter
header	The payment form title - header for the payment form
form_title	The payment form subtitle
card_view	Class for editing card template. Sample for changing card color: card_view: { 'background': '#3D4251'}
body_errors	The errors customisation for card and flat template.
card_brands	Class for editing the size and position of card brands.
secure_info	Class for editing the size and position of secure brands.

CSS Sample of Custom Styles
                                    styles: {
  form_body: {
    'font-family': 'Open Sans'
  },
card_brands: {
    ...
  },
  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',
      },
    },
    '.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 4 states:

not-empty
error
valid
default - without specifying the state

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

The following pseudo-classes and pseudo-elements can also be styled using a nested object inside of a variant:

:hover
:focus
:placeholder

The following CSS properties are supported:

Object Properties	Description
background-color	The background-color CSS property sets the background color of an element.
padding	The padding CSS shorthand property sets the padding area on all four sides of an element
display	The display CSS property sets whether an element is treated as a block or inline element and the layout used for its children, such as flow layout, grid or flex.
font-size	The font-size CSS property sets the size of the font. Changing the font size also updates the sizes of the font size-relative <length> units, such as em, ex, and so forth.
font-weight	The font-weight CSS property sets the weight (or boldness) of the font. The weights available depend on the font-family that is currently set.
margin-bottom	The margin-bottom CSS property sets the margin area on the bottom of an element. A positive value places it farther from its neighbors, while a negative value places it closer.
color	The color CSS property sets the foreground color value of an element's text and text decorations.
border-color	The border-color shorthand CSS property sets the color of an element's border.

Update Payment Intent

If you use several tariffs for payment, you do not need to call the payment form for each price. Instead, you can request the form once and change the amount, currency and product ID using the update method.

Execution of the update method is available after you have received the mounted event for the form entity.

To update the amount, currency or product id on the SolidGate Payment Form, you need to generate the Signature parameter on your backend. The signature allows verifying whether the request from the merchant is valid on the payment gateway server. It's generated from the partialIntent encrypted String.

Partial Intent Parameters

Parameter	Type	Mandatory	Description	Example
amount	integer	Yes, for the non-subscription workflow	Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents	1020
currency	string	Yes, for the non-subscription workflow	Currency amount. 3 letter currency code under ISO-4217. Indicate the parameter together with the product ID if you need to select a tariff for a specific currency.	EUR
product_id	string	Yes, for the subscription workflow	ID of the predefined product.	faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

Please note!
If on the initial call of the SolidGate Payment Form you picked up the non-subscription flow, you can only specify the amount and currency using the refresh method.

After the signature creation, you need to execute the update method in the SolidGate SDK by passing two parameters: partialIntent and signature.

Update Method Parameters

Parameter	Type	Description	Example
partialIntent	string	The encrypted aes-cbc-256 string of JSON request data with random IV (16bytes) and private key is first 32bytes of merchant private key.	E5FKjxw5vRjjIZ....vmG2YFjg5xcvuedQ==
signature	string	Signature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.	MjNiYjVj…ZhYmMxMzNiZDY=

Update Method Execution Sample
                                    form.update (
	{
	  partialIntent, signature
	}
);
                                

Additional Fields on SolidGate Payment Form

Additional Fields is not required fields that could be required to process the payment in some countries.

List of additional fields

ZIP Code. A credit card postal code is an additional form of security used to verify it is being used by the owner of the card or an authorized user. Field used to verify the owner of the card in the USA banks.

CPF. The CPF number is an identification number in the Brazilian register of individual taxpayers. Field used to verify the payer data in the BRA banks.

DNI. DNI is a unique identity document that Argentines have. DNI field could be required to process payments via ARG banks.

PIN. The PIN Code is only required for some NGA banks.

CURP. CURP is the tax registration number of a resident of Mexico. In accordance with Mexican legislation, the field could be required to process payments via MEX banks.

Controlling the display of Additional Fields on the SolidGate Payment Form.

To give SolidGate Payment Form access to display additional fields on the payment form you need to pass an allowedAdditionalFields parameter on the formParams object.

Additional Fields Controlling Sample
                                    formParams: {
  allowedAdditionalFields: ['ZIP', 'CURP']
}
                                

SolidGate Payment Form will check the Card BIN and receive a solution to display Additional Fields according to information about BIN country. SolidGate Payment Form will display only fields, that you provide on the allowedAdditionalFields parameter. For example, if your object doesn’t contain the PIN field, the SolidGate Payment Form will not display the PIN field on the payment form for the users with NGA cards.

In case you do not pass an allowedAdditionalFields parameter the solution to display an additional field on the payment form is absolutely on the SolidGate side.

SolidGate Payment Form Initialization

After completing all the steps described above and modifying all required parameters, you need to add the variable on your page in order to initiate SolidGate SDK and render the payment form.

This variable should contain the data from the Form Request Data Object.

Variable Initialization Sample
                                    const form = PaymentFormSdk.init(data);

SolidGate Payment Form Events

You could communicate with your SolidGate Payment Form by listening to an event.

SolidGate SDK Event Listener Sample
                                    const form = PaymentFormSdk.init(data)

form.on('event_name', (e) => {
  //Merchant's code
})
                                

SolidGate SDK might emit any of the events below. The description of the events is described below.

Event	Body	Description
mounted	{ type: "mounted", entity: "form" }	The event indicates that the payment form was displayed.
error	{type: “error”, message: {msg}}	Event of any form error after a click on submit button (validation error). Contains an object with a message.
fail	{type: “fail”, code: “0.01”, message: “General Decline”}	The event informs that the payment has been declined. Contains an object with an error code and error message. Please, note, this event initiates only when using the SolidGate status page.
submit		The event informs that the user submitted the form, "pay" button pressed.
success		Event of the success payment processing. Please, note, this event initiates only when using the SolidGate status page.
verify		The event informs that the payment starts processing through 3D flow.
sessionExpired		The session for submitting the Payment Form has expired. The session duration is 24 hours.