Payment Form

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

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

Setup Solid Payment Form

To start with the Solid Payment Form, you can use our official payment form SDK for different JS frameworks and libraries. Frameworks usage:

These integrations automatically load solid-form.js and provide a convenient interface for working with the form. Also, you can use manual installation. To start with, you need to include the Solid Payment Form (Solid 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 Solid CDN, the script could be modified.

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

Check the console for a warning that Solid PaymentFormSdk is already connected. If this warning appears, solid-form.js has most likely been connected twice. Remove the unnecessary connection.

The next step is to create the container on your page where the payment form should be. Note that you could pick up your id for the container, as is shown below.

Please, do not set the height of the dimensions (height, width, max-width, max-height) and display (block, inline-block, etc.) any elements inside the container. It may lead to various bugs in form appearance.

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

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

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

Signature Generation

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

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

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

PaymentIntent parameters

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

Parameter	Type	Mandatory	Description	Example
ip_address	string	Yes	Customer IP (only public ones)	8.8.8.8
currency	string	Yes, for the non-subscription flow	Currency amount. 3 letter currency code under ISO-4217	USD
amount	integer (64)	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
product_id	string	Yes, for the subscription workflow	ID of the predefined product	faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
order_id	string	Yes	Order ID specified in the merchant system	123456
order_description	string	Yes	Order description in UTF-8 code	Premium package
platform	string	Yes	Customer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application	WEB
customer_email	string	No	Customer email. If no parameter is received, it will be collected automatically on payment form	test@solidgate.com
customer_account_id	string	Yes, for the subscription workflow	Customer ID in the merchant's system.	4dad42f808
geo_country	string	Yes, for Apple- , Google Pay	Customer country subject to ISO 3166-1 alpha-3	GBR
language	string	No	Customer language settings for the Solid Payment Form field translation. Available values: uk - Ukrainian, ru - Russian, en - English, fr - French, es - Spanish, pt - Portuguese, ja - Japanese, ar - Arabic, it - Italian, tr - Turkish, pl - Polish, etc.	en
force3ds	boolean	No	Routing payments flag for 3DS flow (enabled by Solid account manager)	true
settle_interval	integer	No	Time (in hours) when auto-settle should be done. Maximum value is 168 hours.	48
type	string	No	Parameter for transaction authorization through a payment form	auth
order_number	integer	No	Number of payments by user	1
device	string	No	Device of customer	iPhone 8 iOS 12.0
user_agent	string	No	User-agent of the customer	Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36
transaction_source	string	No	Source of transactions on site.	main_menu
verified	boolean	No	The user was verified on the shop side	true
retry_attempt	integer	No	Number of retry payment	1
geo_city	string	No	Customer City	New Castle
website	string	No	The website from which transaction took place.	google.com
customer_phone	string	No	Customer telephone	380111111111
customer_first_name	string	No	Customer first name	John
customer_last_name	string	No	Customer last name	Snow
customer_date_of_birth	string	No	Customer birth date in format YYYY-MM-DD	2000-11-21
fraudulent	boolean	No	A customer was detected on the merchant end to be a suspicious one	true
order_date	string	No	Date of order creation in format YYYY-MM-DD-HH-MM-SS	2020-12-21 11:21:30
order_metadata	object	No	Metadata is useful for storing additional, structured information about an object. The object consists of a set of key-value pairs (e.g. “coupon_code”: “NY2018", “partner_id”: “123989"). The callback notification returns an order_metadata from the order in each state. The validation of up to 10 fields with an upper limit of 255 characters.
order_items	string	No	Order items in UTF-8 code	item1, inetm2
success_url	string	No	URL of merchant page, which a customer will be redirected in case of successful payment	http://merchant.example/success
fail_url	string	No	URL of merchant page, which a customer will be redirected in case of unsuccessful payment	http://merchant.example/fail
traffic_source	string	No	Source of traffic	facebook
apple_pay_merchant_name	string	No	The merchant name, which can be displayed to the customers when paying via Apple.	Test

Form Request

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

This object should contain the following properties:

Property	Mandatory	Description
merchantData	Yes	The main object required to init the form. Contains all the information for creating payment on the Solid side.
formParams	No	An object that allows you to control non-mandatory parameters of the form (f.e. - Cardholder Name, templates). The list of templates is here.
styles	No	An object that allows you to manage the styles of your payment form.
googlePayButtonParams	No	An object that allows you to customize the Google Pay button. Learn more.
applePayButtonParams	No	An object that allows you to customize the Apple Pay button. Learn more.
iframeParams	No	An object that allows you to customize form container placement and sizes. Learn more.

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: {
    buttonType: 'default' | 'continue', 
    submitButtonText: 'Pay',
    isCardHolderVisible: true,
    hideCvvNumbers: 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',
    autoFocus: false 'true by default'
  },
  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 Solid Payment Form template. You can also control the text on the Pay button, hold the display of the optional Cardholder Name field, etc.

Parameters that you could modify from the formParams object are below. All of them are optional.

Parameter	Type	Description	Example
buttonType	string	The parameter allows you to select the type of Payment Button: with 'continue' text or default one with 'pay' text.	continue
submitButtonText	string	The text on the Submit Button	Pay Now
isCardHolderVisible	boolean	Visibility of the Card Holder field on the form	true
hideCvvNumbers	boolean	Parameter for hiding the CVV digits. By default - false (numbers are visible).	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 Solid Payment Form. The list of templates is below the table.	default
isSolidLogoVisible	boolean	Visibility of the Powered by Solid 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''],
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
enabled	boolean	Card form visibility. Set to false to show only Google- Apple-Pay buttons and status page.	true
allowSubmit	boolean	Determines, if it’s possible to submit card form using enter keypress on submit button click.	true
autoFocus	boolean	Setting to disable autofocus, as the payment form will scroll the page to the container when it initializes.	true

