Create your payment form

Understand how to integrate the payment form into your product

Solidgate’s payment form enables tokenization of sensitive data and management of 3D Secure authentication and supports multiple payment methods.

Integration steps

This guide simplifies adding Solidgate’s payment form to your website. It covers preparing the backend, installing the SDK, creating API instances, and setting up merchant data. Additionally, it explains how to initialize the form using different JavaScript frameworks and customize its look with parameters and styles.

Setup backend

First and foremost, it is necessary to prepare your backend. The Solidgate SDK simplifies integrating Solidgate’s payment form into websites and applications. It provides an easy-to-use interface for handling transactions and customizing payment forms.

Install the SDK
The Solidgate SDK should be installed in your Node.js (recommended) environment by running the command npm install @solidgate/node-sdk

Create an API instance
To interact with the Solidgate API, you need to create an API instance by calling the API constructor function with your Solidgate Public (merchant) and Secret (private key) keys and as arguments. In the example code, this is done using the following line of code:

1

let api = new solidGate.Api("merchant", "private_key");

Form the merchant data
To create a charge, you must provide some information about the transaction. This information is encapsulated in a MerchantData object, which is created by calling the formMerchantData function on your API instance. In the example code, the formMerchantData function is called with fields:

Non-subscription

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


const solidGate = require('@solidgate/node-sdk');

let api = new solidGate.Api("merchant", "private_key");

