Solid Payment Form

Use Solid Payment Form 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, handle 3D Secure authentication. All sensitive information is handled by Solid Payment Form, so it features  PCI compliance.

Setup Solid Payment Form

First of all, you need to include the Solid Payment Form (Solid SDK) on your checkout page by either 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 SDN,  the script could be modified. 

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

Next, create the following object on your page in the place, where the payment form should be. Note, the id name can be different if it was changed in the script tag.

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

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

ID Name 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 verifying whether the request from the merchant is genuine on the payment gateway server. In this case, it’s generated not from JSON, but from the paymentIntent object.

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

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

ParameterTypeMandatoryDescription Example
ip_addressstringYesCustomer IP (only public ones) 8.8.8.8
currencystringYes, for the non-subscription flowCurrency amount. 3 letter currency code under ISO-4217 USD
amountinteger (64)Yes, for the non-subscription workflowOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents 1020
product_id stringYes, for the subscription workflowID of the predefined product faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
order_idstringYesOrder ID specified in the merchant system 123456
order_descriptionstringYesOrder description in UTF-8 code Premium package
platformstringYesCustomer platform at the moment of payment. Available values: WEB- desktop, MOB - mobile version, APP - application WEB
customer_emailstringYesCustomer email test@solidgate.com
customer_account_idstringYesCustomer ID in the merchant's system 4dad42f808
geo_countrystringNoCustomer country subject to ISO 3166-1 alpha-3 GBR
languagestringNoCustomer language settings for the Solid Payment Form field translation. Available values: RU - Russian, EN - English, FR - French, ES - Spanish, PT - Portuguese, JA - Japanese, AR - Arabic, IT - Italian, TR - Turkish, PL - Polish, DE - German IT
force3dsbooleanNoRouting payments flag for 3DS flow (enabled by Solid account manager) true
settle_intervalinteger NoTime (in hours) when auto-settle will be done 48
typestringNoParameter for transaction authorization through a payment form auth
order_numberinteger NoNumber of payments by user 1
devicestringNoDevice of customer iPhone 8 iOS 12.0
user_agentstringNoUser-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_sourcestringNoSource of transactions on site. main_menu
verifiedbooleanNoThe user was verified on the shop side true
retry_attemptinteger NoNumber of retry payment 1
geo_citystringNoCustomer City New Castle
websitestringNoThe website from which transaction took place. google.com
customer_phonestringNoCustomer telephone 380111111111
customer_first_namestringNoCustomer first name John
customer_last_namestringNoCustomer last name Snow
customer_date_of_birthstringNoCustomer birth date in format YYYY-MM-DD2000-11-21
fraudulentbooleanNoA customer was detected on the merchant end to be a suspicious onetrue
order_datestringNoDate of order creation in format YYYY-MM-DD-HH-MM-SS 2020-12-21 11:21:30
order_itemsstringNoOrder items in UTF-8 code item1, inetm2
callback_urlstringNoURL of merchant page, where response with payment result will be sent http://merchant.example/callback
success_urlstringNoURL of merchant page, which a customer will be redirected in case of successful payment http://merchant.example/success
fail_urlstringNoURL of merchant page, which a customer will be redirected in case of unsuccessful payment http://merchant.example/fail
chargeback_notification_urlstringNoURL of merchant page, where the notification of chargeback will be sent http://merchant.example/chargeback
alert_chargeback_notification_urlstringNoURL of merchant page, where the notification of chargeback alerts will be sent http://merchant.example/chargeback_alerts
traffic_sourcestringNoSource of trafficfacebook
 

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. 

ObjectMandatoryDescription
merchantDataYesThe main object required to init the form. Contains all the information for creating payment on the Solid side. 
formParamsNoAn object that allows you to control not mandatory parameters on the form (f.e. - Cardholder Name). In this object, you can also select a Solid Payment Form template. The list of templates is here.
stylesNoAn 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:

ParameterDescriptionExample
merchantUnique merchant identification. Shall be shared at the moment of registration.Test_Merchant
signatureSignature of request. It allows verifying whether the request from the merchant is genuine on the payment gateway server.MjNiYjVj…ZhYmMxMzNiZDY=
paymentIntentThe 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 Solid 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 on the table below. 

ParameterTypeDescription Example
submitButtonTextstringThe text on the Submit ButtonPay Now
isCardHolderVisiblebooleanVisibility of the Card Holder field on the formtrue
headerTextstringThe text on the header of the payment formEnter your payment data
titleTextstringThe text on the title of the payment formCard info
formTypeClassstringTemplate of the Solid Payment Form. The list of templates is beloved the table.default
isSolidLogoVisiblebooleanVisibility of the Powered by Solid logo. By default is false.true
cardBrandsarrayArray 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'],
secureBrandsarrayArray 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 stringFont-family for your payment form. To use it, please add google Font Link on the formParams object.DM Sans

Solid Payment Form templates

In case you don't want to customize your payment form styles, you could always use one of the templates of the Solid Payment Form. For the request one of the templates, please, pass the parameter formTypeClass in the formParams object. 

Available templates: 

  • flat
  • inline
  • card

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 ClassesDescription
form_bodyParameter responsible for the body of the form
card_numberCard number field parameter
expiry_dateExpiry date field parameter
card_cvvCard CVV field parameter
card_holderCardholder parameter field parameter
card_cpfCPF field parameter
zip_codeZIP code field parameter
card_dniDNI field parameter
card_pinPIN field parameter
card_curpCURP field parameter
submit_buttonSubmit button field parameter
headerThe payment form title - header for the payment form 
form_titleThe payment form subtitle 

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 PropertiesDescription
background-colorThe background-color CSS property sets the background color of an element.
paddingThe padding CSS shorthand property sets the padding area on all four sides of an element
displayThe 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-sizeThe 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-weightThe 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-bottomThe 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.
colorThe color CSS property sets the foreground color value of an element's text and text decorations.
border-colorThe 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 params, you need to add the variable on your page in order to init 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

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

Solid SDK Event Listener Sample

const form = PaymentFormSdk.init(data)

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

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

 

EventBodyDescription
mounted The event indicating 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 Solid status page.
success Event of the success payment processing. 
Please, note, this event initiates only when using the Solid status page.
verify The event informs that the payment starts processing through 3D flow. 
card{type: “card”, card: {brand: “VISA”}}The event informs about the payer card brand. Contains an object with brand information.
sessionExpired The session for submitting the Payment Form has expired. The session duration is 24 hours. 

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.

ValueLocale
ENEnglish
ARArabic
DEGerman 
ESSpanish 
FRFrench 
ITItalian 
JAJapanese
KOPortuguese 
PLPolish
PTPortuguese
RURussian
TRTurkish
UKUkraine