The iframeParams object allows you to set form width and container id. Parameters are optional.

Parameter	Type	Description	Example
width	string	Override width of the form	100%
containerId	string	Custom containerId to place form	your-custom-container-id

Solid Payment Form Template

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

Available templates:

card;
inline;
flat;
default.

The appearance of the default template is presented below.

/media/39/download/Screenshot%202021-03-18%20at%2017.24.18.png?v=2&inline=0

Solid Payment Form Styles

Solid Payment Form can be customized to fit perfectly within your checkout page. Solid SDK eliminates the need for hosted payment pages and instead gives you the building blocks to create your own checkout form.

Solid Payment Form is styled using a styles object, which consists of CSS properties nested under objects.

The CSS properties are supported in the following classes:

Allowed Classes	Description
input_group	Class for editing styles of all input fields on the form
additional_field	Class for editing styles of all additional fields on the form
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
zip_code	ZIP code 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.
two-columns	Wrapper for CVV and Expiry Date fields in default form template.

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.

Solid 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 Solid SDK and render the payment form.

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

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

Solid Payment Form Events

Using the Solid Payment Form, you could build your user actions tracking by the events that the Solid Payment Form returns.

You could communicate with the Solid Payment Form by listening to an event.

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

form.on('event_name', (e) => {
  const body = e.data // The body of any available event as it described below.
  // The code will be executed when the event is received.
})
                                

The structure and detailed description of each event is presented below.

Mounted event

The event indicates that Solid SDK displayed the Solid Payment Form, Google-Pay or an Apple-Pay Button inside the iFrame.

Mounted Event Sample
                                    {
	type: 'mounted'
	entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values
}
                                

Submit event

The event indicates that the user submitted the payment. The event could be triggered for one of the variations: Solid Payment Form, Google-Pay or an Apple-Pay.

Submit Event Sample
                                    form.on('submit', e => {
   const data = e.data // SubmitMessage
})