let merchantData = api.formMerchantData({
  "ip_address": "8.8.8.8",
  "platform": "WEB",
  "order_id": "123456",
  "order_description": "Premium package",
  "amount": 1020,
  "currency": "USD",
  "geo_country": "GBR",
  "customer_email": "test@solidgate.com",
  "language": "en",
  "force3ds": True,
  "settle_interval": 48,
  "type": "auth",
  "order_number": 1,
  "order_date": "2020-12-21 11:21:30",
  "order_items": "item1, item2",
  "order_metadata": {
    "coupon_code": "NY2018",
    "partner_id": "123989"
  },
  "device": "iPhone 8 iOS 12.0",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (HTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "verified": True,
  "retry_attempt": 1,
  "geo_city": "New Castle",
  "website": "https://google.com",
  "customer_phone": "380111111111",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_date_of_birth": "2000-11-21",
  "fraudulent": True,
  "success_url": "https://Merchant.example/success",
  "fail_url": "https://Merchant.example/fail",
  "transaction_source": "main_menu",
  "traffic_source": "facebook",
  "apple_pay_merchant_name": "Test"
});

const dataToFront = merchantData.toObject(); 

Subscription

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


const solidGate = require('@solidgate/node-sdk');

let api = new solidGate.Api("merchant", "private_key");

let merchantData = api.formMerchantData({
  "ip_address": "8.8.8.8",
  "platform": "WEB",
  "order_id": "123456",
  "order_description": "Premium package",
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "customer_account_id": "4dad42f808",
  "geo_country": "GBR",
  "customer_email": "test@solidgate.com",
  "language": "en",
  "force3ds": True,
  "settle_interval": 48,
  "type": "auth",
  "order_number": 1,
  "order_date": "2020-12-21 11:21:30",
  "order_items": "item1, item2",
  "order_metadata": {
    "coupon_code": "NY2018",
    "partner_id": "123989"
  }, 
  "device": "iPhone 8 iOS 12.0",
  "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (HTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
  "verified": True,
  "retry_attempt": 1,
  "geo_city": "New Castle",
  "website": "https://google.com",
  "customer_phone": "380111111111",
  "customer_first_name": "John",
  "customer_last_name": "Snow",
  "customer_date_of_birth": "2000-11-21",
  "fraudulent": True,
  "success_url": "https://Merchant.example/success",
  "fail_url": "https://Merchant.example/fail",
  "transaction_source": "main_menu",
  "traffic_source": "facebook",
  "apple_pay_merchant_name": "Test"
});

const dataToFront = merchantData.toObject(); 

Convert the merchant data to an object
The MerchantData object that is returned by the formMerchantData function is an instance of a class, so you may need to convert it to a plain object before you can use it in your front-end code. In the example code, this is done by calling the toObject function on the MerchantData object, which returns a plain JavaScript object.

After you’ve set up the merchant data and turned it into a simple object, you can effortlessly integrate it into your front-end code by transmitting the paymentIntent encrypted String (during form initialization).

Without SDK

In addition to using the Solidgate SDK for integrating the payment form into your website, there is an alternative option to work without the SDK. To do this, you need to manually handle the backend preparation and setup process.

Backend Preparation: Set up your server-side code to handle the communication with Solidgate’s API using your preferred programming language and libraries.
Create DTO: Create a JSON object containing the mandatory fields for a payment transaction, and then encrypt it.
Pass the paymentIntent to the frontend: Once you have successfully encrypted the paymentIntent, pass it to your front-end code for further processing, such as initializing the payment form.
Signature generation: To initialize the Solidgate payment form, generate the Signature parameter on your backend, which verifies the merchant’s request authenticity on the payment gateway server. The signature is generated from the paymentIntent encrypted String, as detailed in the following article.

Working without the SDK demands a thorough grasp of Solidgate’s API, manual management of communication, data, and error handling, providing greater flexibility and control for developers, but with increased effort and time compared to using the SDK.

Setup frontend SDK

The SDK is a hosted, pre-built user interface component for payments. The SDK helps tokenize the customer’s data so that the card data does not come into contact with the merchant’s website.

When starting with the Solidgate payment form, you can use our official payment form SDK wrapper for different JS frameworks:

These integrations automatically load solid-form.js and provide a convenient interface for working with the form. Furthermore, you can use manual installation.

Alternatively, manually add the payment form SDK to your checkout page by inserting the script tag at the end of the HTML file’s <body> tag. Utilize the Solidgate CDN-hosted form for easy integration, ensuring the latest version and preventing potential issues from script modification.

1

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

Check the console for a warning that Solidgate PaymentFormSdk is already initialized. If this warning appears, solid-form.js has most likely been loaded and executed twice. Remove the unnecessary connection.

Next, create a container for the payment form on your page and assign a custom ID, as shown below. Avoid setting height dimensions or display properties for elements inside the container, including the container itself, to prevent form appearance bugs due to CSS conflicts.

The following example specifies a container with the default id of Solidgate SDK.

1

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

Otherwise, you can use your own container, passing its id to iframeParams like in the example below.

Container ID Definition Sample

1
2
3
4
5


const data = {
  iframeParams: {
    containerId: 'your-custom-container-id'
  }
}   

Form initialization

After completing all the steps described above and modifying all required parameters, you need to initiate the Solidgate SDK.

SDK Initialization Sample

1

const form = PaymentFormSdk.init(data);

Object data should contain the:

Form request data object sample

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


const data = {
  merchantData: {
    merchant: 'api_pk_7b197...ba108f842',
    signature: 'MjliMzU4ODE3ZDVlM2E1YWZmYzI1NmU4MzU3YjhlODRkMTJmZTk1NjIxOWNiYzFmNDk0N2NkNjk5YTA5Y2Q4NzIzOWIwMTgxZTQwOGExZjFmYWQ1NzQyYjc3ZGRjMzE0MTczYTQ2OGEyMTlmNGI4YzA5ZmNhMTczZDI0ZDBkZmM=',
    paymentIntent: 'E5FKjxw5vRjjIZBKtH_Q9oN1Wmn5icMn720prO4nPB3cYpzC9wLAHwq9IwstmD-YFLFPsdq2Rk9YzRJhxdPEq2KI19fFt1QotX-smH5_xWxGfYcv9rf2Y4v4KWgbjzJylHTDM6eCXVvbdZyVU54vD3sxntN3gFiyuhEzMn8mKoDV0UdIqLN_VsTAdehBUrqk7aPNzXCfSqpy9pCBlpdFNCfgOyHoDXGGS_Z9fK3gCw7usF2v0IU96mQGzdtyEUs1Z2MJYwle7sjEkWNEb9SkpW1zUXEZCFMF8Cu-dn6fWe4cVE2Ok1MDeTE43dySgw9e8GzMxgPmG2YFjg5xcvuedQ=='
  },
  formParams: {
    buttonType: 'default',
    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'
      }
    }
  }
}

