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.
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>
const data = {
iframeParams: {
containerId: 'id'
}
}
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.
Parameters for the paymentIntent object are described in the following table.
Parameter | Mandatory | Type | Description | Example |
---|---|---|---|---|
order_id | M | string(100) | Order ID specified in merchant system | 123443334 |
amount | M | integer | Order amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. | 1020 |
currency | M | string(3) | Currency amount. 3 letter currency code under ISO-4217 | USD |
order_description | M | string(255) | A description of the payment | Premium package |
order_date | O | string(50) | Date of order creation in format YYYY-MM-DD-HH-MM-SS | 2018-08-07 11:21:30 |
order_items | O | string(255) | Order items in UTF-8 code | item 1, item 2 |
order_number | O | integer | Number of payments by user | 1 |
subscription_product_id | O | string(36) | Product ID in SolidGate subscription service | faf3b86a-1fe6-4ae5-84d4-ab0651d75db2 |
callback_url | O | string(255) | URL of merchant page, where response with payment result will be sent | http://merchant.example/callback |
fail_url | O | string(255) | URL of merchant page, which a customer will be redirected in case of unsuccessful payment | http://merchant.example/fail |
success_url | O | string(255) | URL of merchant page, which a customer will be redirected in case of successful payment | http://merchant.example/success |
settle | M | object | ||
settle: delay_hours | M | integer | Time (in hours) when auto-settle should be done | 24 |
website | O | string(255) | Website from which transaction took place | http://merchant.example |
processing_mid | M | string(255) | Use this field to route your payment to specified MID | b0651d75db2 |
dynamic_descriptor | O | string(50) | The descriptor for the transaction | payhere.com |
three_ds | O | object | Information required for 3D Secure payments | |
three_ds: force | O | boolean | Flag whether to send user for 3DS Flow | FALSE |
three_ds: attempt_non_secure | O | boolean | Determines whether to attempt a 3D Secure payment as non-3D Secure should the card issuer not be enrolled | FALSE |
customer | M | object | Details of the customer to associate with the source | |
customer: user_id | M | string(100) | The identifier of an existing customer | cuid_y343t4mf46fdzuxjbcn2giaqnb44 |
customer: email | M | string(100) | An optional email address to associate with the customer | user@solidgate.us |
customer: ip_address | M | string(50) | The IP address used to make the payment. Required for risk checks | 8.8.8.8 |
customer: first_name | O | string(100) | The customer's first name | Chack |
customer: last_name | O | string(100) | The customer's last name. | Blank |
customer: phone_number | O | string(50) | The payment source owner's phone number | +1415 555 2671 |
customer: date_of_birth | O | string(50) | Birthdate in YYYY-MM-DD format. | 2000-11-21 |
customer: ip_country | O | string(3) | ISO-code of the country that was sent in the request | USA |
customer: delivery_address | O | object | The delivery address | |
customer: delivery_address: line1 | O | string(100) | The delivery address line 1 | 15 William St |
customer: delivery_address: line2 | O | string(100) | The delivery address line 2 | |
customer: delivery_address: city | O | string(100) | City of the delivery address | New York |
customer: delivery_address: state | O | string(100) | State of the delivery address | WA |
customer: delivery_address: zip | O | string(10) | ZIP code of the delivery address | 10005 |
customer: delivery_address: country | O | string(3) | ISO country code of the delivery address | USA |
payment_form | O | object | ||
payment_form: language | O | string(2) | Language code of requested Payment form | EN |
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.
Object | Mandatory | Description |
---|---|---|
merchantData | Yes | The main object required to init the form. Contains all the information for creating payment on the SolidGate side. |
formParams | No | An 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. |
styles | No | An 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:
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.
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.
Parameter | Type | Description | Example |
---|---|---|---|
submitButtonText | string | The text on the Submit Button | Pay Now |
isCardHolderVisible | boolean | Visibility of the Card Holder field on the form | 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 SolidGate Payment Form. The list of templates is beloved the table. | default |
isSolidGateLogoVisible | boolean | Visibility of the Powered by SolidGate 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', 'mir'], |
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 |
If you don't want to customize your payment form styles, you could always use the template of the SolidGate Payment Form.
Available templates:
The appearance of the default template is presented below.
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 Classes | Description |
---|---|
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 parameter |
card_cpf | CPF field parameter |
zip_code | ZIP code field parameter |
card_dni | DNI field parameter |
card_pin | PIN field parameter |
card_curp | CURP 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. |
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:
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:
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. |
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.
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 |
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.
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= |
form.update (
{
partialIntent, signature
}
);
Additional Fields is not required fields that could be required to process the payment in some countries.
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.
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.
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.
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.
const form = PaymentFormSdk.init(data);
You could communicate with your SolidGate Payment Form by listening to an event.
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.
Event | Body | Description |
---|---|---|
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. |