interface SuccessMessage {
   type: 'submit',
   entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values
}
                                

Success event

The event indicates that the payment was successfully processed.

Success Event Sample
                                    {
	type: 'success'
	entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values
	order: { // an optional order object
		status: string // an optional order status field
		currency: string  // an optional order currency field
		amount: number  // an optional order amount field
		subscription_id: string  // an optional subscription id field
		order_id: string  // an optional order id field
	}
}
                                

Fail event

The event indicates that the payment had been declined.

Fail Event Sample
                                    {
	type: 'fail'
	entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values
	code: string // an optional error code field
	message: string // an optional error message field
	order: { // an optional order object
		status: string // an optional order status field
		currency: string  // an optional order currency field
		amount: number  // an optional order amount field
		subscription_id: string  // an optional subscription id field
		order_id: string  // an optional order id field
	}
}
                                

Verify event

The event informs that the payment starts processing through the 3D flow.

Verify Event Sample
                                    {
	type: 'verify'
}
                                

Form Redirect Event

The event informs that the iFrame performs a redirect (to your or Solid status page).

Redirect Event Sample
                                    {
	type: 'formRedirect'
}
                                

Interaction event

The event informs about the current state of the Solid Payment Form and the user's interaction with the controls:

istouched - external interaction with the field
isvalid - validity check

Interaction Event Sample 
                                    {
	type: 'interaction'
	target: {
  	type: 'button' | 'input' // one of the listed
  	name: 'submit' | 'googlePay' | 'applePay' | 'cardNumber' | 'cardCvv' | 'cardExpiry' | 'cardHolder' // It could be one of the listed; furthermore, Solid might extend the list.
   	interaction: 'click' | 'change' | 'focus' | 'blur // one of the lister'
	}
	cardForm: {
  	fields:  {
		cardNumber: {
			isValid: boolean
			isTouched: boolean
		}
		cardCvv: {
			isValid: boolean
			isTouched: boolean
		}
		cardExpiry: {
			isValid: boolean
			isTouched: boolean
		}
// The rest of the fields are optional, including, but not limited to: the `cardHolder` field
	}
	isValid: boolean
   	isTouched: boolean
   }
}
                                

Resize event

The event indicates that the Solid Payment Form was resized. For example, the Solid Payment Form could resize after a validation message appeared.

Resize Event Sample
                                    {
	type: 'resize'
	width: number 
	height: number 
}
                                

Custom Styles Appended event

The event indicates that your styles had applied to the Solid Payment Form. The event is helpful for cases when you want to draw your preloader over the Solid Payment Form (at this point, you may remove it).

Custom Styles Appended Event Sample
                                    {
	type: 'customStylesAppended'
}
                                

Error event

The event indicates any Solid Payment Form error, including javascript execution errors.

Error Event Sample
                                    {
   type: 'error'
   value: {
      code: string // optional 
      message: string | string[] // optional string or array of strings
   }
}
                                

Card event

The event indicates that the customer has entered a card number and informs about the card brand and BIN with the first 6 digits when the card number is validated.

This information can be used to block the user's ability to pay before submitting the order.

Card Event Sample
                                    {
   type: 'card'
   card: {
      brand: ‘visa' | 'unknown’, bin: '111222’ // string with the card brand name and bin with the first 6 digits
  }
}
                                

Order status event

The event indicates that the order status was changed during the processing. However, the event may not show all changes before the final order status: approval or decline. All order statuses, transaction statuses and error codes are described here.

