Solid 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 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 SDN, the script could be modified. 

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

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

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

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 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.

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_idstringNoCustomer ID in the merchant's system. Required for Subscription Payments 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
subscription_callback_url stringYes, for the subscription workflowSubscription callback address http://merchant.example/subscription_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 template

In case you don't want to customize your payment form styles, you could always use the template of the Solid Payment Form. 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 

CSS Sample of Custom Styles

styles: {
  form_body: {
    'font-family': 'Open Sans'
  },
  form_title: {
    display: 'flex',
    width: '100%',
    'justify-content': 'center',
    'font-weight': '500',
    'font-size': '28px',
    color: '#3D4251'
  },
  submit_button: {
    '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 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 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

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. 

 

EventEntitiesBodyDescription
mountedform, googlePayBtn 

{ type: "mounted", entity: "form" }

{ type: "mounted", entity: "googlePayBtn" }

The event indicating that the payment form / Google-Pay Button 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

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.

ParameterTypeMandatoryDescriptionExample
google_pay_merchant_idstringYes, for displaying the Google-Pay ButtonThe Merchant ID parameter that you receive on the Google side.10911390523550288022
google_pay_merchant_namestringNoThe 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 googlePayBtn 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:

ParameterTypeDescriptionExample
containerIdstringThe id of container to place the Google-Pay buttontest-google-button-container-id
colorstringThe color of the Google Pay Button on the Solid Payment Formwhite
typestringThe type of the Google Pay Button on the Solid Payment Formplain

Button Styling Code Sample

formParams: { } 
googlePayButtonParams: {
		containerId: 'test-google-button-container-id'
		color: 'white',
	        type: 'plain'
}