Form events

Using the Solidgate payment form, you can build your user actions tracking by the events that it returns.

You can subscribe to Solidgate payment events like in the examples below.

Solidgate SDK Event Listener Sample

1
2
3
4
5
6


const form = PaymentFormSdk.init(data)

form.on('event_type', (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

This event indicates that the Solidgate SDK displayed the Solidgate payment form, Google Pay, or an Apple Pay button.

Mounted

1
2
3
4
5
6
7
8


form.on('mounted', e => {
  const data = e.data // MountedMessage
})

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

Submit

This event indicates that the user submitted the payment. The event could be triggered for one of the variations: the Solidgate payment form, Google Pay, or Apple Pay.

Submit

1
2
3
4
5
6
7
8


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

interface SubmitMessage {
   type: 'submit',
   entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values, indicates how payment was processed
}

Success

This event indicates that the payment was successfully processed.

Success

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


form.on('success', e => {
   const data = e.data // SuccessMessage
})

interface SuccessMessage {
   type: 'success',
   entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values, indicates how payment was processed
   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

This event indicates that the payment had been declined.

Fail

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


form.on('fail', e => {
  const data = e.data // FailMessage
})

interface FailMessage {
  type: 'fail'
  entity: 'applebtn' | 'googlebtn' | 'form' // one of listed values, indicates how payment was processed
  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

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

Verify

1
2
3
4
5
6
7


form.on('verify', e => {
  const data = e.data // VerifyMessage
})

interface VerifyMessage {
  type: 'verify'
}

Form redirect

This event informs that the iframe performs a redirect (to your or the Solidgate status page).

Form redirect

1
2
3
4
5
6
7


form.on('formRedirect', e => {
  const data = e.data // FormRedirectMessage
})

interface FormRedirectMessage {
  type: 'formRedirect'
}

Interaction

This event information on the current state of the Solidgate payment form and the user’s interaction with the controls:

isTouched - external interaction with the field
isValid - validity check

Interaction

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


form.on('interaction', e => {
  const data = e.data // InteractionMessage
})

interface InteractionMessage {
  type: 'interaction'
  target: { // Indicates source of interaction
    type: 'button' | 'input' // one of the listed
    name: 'submit' | 'googlePay' | 'applePay' | 'cardNumber' | 'cardCvv' | 'cardExpiry' | 'cardHolder' // It could be one of the listed; furthermore, Solidgate might extend the list.
    interaction: 'click' | 'change' | 'focus' | 'blur' // one of the listed
  }
  cardForm: { // Indicates current card form state
    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

This event indicates that the Solidgate payment form was resized. For example, could resize after a validation message appeared.

Resize

1
2
3
4
5
6
7
8
9


form.on('resize', e => {
  const data = e.data // ResizeMessage
})

interface ResizeMessage {
  type: 'resize'
  width: number 
  height: number 
}

Custom styles appended

This event indicates that your styles have been applied to the Solidgate payment form. This event is helpful for cases when you want to draw your preloader over the Solidgate payment form (at this point, you may remove it).

Custom styles appended

1
2
3
4
5
6
7


form.on('customStylesAppended', e => {
  const data = e.data // CustomStylesAppendedMessage
})

interface CustomStylesAppendedMessage {
  type: 'customStylesAppended'
}

Error

This event indicates any Solidgate payment form error during form initialization. These errors will also be shown in the browser console.

Error

1
2
3
4
5
6
7
8


form.on('error', e => {
  const data = e.data // ErrorMessage
})

interface ErrorMessage {
   type: 'error'
   value: Error
}

The following Error classes are provided:

ConnectionError - happens when the user experiences problems with their internet connection.
InitPaymentError - happens when an error with payment intent occurs during initialization. The message will contain a code and an explanation of the particular error. The following error codes are supported:
- 1.01 - Invalid credentials or signature generated.
- 2.01 - Invalid data in payment intent. It could be a non-existing product ID or other properties, which will be described in a message.
- 6.01 - Something went wrong on our backed side, please contact support.
GatewayResponseError - occurs when we cannot parse the response from our backend. Please contact support in case of such errors.

Card

This event indicates that the customer has entered the card number and provides information about the card brand when the card number is validated.

Card

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


form.on('card', e => {
  const data = e.data // CardMessage
})

interface CardMessage {
  type: 'card'
  card: {
    brand: string // one of the card brands in upper case ('VISA', 'MASTERCARD' etc) or 'unknown'
    bin: '111222' // string with the card bin (first 6 symbols)
  }
}

Order status

This event indicates that the order status was changed while processing. However, the event may not show all changes before the final order status: approved or declined.

Order status

1
2
3
4
5
6
7
8


form.on('orderStatus', e => {
  const data = e.data // OrderStatusMessage
})

interface OrderStatusMessage {
  type: 'orderStatus'
  response: object // partial Order status operation response (https://api-docs.solidgate.com/#tag/Card-payments/operation/Card%20order%20status)
}

Form update

You do not have to repeatedly call the payment form when using multiple tariffs. Instead, you can request the form once and change the amount , currency , product ID , or one of the available parameters using the update method of the form instance.

To update Solidgate payment form parameter, generate the Signature parameter on your backend. The signature allows for verifying whether the request from the merchant is valid on the payment gateway server. It is generated from the partialIntent encrypted String

Setup backend

Form the merchant data
First of all, it is necessary to make sure that the backend is prepared, while in the example code, the formMerchantData function is called with fields:

Non-subscription

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


const solidGate = require('@solidgate/node-sdk');

let api = new solidGate.Api("merchant", "private_key");

let merchantData = api.formMerchantData({
  "amount": 1020,
  "currency": "EUR",
  "order_id": "84d4-ab065",
  "order_description": "description",
  "order_date": "2022-02-21 11:21:30",
  "order_items": "item5",
  "order_number": "4",
  "success_url": "http://Merchant.example/success",
  "fail_url": "http://Merchant.example/fail",
  "type": "auth",
  "transaction_source": "Main menu",
  "traffic_source": "Instagram"
});

const partialIntent = merchantData.intent;
const signature = merchantData.signature

Subscription

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


const solidGate = require('@solidgate/node-sdk');

let api = new solidGate.Api("merchant", "private_key");

let merchantData = api.formMerchantData({
  "product_id": "faf3b86a-1fe6-4ae5-84d4-ab0651d75db2",
  "order_id": "84d4-ab065",
  "order_description": "description",
  "order_date": "2022-02-21 11:21:30",
  "order_items": "item5",
  "order_number": "4",
  "success_url": "http://Merchant.example/success",
  "fail_url": "http://Merchant.example/fail",
  "type": "auth",
  "transaction_source": "Main menu",
  "traffic_source": "Instagram"
});

const partialIntent = merchantData.intent;
const signature = merchantData.signature

Convert the merchant data to an object
The MerchantData object that is returned by the formMerchantData function is an instance of a class, so you may need to convert it to a plain object before you can use it in your front-end code. In the example code, this is done by calling the toObject function on the MerchantData object, which returns a plain JavaScript object.

Once you have formed the merchant data and converted it to a plain object, you can use it in your front-end code to update with partialIntent encrypted String

Partial form update

Update method parameters

Expand all

partialIntent

string

Description

The encrypted aes-cbc-256 string of JSON request data with random IV (16bytes) and private key is the first 32bytes of Merchant private key.

Example

E5FKjxw5vRjjIZ....vmG2YFjg5xcvuedQ==

signature

string

Description

Signature of request. It allows verifying whether the request from the Merchant is genuine on the payment gateway server.

Example

MjNiYjVj…ZhYmMxMzNiZDY=

Update Method Execution Sample

1
2
3
4


form
  .update({ partialIntent, signature })
  .then(callbackForSuccessUpdate)
  .catch(callbackForFailedUpdate);

It is important to note that you must handle possible errors, including network errors, in callbackForFailedUpdate by calling a valid update or init; otherwise, the form will remain unresponsive.

If one of the parameters in the updateIntent request is invalid (e.g. the order_id will not be unique), you will get an error.

Update Error Sample

1
2
3
4
5
6
7
8


{
  "error": {
    "code": "2.01",
    "message": [
      "Invalid Data"
    ]
  }
}

Custom submission

The Solidgate payment form has two options for submitting a payment, submit via:

a click on the payment button
the form.submit method

We leave the option to display your payment button below the payment form. Use this feature to collect additional data from the user.

To hide the payment form submit button, you need to set the allowSubmit display property in formParams to false during initialization. This will not only hide the button but also prevent the form from being submitted via enter key press in form fields.

Hiding Default Sample

1
2
3
4
5
6
7


const form = PaymentFormSdk.init({
  ...restData,
  formParams: {
    ...restFormParamsIfPresent,
    allowSubmit: false
  }
})

To submit the payment form without using a Solidgate button, you need to call the form’s submit method.

Submit Method Sample

1

document.getElementById('yourCustomSubmitButtonId').addEventListener('click', () => form.submit())

The payment form cannot be submitted if:

additional fields are requested to be displayed
some fields on the form have yet to be validated
validation errors are present in the form fields

If none of these points are met, the form is ready to be submitted.

Additional fields

Solidgate payment form will check the Card BIN and receive a list of necessary additional fields according to information about the BIN country (the first 6 digits).

Also, depending on the provider, the customer phone parameter is often used to verify 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.

Additional fields classes will be formed as follows:

ZIP Code Field Class Sample

1

    "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 field classes described in the table above.

CSS Sample of Custom Styles for additional fields at once

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


PaymentFormSdk.init({
  ...restData,
  styles: {
    'additional_field': {
      'input': {
        'color': 'red'
      }
    }
  }
})

If you want to customize a specific field, you need to apply styles to this specific additional field class name.

CSS Sample of Custom Styles for Definite Additional Field

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


PaymentFormSdk.init({
  ...restData,
  styles: {
    'guatemala_cui': {
      'input': {
        'color': 'red'
      }
    }
  }
})

Validation rules

Front-end validation and auto-tabulation prevent errors and fraud, verify data correctness, enhance user experience, end increase transaction success.

Validation of form fields occurs when a field loses focus.

Card number

Validate the correctness of data entered (check data entered for validity)

The validity of the card number is verified by the Luhn Algorithm. The Luhn Algorithm calculates the check digits of a plastic card number in accordance with the standard ISO/IEC 7812 WIKI

Define card brand to display the desired logo

For card payments, one of the most important UX rules is automatic card type detection and automatic card number formatting (spacing). To implement these functions, you need to know the IIN ranges and spacing patterns for card types.

Determine the country of the card by BIN and add fields dynamically if necessary

To dynamically add fields to the form, we need to define the country of the map. Depending on this, we add the required field on the frontend.

default

card

inline

flat

CVV

The CVV field can only accept 3 or 4 digits. Validation of the CVV field depends on the card brand:

for AMERICAN EXPRESS, the CVV field must contain 4 digits
for all other card brands, the CVV field must contain 3 digits

Cardholder

The field with the name of the cardholder is disabled by default. It is possible to enable this field through CSS styles.

Rules for the field
- at least 3 characters
- convert from Cyrillic to Latin
- must not contain symbols and numbers, only letters
- auto tabulation is disabled

Supported browsers

The Solidgate payment form requires that the customer's browser supports TLS 1.2. If TLS 1.2 is not supported, the payment form will not be displayed. Additionally, it is important to know:

some of the user’s extensions can break the correct behavior of our payment form
we don’t guarantee payment form stable functioning when rendered inside in-app browsers (Facebook, Instagram browser, etc.)

The 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)

Supported translations

The Solidgate payment form is translated automatically by detecting the location of the customer’s browser.

Afrikaans af
Arabic ar
Bengali bn
Chinese zh
Czech cs
Danish da
Dutch nl
English en
Finnish fi
French fr

German de
Hindi hi
Indonesian id
Italian it
Japanese ja
Korean ko
Malay ms
Norwegian no
Polish pl
Portuguese pt

Romanian ro
Russian ru
Spanish es
Swedish sv
Thai th
Turkish tr
Ukrainian uk
Vietnamese vi

You can also configure localization with the following subset of IETF language tags WIKI

Related articles FAQ

Payment form 1-st payment flow

How-to initiate 2-step payment via Payment form (Auth+Settle)

The Payment form is not loading

Using Java for Payment form