Order Status Event Sample
                                    {
	type: 'orderStatus’'
	response: {
		order: { //optional
			amount: number  //optional
			currency: string //optional
			order_id: string //optional
			descriptor: string //optional
			processing_amount: number //optional
			processing_currency: string //optional
			refunded_amount: number //optional
			status: string // Order status 
			subscription_id: string //optional
			marketing_amount: number //optional
			marketing_currency: string //optional
	}
  	transactions:{ [key: string] }: Transaction } // Object containing transactions by key (transaction described below)
	  	transaction:  {
			  descriptor: string // string
			  amount: number
			  card_token: { // string
				   token: string
				 }
				 card: {
    bank: string //optional
    bin: number
    brand: string //optional
    card_exp_month: string
    card_exp_year: number
    card_holder: string //optional
    card_type: string //optional
    country: string //optional
    number: string //optional
    card_token: { //optional
      token: string
    }
  }
  created_at: string
  currency: string
  id: string
  operation: string
  status: string
  updated_at: string
  refund_reason: string //optional
  refund_reason_code: string //optional
  marketing_amount: number //optional
  marketing_currency: string //optional
  finance_fee_amount: string | number //optional
  finance_fee_currency: string | number //optional
  billing_details: { //optional
    address: string //optional
    city: string //optional
    country: string //optional
    state: string //optional
    zip: string //optional
  }
  error: { //optional
    code: string
    message: string
    recommended_message_for_user?: string
  }
  finance: { //optional
    amount: number
    currency: string
    internal: { //optional
      amount: number
      currency: string
    }
    external: { //optional
      amount: number
      currency: string
    }
  }
  	error: { //optional
  		code: string
  		message: string
  		recommended_message_for_user?: string
  	}
  	three_ds: { //optional
    		eci: string
  	}
  	redirect_url: string //optional
  	verify_url: string //optional
}
}
                                

Supported Translations

Solid Payment Form translated automatically by detecting the locale of the payer browser. You could also use the following subset of IETF language tags to configure localization.

Value	Locale
af	Afrikaans
ar	Arabic
bn	Bengali
zh	Chinese
cs	Czech
da	Danish
nl	Dutch
en	English
fi	Finnish
fr	French
de	German
hi	Hindi
id	Indonesian
it	Italian
ja	Japanese
ko	Korean
ms	Malay
no	Norwegian
pl	Polish
pt	Portuguese
ro	Romanian
ru	Russian
es	Spanish
sv	Swedish
th	Thai
tr	Turkish
uk	Ukrainian
vi	Vietnamese

Google Pay Button on Payment Form

To start processing Google Pay payments via Solid Payment Form, you must perform a few steps.

First of all, you need to verify your domain on the Google Site. Note that you must be logged in as a Google Developer to do this. If not, you will be redirected to Google Pay's support page.

Secondly, you must receive the Merchant ID parameter. This parameter ensures that customers can make payments on your site through Google Pay.

After completing these two steps on the Google side, you can proceed with the integration on the Solid Payment Form side.

To displaying Google Pay Button on the Solid Payment Form, you must add the following parameters to the paymentIntent object for the Solid Payment Form to display the Google-Pay Button.

Parameter	Type	Mandatory	Description	Example
google_pay_merchant_id	string	Yes, for displaying the Google-Pay Button	The Merchant ID parameter that you receive on the Google side.	10911390523550288022
google_pay_merchant_name	string	No	The merchant name, which can be displayed to the customers when paying by Google. It would be better to pass this parameter so that Google does not substitute it on its own.	Solid

To find out that the Google-Pay button has been shown, subscribe to the mounted event. When the event is emitted for the googlebtn entity, this means the Google-Pay button is fully displayed.

The process of subscribing to Payment Form Events is in the following article.

Google Pay Button Customisation

In addition to displaying the button on the form, you can also control the button's position, colour, and size. Use the googlePayButtonParams object for changes as you would for all other customisation in a Solid Payment Form.

Button Position

To choose the position to place the Google-Pay button on your own, you need to create and specify the div. Then, pass the value of the created container to the containerId parameter in the googlePayButtonParams object.

If you haven't specified containerId, we display it by default - above all fields of the Solid Payment Form.

Please note that if you specify a not created container, we will not display the Google-Pay button. In this case, we will return the following error to the console.

