The Solidgate Payment Form allows for the tokenization of sensitive data, manages 3D Secure authentication, and supports multiple payment methods.

It offers dynamic adaptation to card information, supports multiple languages, and is compatible with secure browser versions.

Integration steps

This guide simplifies the process of adding the Payment Form to your website. It covers the preparation of the backend, SDK installation, API instance creation, and merchant data setup. Furthermore, it outlines the initialization of the form using various JavaScript frameworks and how to customize its appearance through parameters and styles.

Backend setup

Begin by setting up your backend, a crucial step for successful implementation. Use the Solidgate SDK to integrate the Payment Form seamlessly into your platforms. This SDK offers intuitive features for transactions and payment form customization. To initiate a charge, supply transaction-specific information through paymentIntent object fields.

chevron down chevron up paymentIntent object Expand all chevron down chevron up order_id string 255 Required

Description

Order ID, which must be unique, is specified in the merchant system.

Example

123456

chevron down chevron up product_id string 36 Required*

Description

Identifier of the predefined product must be passed in UUID v4 format.

Should be provided one of product_id or product_price_id for subscription flow.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

chevron down chevron up product_price_id string 36 Required*

Description

Price ID of the predefined product.

To get product_price_id, use get product prices.

Should be provided one of product_id or product_price_id for subscription flow.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

chevron down chevron up coupon_id string 36

Description

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

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

Without a product_id, the coupon_id is disregarded.

Example

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

chevron down chevron up customer_account_id string 100 Required*

Description

Customer ID in the merchant’s system.

Required, for the subscription workflow.

Example

4dad42f878

chevron down chevron up amount integer >=0 Required*

Description

Order amount - integer without fractional component like cents. For instance, 1020 means 10 USD and 20 cents.

However, amount can be 0, for zero-amount authorization flow.


Required, for one-time payment workflow.

Example

1020

chevron down chevron up currency string 3 Required*

Description

Currency amount is represented in a three-letter currency code as per the ISO-4217 Wiki standard.

Required, for one-time payment workflow.

Example

USD

chevron down chevron up future_usage object

Description

Defines the usage of stored payment credentials.

Should be provided for Bizum or Cash App Pay button.

chevron down chevron up payment_type string Required

Description

Type of the token usage scenario.

  • one-time no token created, for one-off use
chevron down chevron up order_description string 255 Required

Description

Order description in your system and for bank processing.

Highly recommended to keep the description brief to improve the clarity of payment processing, ideally not exceeding 100 characters.

Example

Premium package

chevron down chevron up order_items string 255

Description

Order items in UTF-8 code.

Example

item1, item2

chevron down chevron up order_date string 50

Description

Date of order creation in format YYYY-MM-DD-HH-MM-SS.

Example

2024-12-21 11:21:30

chevron down chevron up order_number integer

Description

Number of payments by the customer.

Example

1

chevron down chevron up type string Required

Description

Specifies the payment processing flow using auth for a two-step payment.

Should be provided together with settle_interval parameter.

Example


auth

chevron down chevron up settle_interval integer [0..240]

Description

Delay before transaction settlement in hours:

  • Visa customer-initiated payments: 240 hours = 10 days
  • Visa merchant-initiated payments: 120 hours = 5 days
  • All other card brands: 144 hours = 6 days

PSP limits:

  • Stripe: 113 hours
  • Ebanx: 95 hours
  • Razorpay: 72 hours
  • Braintree: 72 hours

Required if type auth is provided.

Example

48

chevron down chevron up retry_attempt integer >=0

Description

Number of retry payment.

Should be provided for the subscription workflow.

Example

1

chevron down chevron up force3ds boolean

Description

Routing payments flag for 3DS flow.

Example

true

chevron down chevron up google_pay_merchant_id string 100

Description

Merchant ID parameter you receive on Google’s side.

Required for displaying the Google Pay button.

Example

10911390523550288022

chevron down chevron up google_pay_merchant_name string 255

Description

Merchant name, which can be displayed to the customers when paying via Google.

