Payment form insights

Additional information about the payment form

Solidgate Payment Form is designed for seamless interaction, providing extensive customization and validation features. It dynamically adapts to different card information, supports multiple languages, and ensures compatibility with the latest secure browser versions, providing a smooth and secure payment experience for customers.

First payment flow

Initiating a transaction involves using the paymentIntent object within the Payment Form. This process is the first step in the payment flow, setting the groundwork for a seamless transaction. A series of background steps encompass checks and validations for efficient and secure payment processing. For instance, to prevent double charging for payments, the system ensures each payment form handles just one transaction, regardless of the number of times customers click the payment button.

Validation rules

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

Validation of form fields occurs when a field loses focus.

Card number

Validate the data entered
The validity of the card number is ensured through the Luhn Algorithm Reference for card brands supporting it. The Luhn Algorithm calculates the check digits of a card number following the ISO/IEC 7812 WIKI standard.
Define card brand to display the desired logo
For an enhanced user experience in card payments, it is essential to automatically detect the card type and format the card number with appropriate spacing patterns. Implementing this requires identifying the IIN ranges and applying the spacing rules for each card type.
Determine the country of the card by BIN and add fields dynamically if necessary
To dynamically add relevant fields to the payment form, it is necessary to determine the country associated with the card brand. Based on this information, the required additional fields can be dynamically rendered on the front end so the user can provide any missing data specific to their card or location.

Form template: default	Form template: flat	Form template: card

Form template: inline

Cardholder

The cardholder’s name field is disabled by default but can be enabled through CSS styles.

Rules for the card_holder field are as follows:
- Data entered must have at least 3 characters
- Input is automatically converted from Cyrillic to Latin
- Symbols and numbers are stripped from input, keeping only letters

The card_holder field is specifically required for transactions from certain countries.

Those countries include Argentina ARG, Bangladesh BGD, Bolivia BOL, Brazil BRA, Cameroon CMR, Chile CHL, China CHN, Colombia COL, Costa Rica CRI, Dominican Republic DOM, Ecuador ECU, Egypt EGY, El Salvador SLV, Ghana GHA, Guatemala GTM, India IND, Indonesia IDN, Japan JPN, Kenya KEN, Malaysia MYS, Mexico MEX, Morocco MAR, Nigeria NGA, Panama PAN, Paraguay PRY, Peru PER, Philippines PHL, Senegal SEN, South Africa ZAF, Tanzania TZA, Thailand THA, Turkey TUR, Uganda UGA, Uruguay URY, and Vietnam VNM.

Expiry date

The expiration date:

Must be provided in the MM/YY or MM/YYYY format
Must represent a date in the future, not a past date

CVV

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

AMERICAN EXPRESS card requires 4 digits for the CVV field
All other card brands require 3 digits for the CVV field

Once the payment data is validated, the payment processing unfolds. Merchants can then receive notifications about the order status and inform customers about the outcome of their payments.

Order status updates

Merchants receive notifications for any changes in the status of their orders. Continuous order status tracking is handled by Guide
Subscribe for events on your Solidgate account so your integration can automatically trigger actions. webhooks that serve as destinations for these notifications.

Status requests
Merchants can choose to receive the current status Webhook of an order, ensuring flexibility in monitoring transaction progress.
Event listening
The Guide
Form events are essential checkpoints for monitoring user interactions in payments. events allow merchants to promptly respond to changes in the Payment Form state, enabling real-time communication and response to various form events.

Transaction status communication

Payment Form allows customers to be immediately redirected to designated pages, indicating successful or unsuccessful transactions through the use of success_url and fail_url parameters.

Unsuccessful
In case of unsuccessful transactions, it is crucial to inform customers about the status and provide clear explanations for the decline. This transparency helps maintain customer trust and enables them to take necessary actions.
Successful
For successful transactions, customers should receive prompt and clear confirmation of their successful payment. It is important to include payment details, such as the payment descriptor, which will be reflected on the customer's bank statement, promoting transparency and trust. This descriptor is communicated through notifications and upon request for order status.

Coupons

Solidgate provides the ability to apply discounts to subscription products through two schemas:

Predefined coupon flow
In this flow, the coupon ID is embedded and encrypted in the paymentIntent during payment initialization. Once the form is initialized, the applied discount will already be present.
Direct coupon flow
In this flow, the coupon code is applied after the payment form has been initialized using a special applyCoupon method.

Predefined coupon flow

If you want to apply a discount during form initialization, you can include the coupon_id parameter in the encryption of the paymentIntent, and then call form.init

coupon_id

string

Description

ID of the coupon which corresponds to the specific product discount, must be passed in UUID v4 format.

The coupon flow will only be activated when a product_id is supplied of the subscription workflow.