Container with id =‘specified-container’ doesn’t exist

Button Styling

On the Solid Payment Form side, some options allow you to style the Google Pay button to fit your site's style as much as possible.

We allow changing two parameters of the button in the googlePayButtonParams object:

color with options:

default - may change the colour over time (day or night theme);
black - a black button suitable for use on a white or light background;
white - a white button suitable for use on colourful background.

type with options:

buy - 'Buy with Google Pay' button (default);
plain - Button without additional text.

By default, the Solid Payment Form displays the button with black color and plain type.

The properties are supported to customize Google Pay Button:

Parameter	Type	Description	Example
containerId	string	The id of container to place the Google-Pay button	test-google-button-container-id
color	string	The color of the Google Pay Button on the Solid Payment Form	white
type	string	The type of the Google Pay Button on the Solid Payment Form	plain
allowedAuthMethods	array	The authentication method of the card transaction. A card authenticated with the use of a CRYPTOGRAM_3DS or with a PAN_ONLY authMethod. By default both types are available.	['PAN_ONLY', 'CRYPTOGRAM_3DS']

Button Styling Code Sample
                                    formParams: { } 
googlePayButtonParams: {
		containerId: 'test-google-button-container-id'
		color: 'white',
	        type: 'plain', 
                allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS']
}

                                

Apple Pay Button on Payment Form

This guide provides step-by-step instructions for enabling Apple Pay on the web with the Solid Payment Form. After completing the following steps, your payment form includes an Apple Pay button.

Solid Payment Form adheres to Apple's development requirements for Apple Pay on the Web. Solid users can accept Apple Pay on the web in Safari, starting with iOS 10 or macOS Sierra.

Displaying an Apple Pay button

To start processing Apple Pay payments via Solid Payment Form, you must perform a few steps.

First of all, you need to host the domain-verification file at the following path for each domain you’re need to process Apple Pay Payments:

Domain-verification file location
                                    HTTPS://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association
                                

After placing the domain-verification file on your site, you must verify the domain in HUB. Apple Pay Domain verification is available in the Developers section. Domain verification is available only for websites that Solidgate Team approved for processing payments.

When the domain is verified, you are ready to display the Apple Pay Button on the Solid Payment Form. You must add the following parameter to the paymentIntent object to display the ApplePay Button.

Parameter	Type	Mandatory	Description	Example
apple_pay_merchant_domain	string	Yes, for displaying the ApplePay Button	The domain, where you placed the domain-verification file.	solidgate.com

To indicate that the ApplePay button has been shown, subscribe to the mounted event. When the event is emitted for the applebtn entity, this means the ApplePay button is fully displayed.

Apple Pay Button Customisation

In addition to displaying the button on the form, you can also control the button's position, color, and type. Use the applePayButtonParams object for changes as you would for all other customisation in a Solid Payment Form.

Button Position

To choose the position to place the Apple Pay button on your own, you need to create and specify the div. Then, pass the value of the created container to the containerId parameter in the applePayButtonParams object.

If you haven't specified containerId, we display it by default - above all fields of the Solid Payment Form.

Please note that if you specify a not created container, we will not display the Apple Pay button. In this case, we will return the following error to the console.

Container with id =‘specified-container’ doesn’t exist

Button Styling

On the Solid Payment Form side, some options allow you to style the Apple Pay button to fit your site's style as much as possible.

We allow changing two parameters of the button in the applePayButtonParams object:

color with options:
- black - use on white or light-color backgrounds that provide sufficient contrast. Don't use on black or dark backgrounds.
- white-outline - use on white or light-color backgrounds that don't provide sufficient contrast. Don't place on dark or saturated backgrounds.
- white - use on dark-color backgrounds that provide sufficient contrast.
type - Apple provides several types of buttons so that you can choose the button type that fits best with the terminology and flow of your purchase or payment experience. More information you could find in the Apple Pay Guidelines.

