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 the Solid Payment Form, you can use our official payment form SDK for different JS frameworks and libraries.  Frameworks usage:

Also, you can use manual installation. 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 CDN, the script could be modified. 

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

The next step is to create the container on your page where the payment form should be. Note that you could pick up your id for the container, as is shown below.

Please, do not set the height of the dimensions (height, width, max-width, max-height) and display (block, inline-block, etc.) any elements inside the container. It may lead to various bugs in form appearance.

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

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

Сontainer ID 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_emailstringNoCustomer email. If no parameter is received, it will be collected automatically on payment formtest@solidgate.com
customer_account_idstringYes, for the subscription workflowCustomer ID in the merchant's system. 4dad42f808
geo_countrystringYes, for Apple- ,  Google PayCustomer country subject to ISO 3166-1 alpha-3 GBR
languagestringNoCustomer language settings for the Solid Payment Form field translation. Available values: uk - Ukrainian, ru - Russian, en - English, fr - French, es - Spanish, pt - Portuguese, ja - Japanese, ar - Arabic, it - Italian, tr - Turkish, pl - Polish, etc.  en
force3dsbooleanNoRouting payments flag for 3DS flow (enabled by Solid account manager) true
settle_intervalinteger NoTime (in hours) when auto-settle should be done. Maximum value is 168 hours.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
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
traffic_sourcestringNoSource of trafficfacebook
 
apple_pay_merchant_namestringNoThe merchant name, which can be displayed to the customers when paying via Apple.Test

Form Request

After completing these steps you need to create a form request object in a new <script> tag on your page (after Solid.js Script). 

This object should contain the following properties:

PropertyMandatoryDescription
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 non-mandatory parameters of the form (f.e. - Cardholder Name, templates). The list of templates is here.
stylesNoAn object that allows you to manage the styles of your payment form.
googlePayButtonParamsNoAn object that allows you to customize the Google Pay button. Learn more.
applePayButtonParamsNoAn object that allows you to customize the Apple Pay button. Learn more.
iframeParamsNoAn object that allows you to customize form container placement and sizes. Learn more.

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: {
    buttonType: 'default' | 'continue', 
    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' 
    }
  }
}

The formParams object allows you to select the Solid Payment Form template. You can also control the text on the Pay button, hold the display of the optional Cardholder Name field, etc.

Parameters that you could modify from the formParams object are below. All of them are optional. 

ParameterTypeDescription Example
buttonTypestringThe parameter allows you to select the type of Payment Button: with 'continue' text or default one with 'pay' text. continue
submitButtonTextstringThe text on the Submit ButtonPay Now
isCardHolderVisiblebooleanVisibility of the Card Holder field on the formtrue
hideCvvNumbersbooleanParameter for hiding the CVV digits. By default - false (numbers are visible). true
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 below 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
enabledbooleanCard form visibility. Set to false to show only Google- Apple-Pay buttons and status page.true
allowSubmitbooleanDetermines, if it’s possible to submit card form using enter keypress on submit button click.true
autoFocusbooleanSetting to disable autofocus, as the payment form will scroll the page to the container when it initializes.true

The iframeParams object allows you to set form width and container id. Parameters are optional.

ParameterTypeDescriptionExample
widthstringOverride width of the form100%
containerIdstringCustom containerId to place formyour-custom-container-id

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. 

Available templates: 

  • card;
  • inline;
  • flat;
  • default.

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
input_groupClass for editing styles of all input fields on the form 
additional_fieldClass for editing styles of all additional fields on the form 
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 
zip_codeZIP code 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.
two-columnsWrapper for CVV and Expiry Date fields in default form template.

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.

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

Using the Solid Payment Form, you could build your user actions tracking by the events that the Solid Payment Form returns.

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

Solid SDK Event Listener Sample

const form = PaymentFormSdk.init(data)

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

The event indicates that Solid SDK displayed the Solid Payment Form, Google-Pay or an Apple-Pay Button inside the iFrame.

Mounted Event Sample

{
	type: 'mounted'
	entity: 'card' | 'google-pay' | 'apple-pay' // one of listed values
}

Submit event

The event indicates that the user submitted the payment. The event could be triggered for one of the variations: Solid Payment Form, Google-Pay or an Apple-Pay.

Submit Event Sample

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

interface SuccessMessage {
   type: 'submit',
   entity: 'card' | 'google-pay' | 'apple-pay' // one of listed values
}

Success event

The event indicates that the payment was successfully processed. 