It would be better to pass this parameter so that Google does not substitute it on its own.

Example

Solidgate

chevron down chevron up apple_pay_merchant_name string 64

Description

Merchant name, which can be displayed to the customers when paying via Apple.

Example

Test

chevron down chevron up customer_date_of_birth string <=10

Description

Customer birthdate in format YYYY-MM-DD.

Example

2000-11-21

chevron down chevron up customer_email string 100

Description

Customer email.

If not provided, it is collected on the payment form.

For PayPal, an autogenerated email may initialize the order, which customer enters while logging into their PayPal account.

Example

test@solidgate.com

chevron down chevron up customer_first_name string 100

Description

Customer first name.

Example

John

chevron down chevron up customer_last_name string 100

Description

Customer last name.

Example

Snow

chevron down chevron up customer_phone string 50

Description

Customer’s phone number.

Example

12120001111

chevron down chevron up ip_address string 50

Description

Public IP address of the customer. Both IPv4 and IPv6 are supported.

Private IPs (10.0.0.0-10.255.255.255, 172.16.0.0-172.31.255.255) result in an ‘Invalid IP’ error.

Example

8.8.8.8

chevron down chevron up traffic_source string 255

Description

Source of traffic.

Example

facebook

chevron down chevron up transaction_source string 255

Description

Source of transactions on the merchant site.

Example

main_menu

chevron down chevron up purchase_country string 3

Description

Country where the goods are purchased or where the seller is based is identified using the ISO-3166 Wiki alpha-3 country code.

Required if you are registered with international payment systems as a marketplace. Being registered as a marketplace, in the context of international payment systems, typically implies that you operate a platform where numerous sellers can offer their goods or services.

Example

CHN

chevron down chevron up geo_country string 3

Description

Customer country subject to ISO-3166 Wiki alpha-3.

If this parameter is not provided, it is automatically inferred.

In cases where it fails to provide this information, Apple and Google Pay methods are not displayed.

Example

GBR

chevron down chevron up geo_city string 100

Description

Customer city.

Example

New Castle

chevron down chevron up billing_address object

Description

Billing address details.

chevron down chevron up address string 100

Description

First and second line of the billing address.

Example

221B Baker Street

chevron down chevron up country string 3

Description

ISO-3166 Wiki country code of the billing address.

Example

USA

chevron down chevron up state string 10

Description

ISO 3166-2 Wiki address state code of the billing address.

Example

US-NY

chevron down chevron up city string 100

Description

City name associated with the billing address.

Example

Brooklyn

chevron down chevron up zip_code string 10

Description

Address zip/postal code.

If the field is provided, manual entry is not required for it.

Example

11201

chevron down chevron up language string [2..3]

Description

Customer language settings for the translation of Payment Form fields and the language of email receipts sent for successful payments.

Example

en

chevron down chevron up website string 255

Description

Website from which transaction took place.

Example

https://google.com

chevron down chevron up device string 50

Description

Device of customer.

Example

iPhone 8 iOS 12.0

chevron down chevron up device_sessions array of objects

Description

Device sessions containing the unique session ID of the device and the associated third-party provider.

chevron down chevron up id string 255

Description

Unique session identifier generated by the application.

Parameter for tracking customer sessions in payments and for risk analytics. Ensure that you handle this field in compliance with regional data privacy regulations (for example, GDPR Reference in the EU).

Example

dsid_3a20_f9c1_4cd8_89d3_1c5

chevron down chevron up provider string 255

Description

Specifies the third-party provider associated with the device session.

Identifies the integration type for the merchant, allowing multiple such integrations if needed.

Example

checkout

chevron down chevron up platform string 3

Description

Customer platform at the moment of payment.

  • WEB - desktop
  • MOB - mobile version
  • APP - application

If this parameter is not provided, it is automatically inferred from the header.

Example

WEB

chevron down chevron up user_agent string 1000

Description

User-agent of the customer.