By default, the Solid Payment Form displays the button with white-outline color and plain type.

Button Hiding

You could always hide the button for the user by passing false to the enabled parameter. You don't need to specify true to display the button on the form - this is the default value. When you pass the false value, it means that the form with the passed parameters of containerId, color and type is collected but not displayed on the Solid Payment Form.

The properties are supported to customize Apple Pay Button:

Parameter	Type	Description	Example
enabled	boolean	The parameter is responsible for displaying the Apple Pay Button on the Solid Payment Form	false
containerId	string	The id of container to place the Apple Pay Button	test-apple-button-container-id
color	string	The color of the Apple Pay Button on the Solid Payment Form	white
type	string	The type of the Apple Pay Button on the Solid Payment Form	plain

Apple Pay Button Styling Code Sample
                                    applePayButtonParams: {
  enabled: false,
  containerId: 'apple-pay-button-container',
  color: 'white-outline',
  type: 'plain'
}
                                

Customize the Apple Payment Sheet

Solid Payment Form gave you access to customize Merchant Name Label on the Apple Payment Sheet. To change the name you need to pass the apple_pay_merchant_name parameter in the paymentIntent object.

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, product ID, or one of the other available parameters 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 Solid Payment Form parameter, 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.

Please, note that we are not saving the data from the paymentIntent object if you use the update method.

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
order_id	string	No	Order ID specified in the merchant system. Order ID must be unique.	84d4-ab065
order_description	string	No	Order description in UTF-8 code.	description
order_date	string	No	Date of order creation in format YYYY-MM-DD-HH-MM-SS.	2022-02-21 11:21:30
order_items	integer	No	Order items in UTF-8 code	item5
order_number	string	No	The number of payments by the user.	4
success_url	string	No	URL of merchant page, which a customer will be redirected in case of successful payment	http://merchant.example/success
fail_url	string	No	URL of merchant page, which a customer will be redirected in case of unsuccessful payment	http://merchant.example/fail
type	string	No	Parameter for transaction authorization through a payment form	auth
transaction_source	string	No	Source of transactions on the merchant site.	Main menu
traffic_source	string	No	Source of traffic	Instagram

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

After the signature creating, you need to execute the update method in the Solid 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
	}
);
                                

If one of the parameters in the udateIntent request is invalid (f.e. the Order ID will not be unique), you will get a response with an error.

Update Response Sample
                                    {
    "error": {
        "code": "2.01",
        "message": [
            "Invalid data"
        ]
    }
}
                                

Submit Form without Pay Button

Solid leaves the option to display your payment button below the Solid Payment Form. Use this feature to collect additional data from the user on the payment page.

To hide a Solid Pay Button, you need to describe the display property using a formParams object.

Hiding Button Sample
                                    formParams: {
    allowSubmit: false
}
                                

To submit the Solid Payment Form without using a Solid Button, you need to call the form's submit method.

Submit Method Sample
                                    document.getElementById('customSubmitButton').addEventListener('click', () => form.submit())
                                

Additional Fields on Solid Payment Form

Additional Fields could be required to process the payment in some countries. The solid Payment Form will check the Card BIN and receive a solution to display Additional Fields according to information about the BIN country.

Also, depending on the provider, the customer phone parameter is often used as a means of verifying the identity of the person making a payment, for example in India this is indian_customer_phone. This parameter typically requires the person to enter their registered mobile phone number, which is then used to authenticate the payment.

The list of additional fields and the countries for which they are displayed are presented below.