Success Event Sample

{
	type: 'success'
	entity: 'card' | 'google-pay' | 'apple-pay' // one of listed values
	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 event

The event indicates that the payment had been declined. 

Fail Event Sample

{
	type: 'fail'
	entity: 'card' | 'google-pay' | 'apple-pay' // one of listed values
	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 event

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

Verify Event Sample

{
	type: 'verify'
}

Form Redirect Event

The event informs that the iFrame performs a redirect (to your or Solid status page).

Redirect Event Sample

{
	type: 'formRedirect'
}

Interaction event

The event informs about the current state of the Solid Payment Form and the user's interaction with the controls:

  • istouched - external interaction with the field
  • isvalid - validity check

Interaction Event Sample

{
	type: 'interaction'
	target: {
  	type: 'button' | 'input' // one of the listed
  	name: 'submit' | 'googlePay' | 'applePay' | 'cardNumber' | 'cardCvv' | 'cardExpiry' | 'cardHolder' // It could be one of the listed; furthermore, Solid might extend the list.
   	interaction: 'click' | 'change' | 'focus' | 'blur // one of the lister'
	}
	cardForm: {
  	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 event

The event indicates that the Solid Payment Form was resized. For example, the Solid Payment Form could resize after a validation message appeared.

Resize Event Sample

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

Custom Styles Appended event

The event indicates that your styles had applied to the Solid Payment Form. The event is helpful for cases when you want to draw your preloader over the Solid Payment Form (at this point, you may remove it).

Custom Styles Appended Event Sample

{
	type: 'customStylesAppended'
}

Error event

The event indicates any Solid Payment Form error, including javascript execution errors.

Error Event Sample

{
   type: 'error'
   value: {
      code: string // optional 
      message: string | string[] // optional string or array of strings
   }
}

Card event

The event indicates that the customer has entered a card number and informs about the card brand when the card number is validated.

Card Event Sample

{
   type: 'card'
   card: {
      brand: 'visa' | 'unknown' // string with the card brand name
  }
}

Order status event

The event indicates that the order status was changed during the processing. However, the event may not show all changes before the final order status: approval or decline. All order statuses, transaction statuses and error codes are described here.

Order Status Event Sample

{
	type: 'orderStatus’'
	response: {
		order: { //optional
			amount: number  //optional
			currency: string //optional
			order_id: string //optional
			descriptor: string //optional
			processing_amount: number //optional
			processing_currency: string //optional
			refunded_amount: number //optional
			status: string // Order status 
			subscription_id: string //optional
			marketing_amount: number //optional
			marketing_currency: string //optional
	}
  	transactions:{ [key: string] }: Transaction } // Object containing transactions by key (transaction described below)
	  	transaction:  {
			  descriptor: string // string
			  amount: number
			  card_token: { // string
				   token: string
				 }
				 card: {
    bank: string //optional
    bin: number
    brand: string //optional
    card_exp_month: string
    card_exp_year: number
    card_holder: string //optional
    card_type: string //optional
    country: string //optional
    number: string //optional
    card_token: { //optional
      token: string
    }
  }
  created_at: string
  currency: string
  id: string
  operation: string
  status: string
  updated_at: string
  refund_reason: string //optional
  refund_reason_code: string //optional
  marketing_amount: number //optional
  marketing_currency: string //optional
  finance_fee_amount: string | number //optional
  finance_fee_currency: string | number //optional
  billing_details: { //optional
    address: string //optional
    city: string //optional
    country: string //optional
    state: string //optional
    zip: string //optional
  }
  error: { //optional
    code: string
    message: string
    recommended_message_for_user?: string
  }
  finance: { //optional
    amount: number
    currency: string
    internal: { //optional
      amount: number
      currency: string
    }
    external: { //optional
      amount: number
      currency: string
    }
  }
  	error: { //optional
  		code: string
  		message: string
  		recommended_message_for_user?: string
  	}
  	three_ds: { //optional
    		eci: string
  	}
  	redirect_url: string //optional
  	verify_url: string //optional
}
}

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
afAfrikaans
arArabic
bnBengali
zhChinese
csCzech
daDanish
nlDutch
enEnglish
fiFinnish
frFrench
deGerman
hiHindi
idIndonesian
itItalian
jaJapanese
koKorean
msMalay
noNorwegian
plPolish
ptPortuguese
roRomanian
ruRussian
esSpanish
svSwedish
thThai
trTurkish
ukUkrainian
viVietnamese

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
allowedAuthMethodsarrayThe authentication method of the card transaction.  A card authenticated with the use of a CRYPTOGRAM_3DS or with a PAN_ONLY authMethod. By default both types are available.['PAN_ONLY', 'CRYPTOGRAM_3DS']

Button Styling Code Sample

formParams: { } 
googlePayButtonParams: {
		containerId: 'test-google-button-container-id'
		color: 'white',
	        type: 'plain', 
                allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS']
}

Apple Pay Button on Payment Form

This guide provides step-by-step instructions for enabling Apple Pay on the web with the Solid Payment Form. After completing the following steps, your payment form includes an Apple Pay button.

Solid Payment Form adheres to Apple's development requirements for Apple Pay on the Web. Solid users can accept Apple Pay on the web in Safari, starting with iOS 10 or macOS Sierra.

Displaying an Apple Pay button 

To start processing Apple Pay payments via Solid Payment Form, you must perform a few steps.

First of all, you need to host the domain-verification file at the following path for each domain you’re need to process Apple Pay Payments:

Domain-verification file location

HTTPS://[DOMAIN_NAME]/.well-known/apple-developer-merchantid-domain-association

After placing the domain-verification file on your site, you must verify the domain in HUB. Apple Pay Domain verification is available in the Developers section. Domain verification is available only for websites that Solidgate Team approved for processing payments. 

When the domain is verified, you are ready to display the Apple Pay Button on the Solid Payment Form. You must add the following parameter to the paymentIntent object to display the ApplePay Button.

ParameterTypeMandatoryDescriptionExample
apple_pay_merchant_domainstringYes, for displaying the ApplePay ButtonThe domain, where you placed the domain-verification file.solidgate.com

To indicate that the ApplePay button has been shown, subscribe to the mounted event. When the event is emitted for the apple-pay entity, this means the ApplePay button is fully displayed.

Apple Pay Button Customisation

In addition to displaying the button on the form, you can also control the button's position, color, and type. Use the applePayButtonParams object for changes as you would for all other customisation in a Solid Payment Form.

Button Position

To choose the position to place the Apple 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 applePayButtonParams 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 Apple 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 Apple Pay button to fit your site's style as much as possible.

We allow changing two parameters of the button in the applePayButtonParams object:

  • color with options:
    • black - use on white or light-color backgrounds that provide sufficient contrast. Don't use on black or dark backgrounds.
    • white-outline - use on white or light-color backgrounds that don't provide sufficient contrast. Don't place on dark or saturated backgrounds.
    • white - use on dark-color backgrounds that provide sufficient contrast.
  • type - Apple provides several types of buttons so that you can choose the button type that fits best with the terminology and flow of your purchase or payment experience. More information you could find in the Apple Pay Guidelines.

By default, the Solid Payment Form displays the button with white-outline color and plain type.

Button Hiding

You could always hide the button for the user by passing false to the enabled parameter. You don't need to specify true to display the button on the form - this is the default value. When you pass the false value, it means that the form with the passed parameters of containerId, color and type is collected but not displayed on the Solid Payment Form.

The properties are supported to customize Apple Pay Button:

ParameterTypeDescriptionExample
enabledbooleanThe parameter is responsible for displaying the Apple Pay Button on the Solid Payment Formfalse
containerIdstringThe id of container to place the Apple Pay Button test-apple-button-container-id
colorstringThe color of the Apple Pay Button on the Solid Payment Formwhite
typestringThe type of the Apple Pay Button on the Solid Payment Formplain

Apple Pay Button Styling Code Sample

applePayButtonParams: {
  enabled: false,
  containerId: 'apple-pay-button-container',
  color: 'white-outline',
  type: 'plain'
}

Customize the Apple Payment Sheet

Solid Payment Form gave you access to customize Merchant Name Label on the Apple Payment Sheet. To change the name you need to pass the apple_pay_merchant_name parameter in the paymentIntent object

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, product ID, or one of the other available parameters 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 Solid Payment Form parameter, 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.

Please, note that we are not saving the data from the paymentIntent object if you use the update method. 

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
order_idstringNoOrder ID specified in the merchant system. Order ID must be unique.  84d4-ab065
order_descriptionstringNoOrder description in UTF-8 code.description
order_datestringNoDate of order creation in format YYYY-MM-DD-HH-MM-SS.2022-02-21 11:21:30
order_itemsintegerNoOrder items in UTF-8 codeitem5
order_numberstringNoThe number of payments by the user.4
typestringNoParameter for transaction authorization through a payment formauth
transaction_sourcestringNoSource of transactions on the merchant site.Main menu
traffic_sourcestringNoSource of trafficInstagram

Please note!

If on the initial call of the Solid Payment Form you picked up the non-subscription flow, you can only specify the amount and currency using the refresh method.

After the signature creating, you need to execute the update method in the Solid 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
	}
);

If one of the parameters in the udateIntent request is invalid (f.e. the Order ID will not be unique), you will get a response with an error.

Update Response Sample

{
    "error": {
        "code": "2.01",
        "message": [
            "Order already exists"
        ]
    }
}

Submit Form without Pay Button

Solid leaves the option to display your payment button below the Solid Payment Form. Use this feature to collect additional data from the user on the payment page.

To hide a Solid Pay Button, you need to describe the display property using a formParams object.

Hiding Button Sample

formParams: {
    allowSubmit: false
}

To submit the Solid Payment Form without using a Solid Button, you need to call the form's submit method.

Submit Method Sample

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

Additional Fields on Solid Payment Form

Additional Fields could be required to process the payment in some countries. The solid Payment Form will check the Card BIN and receive a solution to display Additional Fields according to information about the BIN country.  

The list of additional fields and the countries for which they are displayed are presented below.

CountryCountry Code (ISO 3166-1)Additional Field ClassField Title
ArgentinaARGargentina_dniDNI
BangladeshBGDbangladesh_nicNational Identity Card
BoliviaBOLbolivia_ciCedula de Identidad
BrazilBRAbrazil_cpfCPF
CameroonCMRcameroon_cniСNI
ChileCHLchile_ciRol Único Tributario 
ChinaCHNchina_idCitizen ID Number
ColombiaCOLcolombia_ccCedula de Ciudadania
Costa RicaCRIcosta_rica_ciCédula de Identidad
Dominican RepublicDOMdominicana_idIdentity card
EcuadorECUecuador_ciCédula de Identidad
El SalvadorSLVel_salvador_idPersonal Identification Card
EgyptEGYegypt_idIdentity card
GhanaGHAghana_cardGhana Card
GuatemalaGTMguatemala_cuiCUI
IndiaINDindia_panPAN
IndonesiaIDNindonesia_nikNIK
JapanJPNjapan_idMy Number
KenyaKENkenya_idNational ID Card
MalaysiaMYSmalaysia_nricNRIC
MexicoMEXmexico_curpCURP
MoroccoMARmorocco_cnieCNIE
NigeriaNGAnigeria_ninNIN
PanamaPANpanama_idCedula de Identidad
ParaguayPRYparaguay_ciCédula de Identidad
PeruPERperu_dniDNI
PhilippinesPHLphilipines_psnPSN
SenegalSENsenegal_cniCNI or ECOWAS ID Card
South AfricaZAFsouth_africa_idSouth African Identity Card
TanzaniaTZAtanzania_idNational Identity Card
ThailandTHAthailand_idThai Identity Card
TurkeyTURturkey_tc_kimlik_noT.C. Kimlik No.
UgandaUGAuganda_nicNational ID number (NIC)
UruguayURYuriguay_ciCédula de Identidad
VietnamVNMvietnam_vnidVNID
United StatesUSA zip_codeZIP code

Additional fields classes will be formed as follows:

ZIP Code Field Class Sample

 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 fields classes, described in the table above. 

CSS Sample of Custom Styles for Additional Fields at once

styles: {
    additional_field: {
      'input': {
        'color': 'red'
      }
    }
}

If you want to customize a definite field, you need to apply styles to the Additional Field Class name. 

CSS Sample of Custom Styles for Definite Additional Field

styles: {
    guatemala_cui: {
      'input': {
        'color': 'red'
      }
    }
}

Fields Label Customisation

You could customize all labels on the Solid Payment Form. To change the field label you need to pass the parameter fieldNameLabel with the new Label Name to formParams Objects.

The parameters for Card Data Fields are presented below.

Card Data Fields Parameters

cardExpiryDateLabel
cardCvvLabel
cardNumberLabel
cardHolderLabel

To get the value of fieldNameLabel for additional fields, you need to take the Field Class name on the table, remake it into camelcase and add a ‘label’ in the end. 

For example, bolivia_ci move to boliviaCiLabel and argentina_dni moves to argentinaDniLabel.

Label Customisation Sample

formParams: {
    cardExpiryDateLabel: 'Expiration Date', 
    boliviaCiLabel: 'CI'
}