Example

Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (HTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36

chevron down chevron up order_metadata object

Description

Metadata is useful for storing additional, structured information about an object, consisting of up to 10 key-value pairs with a validation limit of 380 characters per field.

The callback notification returns an order_metadata from the order in each state.

Example

“coupon_code”: “NY2024", “partner_id”: “123989"

chevron down chevron up success_url string 255

Description

Provide this URL if you want to redirect a customer to your own Success Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Success Screen.

Example

https://merchant.example/success

chevron down chevron up fail_url string 255

Description

Provide this URL if you want to redirect a customer to your own Fail Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Fail Screen.

Example

https://merchant.example/fail

chevron down chevron up fraudulent boolean

Description

A customer was detected on the merchant end to be a suspicious one.

⚠️ This field is deprecated and should not be used in new implementations.

Example

true

With SDK

Step 1. Install SDK

Install the Solidgate SDK in your environment:

Step 2. Create SDK instance

To interact with the Solidgate API, create an API instance by calling the API constructor function, passing your Public public_key and Secret secret_key keys as arguments.

Step 3. Form intent data

To create a charge, you must provide transaction-related information. This information is contained in a FormInitDTO object, which is created by invoking the formMerchantData function on your API instance. In the example code, this function is called with the paymentIntent object fields.

Step 4. Pass generated data to frontend

After you have set up the FormInitDTO and turned it into a simple object, you can effortlessly integrate it into your frontend code by transmitting the paymentIntent encrypted String (during form initialization).

Without SDK

An alternative option for integrating the payment form exists without using the Solidgate SDK.

  1. Prepare server-side code in your preferred programming language and libraries to communicate with the Solidgate API.
  2. Create and encrypt a JSON object with the required fields for a payment transaction.
  3. Once the paymentIntent is encrypted, pass it to the frontend for further processing, such as form initialization.
  4. Integrate the signature parameter process with the encryption steps for initializing the form, the flow for paymentIntent encrypted String
    • The customer starts the transaction by providing the necessary payment data.
    • A secure random IV is created with the required size for encryption.
    • The system extracts the required size from the secret key and formats it for encryption.
    • A cipher object is set up with the selected encryption algorithm, mode, and padding, and initialized with the key and IV for encryption.
    • The input data is converted into bytes and encrypted using the initialized cipher.
    • The IV and encrypted data become combined into a single byte array for secure transmission, ensuring compatibility and security, such as using the pycryptodome Reference library in Python 3 environments.
    • The combined IV and encrypted data become encoded into a Base64 string for safe transmission over the network.

Frontend SDK setup

The Solidgate SDK provides a pre-built interface component for payments. It assists in tokenizing customer data, ensuring that card information never interacts with the merchant’s website.

When starting with the Payment Form, you can use Solidgate official payment form SDK wrapper for different JavaScript frameworks:

These integrations automatically load solid-form.js and offer a convenient interface for form operation. 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. Use the Solidgate CDN-hosted form for easy integration, ensuring the latest version and preventing potential issues from script modification.

<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 it a custom ID, as demonstrated below. Avoid setting height or display properties for elements inside the container, including the container itself, to prevent form appearance issues due to CSS conflicts.

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

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

Alternatively, use your own container, passing its id to iframeParams as shown in the example below.

Form initialization

After completing all the steps and modifying the required parameters, initiate the Solidgate SDK

Object data (or InitConfig interface in case of frameworks usage) should contain the:

chevron down chevron up following properties Expand all chevron down chevron up merchantData object Required

Description

Main object required to init the form.

Contains all the information for creating payment on Solidgate side.

chevron down chevron up merchant string Required

Description

Unique merchant identification.

Shall be shared at the moment of registration.

Example

api_pk_7b197...ba108f842

chevron down chevron up signature string Required

Description

Signature of request.

It allows verifying whether the request from the merchant is genuine on the payment gateway server.

Example

MjNiYjVj…ZhYmMxMzNiZDY=

chevron down chevron up paymentIntent string Required

Description

Encrypted aes-cbc-256 string of JSON request data with random IV (16bytes) and secret key is first 32bytes of merchant secret key.

Example

E5FKjxw5vRjjIZ….vmG2YFjg5xcvuedQ==

chevron down chevron up formParams object

Description

Control non-mandatory parameters of the form (f.e. - Cardholder Name, templates).

chevron down chevron up buttonType string

Description

Type of payment button: with continue text or default one with pay text.

Example

continue

Default

pay

chevron down chevron up submitButtonText string

Description

Override the default text of the submit button.

Example

Pay Now

Default

not set chevron down chevron up isCardHolderVisible boolean

Description

Defines should cardholder field be always visible.

Otherwise, it could be shown simultaneously during additional fields request.

Example

true

Default

false

chevron down chevron up hideCvvNumbers boolean

Description

Mask cvv number as *** during input.

Example

true

Default

false

chevron down chevron up headerText string

Description

Text on the header of the payment form.

Example

Enter your payment data

Default

not set chevron down chevron up titleText string

Description

Text on the title of the payment form.

Example

Card info

Default

not set chevron down chevron up formTypeClass string

Description

Template of Payment Form.

  • default
  • card
  • inline
  • flat

Example

card

Default

default

chevron down chevron up isSolidLogoVisible boolean

Description

Visibility of the Powered by Solidgate logo.

Example

true

Default

false

chevron down chevron up cardBrands array

Description

An array with a list of card brands that could be displayed on the payment form.

  • american-express
  • aura
  • bajaj
  • bancontact
  • bc-card
  • cartes-bancaires
  • dankort
  • diners-club
  • discover
  • elo
  • gpn-card
  • hipercard
  • interac
  • jcb
  • maestro
  • mada
  • mastercard
  • paypal
  • rupay
  • thai-payment-network
  • troy
  • unionpay
  • verve
  • visa

Example

['american-express','diners-club','discover','maestro', 'mastercard', 'paypal','visa']

Default

[]

chevron down chevron up secureBrands array

Description

An array with a list of card brands that could be displayed on the payment form.

Example

['visa-secure', 'mcc-id-check', 'ssl', 'pci-dss', 'norton', 'mc-affee']

Default

[]

chevron down chevron up googleFontLink string

Description

Link to Google Font.

Please, avoid using large font sets to keep form loading fast.

Example

//fonts.googleapis.com/css2?family=Roboto:wght@400;500&display=swap

Default

not set chevron down chevron up enabled boolean

Description

Card form visibility.

Set false to show only Google/Apple Pay buttons and status page.

Example

false

Default

true

chevron down chevron up allowSubmit boolean

Description

Determines, if it is possible to submit card form using enter key press or submit button click.

Usefully for implementing custom submit flow.

Example

false

Default

true

chevron down chevron up autoFocus boolean

Description

Setting to disable form autofocus.

Example

false

Default

true

chevron down chevron up styles object

Description

Manage the styles of your payment form.

chevron down chevron up input_group

This class targets all input fields within the form, enabling you to apply consistent styling.

To view changes, directly modify the input_group class in your CSS. Activation occurs automatically as the form renders.

chevron down chevron up header

Defines the style for the payment form’s header.

Adjustments to the header class become visible upon form load and are particularly useful for aligning with your brand identity.

chevron down chevron up form_body

Responsible for the overall container of the form, allowing for adjustments in font, color, or spacing.

The form_body becomes visible when the form is initialized and can be tailored to fit seamlessly within your site’s design.

chevron down chevron up form_title

Customize the subtitle of your payment form, enhancing readability and focus.

Changes are immediately visible, providing a quick way to align form instructions with customer expectations.

chevron down chevron up submit_button

Controls the styling of the form’s submit button.

To hide the button, set the display property to none in your styles. This class becomes crucial when you prefer a custom button or need to follow the specific design systems.

chevron down chevron up two_columns

Wraps fields like CVV and Expiry Date in the default form template, enabling a two-column layout for a compact and organized look.

Alterations to this class are seen as soon as the form is rendered.

chevron down chevron up card_view

Edit the card template, such as changing the background color with a property like card_view: { 'background': '#3D4251'}.

This class is particularly impactful for branding purposes and customer engagement.

chevron down chevron up card_brands

Modifies the display of card brand logos, ensuring they fit well within your form’s design.

The size and position can be adjusted to meet visual design standards.

chevron down chevron up card_number
Specific to the card number input field, this class can be styled to indicate valid input or errors, with immediate feedback enhancing the customer’s experience. chevron down chevron up card_cvv
Targets the CVV field, allowing for distinct styles during error states or focus, providing immediate visual cues to the customer. chevron down chevron up expiry_date

Controls the appearance of the expiry date field.

Customizing this field can ensure consistency with other form elements and can trigger when the field is in focus or an error state.

chevron down chevron up card_holder

Description

Defines the style for the cardholder’s name field, which is a crucial element for transactions.

A string parameter ranging from 3 to 50 characters. The pattern ^[a-zA-Z]+ [a-zA-Z]+(?: [a-zA-Z]+)*$ is used to validate the format.

The field specifies the name as it appears on the card, essential for transaction processing. It requires at least one space between the first and last names to ensure accuracy and enhance transaction conversions. chevron down chevron up additional_field
Manages the styling of any additional fields that may be required for specific transactions. This ensures that these fields are visible and styled according to the form’s design when they become relevant. chevron down chevron up zip_code
Styling for the ZIP code field is important in address forms, and any updates to this class appear as soon as the field is rendered. chevron down chevron up body_errors

Customize the error messages associated with the card and flat templates, ensuring that any validation errors are communicated effectively and clearly.

The errors customization for card and flat template. chevron down chevron up secure_info
Edits the appearance of security-related branding, such as SSL certificates or payment compliance logos, reinforcing trust and security on the payment form. chevron down chevron up googlePayButtonParams object

Description

Customize the Google Pay button.

chevron down chevron up enabled boolean

Description

Displays the Google Pay button.

Example

false

Default

true

chevron down chevron up containerId string

Description

Identifier of container to place the Google Pay button.

By default, if not set, button is displayed above the form.

Example

yourCustomContainerId

Default

not set chevron down chevron up color string

Description

Color of the Google Pay button.

Supported colors:

  • default A Google-selected default value. Currently black but it may change over time.
  • black A black button suitable for use on white or light backgrounds.
  • white A white button suitable for use on colorful backgrounds.

Example

white

Default

black

chevron down chevron up type string

Description

Type of the Google Pay button.

Supported types:

  • buy
  • checkout
  • order
  • pay
  • plain
  • subscribe

Not supported types:

  • donate
  • book

Example

plain

Default

not set chevron down chevron up allowedAuthMethods array

Description

Authentication method of the card transaction.

  • PAN_ONLY: This authentication method is associated with payment cards stored on file with the customer’s Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year.
  • CRYPTOGRAM_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3D Secure (3DS) cryptogram generated on the device.

The capability to transmit only PAN_ONLY or CRYPTOGRAM_3DS is also available, and such transmission work for both one-time payments and subscriptions.

Example

['PAN_ONLY']

Default

['PAN_ONLY', 'CRYPTOGRAM_3DS']

chevron down chevron up applePayButtonParams object

Description

Customize the Apple Pay button.

chevron down chevron up enabled boolean

Description

Displays the Apple Pay button.

Example

false

Default

true

chevron down chevron up integrationType string

Description

Defines the type of Apple Pay button integration.

In Safari browsers, both css and js integration types are supported. In non-Safari browsers, Apple Pay can only be displayed when using the js integration type, which enables QR code scanning with iOS 18 or later.

Example

js

Default

css

chevron down chevron up containerId string

Description

Identifier of container to place the Apple Pay button.

By default, if not set, button is displayed above the form.

Example

yourCustomContainerId

Default

not set chevron down chevron up color string

Description

Color of the Apple Pay button.

Supported colors:

  • white-outline
  • black
  • white

Example

white-outline

Default

black

chevron down chevron up type string

Description

Type of the Apple Pay button.

Supported types:

  • check-out
  • add-money
  • buy
  • order
  • plain
  • reload
  • set-up
  • subscribe
  • top-up
  • continue
  • pay

Not supported types:

  • donate
  • support
  • rent
  • contribute
  • tip

Example

check-out

Default

plain

chevron down chevron up paypalButtonParams object

Description

Customizes form container placement and sizes.

chevron down chevron up enabled boolean

Description

Displays the PayPal button.

If you do not pass this field with true, the PayPal button is hidden.

Example

true

Default

false

chevron down chevron up containerId string

Description

Identifier of the container where the PayPal button is placed.

Example

paypal-button-container

Default

Button is displayed above the form.

chevron down chevron up color string

Description

Color Reference of the PayPal button.
  • gold
  • blue
  • silver
  • black

Example

blue

Default

gold

chevron down chevron up shape string

Description

Shape Reference of the PayPal button.
  • pill
  • rect
  • sharp

Example

sharp

Default

rect

chevron down chevron up label string

Description

Label Reference displayed on the PayPal button.
  • paypal
  • checkout
  • buynow
  • pay

Example

checkout

Default

paypal

chevron down chevron up height string

Description

Height Reference of the PayPal button.

Accepts a value in the range of 25 to 55.

Example

52

Default

Button adapts to the size of its container element.

chevron down chevron up pixButtonParams object

Description

Controls the display and placement of the Smart Pix button.

chevron down chevron up enabled boolean

Description

Displays the SmartPix button.

If you do not pass this field with true, the SmartPix button is hidden.

Example

true

Default

false

chevron down chevron up containerId string

Description

Identifier of the container where the SmartPix button is placed.

Example

pix-button-container

Default

Button is displayed above the form.

chevron down chevron up iframeParams object

Description

Customize form container placement and sizes.

chevron down chevron up width string

Description

Parameter allows the overriding of the form width. You can set the value in either percentage, such as 100%, or pixels, like 320px.

Example

100%

Default

not set

Depending on form template:

  • default: 300px
  • card: 352px
  • inline: 300px
  • flat: 320px
chevron down chevron up containerId string

Description

Custom containerId to place form.

If not set, it is displayed in element with id solid-payment-form-container

Example

your-custom-container-id

Default

not set

Form cleanup

You can use form.destroy() to clean up the form instance fully. This method ensures that all associated resources are properly destroyed, including cleaning up the DOM tree and removing any residual event listeners or states that may persist.

this.form.destroy()

Handle initialization errors

There might be errors when setting up the Payment Form and if you encounter them:

  • Verify that paymentIntent contains the required parameters.
  • Confirm that the ip_address added is not private.
  • Verify that the ip_address added matches the selected region if using a VPN.
  • Ensure that the form styles do not have the opacity property set to 0 .
  • Inspect form styles for any elements that could be covering the form area.
  • Ensure that you generate a new order_id for each transaction attempt.

You can test payments to make sure everything works as expected. If the outlined steps do not resolve the issue, please contact the Solidgate support team for further assistance. When contacting, share the details of the issue and the steps you have taken to resolve it.


Form update

There is no need to call the payment form repeatedly when using multiple tariffs. Request the form once and modify the amount , currency , product_id , or any parameter of the partialIntent object using the form instance’s update method.

To update a Payment Form parameter, generate the signature parameter on your backend. This signature verifies the merchant’s request authenticity on the payment gateway server and originates from the partialIntent encrypted String

Backend setup

Firstly, ensure that the backend is prepared. In the example code, the formMerchantData function is called with fields.

Specifically, this method allows updates only to a predefined list of fields, distinct from those available during initial form creation in the paymentIntent object. Updates are limited to select parameters within the partialIntent object.

It is important to note that attempting to update fields not defined in the allowed list result in an error response. chevron down chevron up partialIntent object Expand all chevron down chevron up product_id string 36 Required*

Description

Identifier of the predefined product must be passed in UUID v4 format.

Should be provided one of product_id or product_price_id for subscription flow.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

chevron down chevron up product_price_id string 36 Required*

Description

Price ID of the predefined product.

To get product_price_id, use get product prices.

Should be provided one of product_id or product_price_id for subscription flow.

Example

faf3b86a-1fe6-4ae5-84d4-ab0651d75db2

chevron down chevron up customer_account_id string 100 Required*

Description

Customer ID in the merchant’s system.

Required, for the subscription workflow.

Example

4dad42f878

chevron down chevron up amount integer >=0 Required*

Description

Order amount - integer without fractional component like cents. For instance, 1020 means 10 USD and 20 cents.

However, amount can be 0, for zero-amount authorization flow.


Required, for one-time payment workflow.

Example

1020

chevron down chevron up currency string 3 Required*

Description

Currency amount is represented in a three-letter currency code as per the ISO-4217 Wiki standard.

Required, for one-time payment workflow.

Example

USD

chevron down chevron up order_description string 255

Description

Order description in your system and for bank processing.

Highly recommended to keep the description brief to improve the clarity of payment processing, ideally not exceeding 100 characters.

Example

Premium package

chevron down chevron up order_items string 255

Description

Order items in UTF-8 code.

Example

item1, item2

chevron down chevron up order_date string 50

Description

Date of order creation in format YYYY-MM-DD-HH-MM-SS.

Example

2024-12-21 11:21:30

chevron down chevron up order_number integer

Description

Number of payments by the customer.

Example

1

chevron down chevron up settle_interval integer [0..240]

Description

Delay before transaction settlement in hours:

  • Visa customer-initiated payments: 240 hours = 10 days
  • Visa merchant-initiated payments: 120 hours = 5 days
  • All other card brands: 144 hours = 6 days

PSP limits:

  • Stripe: 113 hours
  • Ebanx: 95 hours
  • Razorpay: 72 hours
  • Braintree: 72 hours

Example

48

chevron down chevron up force3ds boolean

Description

Routing payments flag for 3DS flow.

Example

true

chevron down chevron up customer_email string 100

Description

Customer email.

If email on the initialization payment form was:

  • non-empty, you cannot change it to an empty email
  • non-empty, and you provide a new email, the new value is passed
  • empty and you provide a new email, the form uses that email as a prefilled value The customer has the option to change it or to confirm it by submission.

Example

test@solidgate.com

chevron down chevron up traffic_source string 255

Description

Source of traffic.

Example

facebook

chevron down chevron up transaction_source string 255

Description

Source of transactions on the merchant site.

Example

main_menu

chevron down chevron up order_metadata object

Description

Metadata is useful for storing additional, structured information about an object, consisting of up to 10 key-value pairs with a validation limit of 380 characters per field.

The callback notification returns an order_metadata from the order in each state.

Example

“coupon_code”: “NY2024", “partner_id”: “123989"

chevron down chevron up success_url string 255

Description

Provide this URL if you want to redirect a customer to your own Success Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Success Screen.

Example

http://merchant.example/success

chevron down chevron up fail_url string 255

Description

Provide this URL if you want to redirect a customer to your own Fail Screen.

If you do not provide the URL, Solidgate directs customers to the Solidgate Fail Screen.

Example

http://merchant.example/fail

Step 1. Form partial intent data

For updating, provide transaction-related information. This information resides in a FormUpdateDTO object, created by invoking the formUpdate function on your API instance.

Step 2. Pass generated data to frontend

The FormUpdateDTO object, returned by the FormUpdateDTO function, is a class instance. Convert it to a plain object for use in frontend code. This conversion is accomplished by calling the toObject function on the FormUpdateDTO object, resulting in a plain JavaScript object.

After forming the merchant data and converting it to a plain object, use it in frontend code to update with the partialIntent encrypted String

Partial form update

chevron down chevron up Update method parameters Expand all chevron down chevron up partialIntent string

Description

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

Example

E5FKjxw5vRjjIZ....vmG2YFjg5xcvuedQ==

chevron down chevron up 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=

It is very important to handle possible errors, including network errors, in callbackForFailedUpdate by calling a valid update or init. Otherwise, the form remains unresponsive.

If an invalid parameter exists in the updateIntent request, such as a non-unique product_id, an error occurs.