Without a product_id, the coupon_id will be disregarded.

Example

eb4c6e93-4c53-447a-b215-5d5786af9844

After a successful form initialization, the discount will already be applied. However, in the case of an invalid or expired coupon, you will receive an error event with a InitPaymentError when calling form.init

Direct coupon flow

If you have already initialized the payment form and wish to apply a discount to it, you can do so by calling the applyCoupon method with the specified couponCode string.

1
2
3
4


form
  .applyCoupon("exampleCoupon")
  .then((result: ApplyCouponPrices) => { /* success handlers here */ })
  .catch((error: ApplyCouponError) => { /* error handlers here */ })

If the coupon is valid and was successfully applied, applyCoupon will resolve with ApplyCouponPrices object with schema:

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


interface ApplyCouponPrices {
  productPrice: {  // initial product price
    amount: string;
    currency: string;
    currencyIcon: string;
  };
  discountPrice: { // product price with applied discount
    amount: string;
    currency: string;
    currencyIcon: string;
  };
  trialPrice?: {
    amount: string;
    currency: string;
    currencyIcon: string;
  };
}

If a trial price exists, users are charged at this rate. Future payments may also have the discountPrice applied based on rules established in the HUB. Use data from ApplyCouponPrices to inform users about the original and discounted product prices.

In cases where the coupon application fails due to reasons like an expired coupon code, applyCoupon rejects with an ApplyCouponError, containing error details with a specific code and message within error.details

1
2
3
4
5
6


interface ApplyCouponError extends Error {
  details?: {
    code: string
    message: string
  };
}

ApplyCouponError.details will contain original error with a specific code and message

Additional fields

The Payment Form will check the Card BIN and receive a list of necessary additional fields according to information about the BIN country (the first six 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 india_pan . This parameter typically requires the person to enter their registered mobile phone number, which is then used to authenticate the payment.

Styling additional fields

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'
      }
    }
  }
})

Supported browsers

Our payment form supports the following browsers:

Mobile

Desktop

For browsers not explicitly supported, support is limited as follows:

customer’s browser must support TLS 1.2. If TLS 1.2 is not supported, the payment form will not be displayed
certain browser extensions may interfere with the proper functioning of the payment form
payment form’s stable performance cannot be guaranteed when rendered inside in-app browsers like Facebook, Instagram
browsers must be sufficiently modern, including support for Promises Reference in JavaScript
bug reports are addressed, but proactive testing of other browsers is not conducted

Supported translations

Payment Form is automatically translated based on the customer’s browser language settings. If the browser language is not supported, the form will display in en English.

Languages and language tags
Afrikaans	`af`	Arabic	`ar`	Bengali	`bn`	Bosnian	`bs`
Bulgarian	`bg`	Cantonese	`yue`	Chinese	`zh`	Croatian	`hr`
Czech	`cs`	Danish	`da`	Dutch	`nl`	English	`en`
Estonian	`et`	Filipino	`fil`	Finnish	`fi`	French	`fr`
German	`de`	Greek	`el`	Hebrew	`he`	Hindi	`hi`
Hungarian	`hu`	Indonesian	`id`	Italian	`it`	Japanese	`ja`
Korean	`ko`	Latvian	`lv`	Lithuanian	`lt`	Malay	`ms`
Norwegian	`no`	Polish	`pl`	Portuguese	`pt`	Romanian	`ro`
Serbian	`sr`	Slovak	`sk`	Slovenian	`sl`	Spanish	`es`
Swedish	`sv`	Thai	`th`	Turkish	`tr`	Turkmen	`tk`
Ukrainian	`uk`	Urdu	`ur`	Vietnamese	`vi`	Zulu	`zu`

If you prefer to display the Payment Form in a specific language, pass any IETF WIKI language tag from the above list into the paymentIntent Guide
Begin by setting up your back end, a vital step for successful implementation. object .

Iframe and HTTP limitations

Payment Form is not suitable for embedding on HTTP web pages. Use HTTPS to ensure the secure transmission of sensitive data.

To work in iframe, the Payment Form requires payments to be allowed in iframe:

1

<iframe src="https://your-website.com/payment-form" allow="payment"></iframe>

Specifically, Guide
Optimize your payment form with Apple Pay integration, providing a secure and efficient checkout for Apple device users. Apple Pay requires iframe and top-level domains to be verified via the Solidgate HUB .

Common initialization errors related to third-party when integrating the Solidgate Payment Form SDK are the following:

Feature-Policy violation that arises in third-party iframes without proper permissions.
Apple Pay security origin issue that occurs when starting Apple Pay sessions from a document with a differing security origin than its top-level frame.
Insecure document error that is triggered by attempting Apple Pay transactions on non-HTTPS web pages.

Looking for help? Contact us

Stay informed with Changelog