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.

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
currencyMstring(3)Currency amount. 3 letter currency code under ISO-4217USD
order_descriptionMstring(255)A description of the paymentPremium package
order_dateOstring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2018-08-07 11:21:30
order_itemsOstring(255)Order items in UTF-8 codeitem 1, item 2
order_numberOintegerNumber of payments by user1
subscription_product_idOstring(36)Product ID in SolidGate subscription service
 
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
 
callback_urlOstring(255)URL of merchant page, where response with payment result will be senthttp://merchant.example/callback
fail_urlOstring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlOstring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
settleMobject  
settle: delay_hoursMintegerTime (in hours) when auto-settle should be done24
websiteOstring(255)Website from which transaction took placehttp://merchant.example
processing_midMstring(255)Use this field to route your payment to specified MIDb0651d75db2
dynamic_descriptorOstring(50)The descriptor for the transactionpayhere.com
three_dsOobjectInformation required for 3D Secure payments 
three_ds: forceObooleanFlag whether to send user for 3DS FlowFALSE
three_ds: attempt_non_secureObooleanDetermines whether to attempt a 3D Secure payment as non-3D Secure should the card issuer not be enrolledFALSE
customerMobjectDetails of the customer to associate with the source 
customer: user_idMstring(100)The identifier of an existing customercuid_y343t4mf46fdzuxjbcn2giaqnb44
customer: emailMstring(100)An optional email address to associate with the customeruser@solidgate.us
customer: ip_addressMstring(50)The IP address used to make the payment. Required for risk checks8.8.8.8
customer: first_nameOstring(100)The customer's first nameChack
customer: last_nameOstring(100)The customer's last name.Blank
customer: phone_numberOstring(50)The payment source owner's phone number+1415 555 2671
customer: date_of_birthOstring(50)Birthdate in YYYY-MM-DD format. 2000-11-21
customer: ip_countryOstring(3)ISO-code of the country that was sent in the requestUSA
customer: delivery_addressOobjectThe delivery address 
customer: delivery_address: line1Ostring(100)The delivery address line 115 William St
customer: delivery_address: line2Ostring(100)The delivery address line 2 
customer: delivery_address: cityOstring(100)City of the delivery address New York
customer: delivery_address: stateOstring(100)State of the delivery address WA
customer: delivery_address: zipOstring(10)ZIP code of the delivery address 10005
customer: delivery_address: countryOstring(3)ISO country code of the delivery address USA
payment_formOobject  
payment_form: languageOstring(2)Language code of requested Payment formEN

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

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 SolidGate Payment Form. The list of templates is beloved the table.default
isSolidGateLogoVisiblebooleanVisibility of the Powered by SolidGate 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

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 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 
card_viewClass for editing card template. Sample for changing card color: 
card_view: { 'background': '#3D4251'}
body_errorsThe errors customisation for card and flat template. 
card_brandsClass for editing the size and position of card brands.
secure_infoClass 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 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.

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

ParameterTypeMandatoryDescriptionExample
amountintegerYes, for the non-subscription workflowOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents1020
currencystringYes, for the non-subscription workflowCurrency 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_idstringYes, for the subscription workflowID 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

ParameterTypeDescriptionExample
partialIntentstringThe 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==
signaturestringSignature 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. 

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