Country	Country Code (ISO 3166-1)	Additional Field Class	Field Title
Argentina	ARG	argentina_dni	DNI
Bangladesh	BGD	bangladesh_nic	National Identity Card
Bolivia	BOL	bolivia_ci	Cedula de Identidad
Brazil	BRA	brazil_cpf	CPF
Cameroon	CMR	cameroon_cni	СNI
Chile	CHL	chile_ci	Rol Único Tributario
China	CHN	china_id	Citizen ID Number
Colombia	COL	colombia_cc	Cedula de Ciudadania
Costa Rica	CRI	costa_rica_ci	Cédula de Identidad
Dominican Republic	DOM	dominicana_id	Identity card
Ecuador	ECU	ecuador_ci	Cédula de Identidad
El Salvador	SLV	el_salvador_id	Personal Identification Card
Egypt	EGY	egypt_id	Identity card
Ghana	GHA	ghana_card	Ghana Card
Guatemala	GTM	guatemala_cui	CUI
India	IND	india_pan, indian_customer_phone	PAN, Customer Phone
Indonesia	IDN	indonesia_nik	NIK
Japan	JPN	japan_id	My Number
Kenya	KEN	kenya_id	National ID Card
Malaysia	MYS	malaysia_nric	NRIC
Mexico	MEX	mexico_curp	CURP
Morocco	MAR	morocco_cnie	CNIE
Nigeria	NGA	nigeria_nin	NIN
Panama	PAN	panama_id	Cedula de Identidad
Paraguay	PRY	paraguay_ci	Cédula de Identidad
Peru	PER	peru_dni	DNI
Philippines	PHL	philipines_psn	PSN
Senegal	SEN	senegal_cni	CNI or ECOWAS ID Card
South Africa	ZAF	south_africa_id	South African Identity Card
Tanzania	TZA	tanzania_id	National Identity Card
Thailand	THA	thailand_id	Thai Identity Card
Turkey	TUR	turkey_tc_kimlik_no	T.C. Kimlik No.
Uganda	UGA	uganda_nic	National ID number (NIC)
Uruguay	URY	uriguay_ci	Cédula de Identidad
Vietnam	VNM	vietnam_vnid	VNID
United States	USA	zip_code	ZIP code

Additional fields classes will be formed as follows:

ZIP Code Field Class Sample 
                                     class = "input_group zip_code additional_field"
                                

You can customize all additional fields at once using the additional_field class. In this case, styles will be applied to all additional fields classes, described in the table above.

CSS Sample of Custom Styles for Additional Fields at once
                                    styles: {
    additional_field: {
      'input': {
        'color': 'red'
      }
    }
}
                                

If you want to customize a definite field, you need to apply styles to the Additional Field Class name.

CSS Sample of Custom Styles for Definite Additional Field
                                    styles: {
    guatemala_cui: {
      'input': {
        'color': 'red'
      }
    }
}
                                

Fields Label Customisation

You could customize all labels on the Solid Payment Form. To change the field label you need to pass the parameter fieldNameLabel with the new Label Name to formParams Objects.

The parameters for Card Data Fields are presented below.

Card Data Fields Parameters
                                    cardExpiryDateLabel
cardCvvLabel
cardNumberLabel
cardHolderLabel
                                

To get the value of fieldNameLabel for additional fields, you need to take the Field Class name on the table, remake it into camelcase and add a ‘label’ in the end.

For example, bolivia_ci move to boliviaCiLabel and argentina_dni moves to argentinaDniLabel.

Label Customisation Sample
                                    formParams: {
    cardExpiryDateLabel: 'Expiration Date', 
    boliviaCiLabel: 'CI'
}
                                

Supported browsers

Solidgate payment form requires that your browser supports TLS 1.2. If TLS 1.2 is not supported, the payment form will not be displayed. Additionally, it is important:

do not overload the browser with extensions
the stable function with built-in browsers (Facebook&Instagram) is not guaranteed

Solidgate Payment Form (JS) strives to support the latest versions of all major browsers. For security reasons and to provide customization options to customers, we do not support browsers that do not receive security updates and are low usage.

We support:
Chrome, Chrome Mobile, Firefox, Samsung Browser, Opera and Microsoft Edge
Safari on desktop and iOS (last 3 major versions)