Embedded Custom Checkout

Embedded Custom Checkout lets merchants directly integrate a customized payment page into their websites. Using HTML and CSS, merchants can design the payment page to match their brand's visual identity and deliver a seamless checkout experience.

The Embedded Custom Checkout solution creates a smooth, personalized payment experience without redirecting customers to external pages. It simplifies the checkout process, increasing conversion rates and enhancing customer satisfaction. Merchants control the design and functionality of the payment page, aligning it with their brand identity and specific business needs.

How to Use the Embedded Custom Checkout

To add the Embedded Custom Checkout to your page, you must import the JavaScript SDK and CSS files into your HTML project.

JavaScript SDK: https://pay.fondy.eu/latest/checkout.js
CSS: https://pay.fondy.eu/latest/checkout.css

The following code block presents an example of adding these settings to your project:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Fondy Integration</title>
    
    <!-- Import Fondy CSS -->
    <link rel="stylesheet" href="https://pay.fondy.eu/latest/checkout.css">
</head>
<body>
    
    <!-- Your Content Here -->
    <div id="payment-container"></div>

    <!-- Import Fondy JavaScript SDK -->
    <script src="https://pay.fondy.eu/latest/checkout.js"></script>

</body>
</html>

After including the JavaScript SDK and CSS files, you need to set the customizations you will use with the Embedded Custom Checkout. These customizations are defined through a JSON file as displayed in the following code block:

{
  options: {},
  regular: {},
  recurring: {},
  params: {},
  messages: {},
  validate: {}
}

Each of the available objects that define the Embedded Custom Checkout behavior are described in the following sections:

options
regular
recurring
params
messages
validate

The following code block presents an example of the configuration of the Embedded Custom Checkout.

var Options = {
	options: {
		methods: ['card', 'banklinks_eu','wallets'],
		cardIcons: ['mastercard', 'visa'],
		active_tab: 'card',
		default_country: 'PL',
		countries: ["PL","IE","GB","CZ","GE"],
		fields: false,
		title: 'my_title',
		link: 'https://shop.com',
		fullScreen: true,
		button: true,
		locales: ['fr','en','cs','sk'],
		email: true,
		tooltip: true,
		fee: true,
	},
	params: {
		merchant_id: 1396424,
		required_rectoken: 'y',
		currency: 'USD',
		amount: 500,
		order_desc: 'my_order_desc',
		response_url: 'http://shop.com/thankyoupage',
		email: '',
		lang: 'en'
	},
	messages: {
		pl: {
			card_number: 'Numer karty',
			my_title: 'Cel płatności',
			my_order_desc: 'Płatność testowa'
		},
		en: {
			card_number: 'Card number',
			my_title: 'Order description',
			my_order_desc: 'Test order'
		}
	}
}

As the last step, to display the checkout for your customer, you need to call the fondy(<html-component>, <options>) informing the HTML where the checkout should be rendered and the configuration options:

fondy("#app", Options);

Configure the Embedded Custom Checkout

The following sections list and describe the available configurations you can set with the Embedded Custom Checkout:

options
regular
recurring
params
messages
validate

`options`

The available configurations for the options object are listed and described in the following table.

Parameter name	Parameter type	Default value	Description
`methods`	Array	[‘`card`’, `banklinks_eu`,`wallets`]	Enable payment methods for checkout: cards, internet banking, Google Pay, Apple Pay, and local payment options. Supported values include: - `card`: Bank cards - `banklinks_eu`: Internet banking and local payment options (e.g., iDEAL, Giropay, MyBank, Blick) - `wallets`: Google Pay and Apple Pay - `local_methods`: Local country methods, such as GiroPay, EPS, SafetyPay, Multibanco, MyBank, OXXO, Skrill, iDeal, Blik.
`cardIcons`	Array	[`mastercard`, `visa`]	Specifies the set of payment system logos. Supported values include: - `mastercard` - `visa` - `mir` - `prostir` - `diners-club` - `american-express`
`fields`	Boolean	`false`	Enables additional input fields on the checkout page.
`title`	String
`link`	String
`fullScreen`	Boolean	`true`	Defines whether the checkout form will be placed in a compact area (`false`) or in a full page (`true`).
`button`	Boolean	`true`	Defines whether the default pay button should be shown or will be custom.
`locales`	Array		Lists the available locales for the checkout page. Supported values include: ` - `en` - `pl` - `lv` - `fr` - `cs` - `sk` Support languages
`email`	Boolean	`false`	Defines if email must be provided on the checkout page by the customer.
`tooltip`	Boolean	`true`
`apiDomain`	String	`api.fondy.eu`
`fee`	Boolean	`true`	Client fee.
`css`	String		Supported values: `bootstrap3`, `bootstrap4`, `foundation6`.

`regular`

Enables the subscription option on the checkout page. This allows users to configure recurring payments.

The examples Subscription and Subscription 2 illustrate a use case for the parameters described below.

Parameter name	Parameter type	Default value	Description
`insert`	Boolean	`false`	Enables subscription payments.
`open`	Boolean	`false`	Shows frequency and period options for subscription payments.
`hide`	Boolean	`false`	Make subscription options read-only for customers.
`period`	Array	[`‘day’`, `‘week’`, `‘month’`, `‘year’`]	Subscription period Supported values: `day`, `week`, `month`, `year`.

`recurring`

Defines the subscription parameters, including period, frequency, start date, end date, and regular amount. These parameters configure the recurring payment settings.

Parameter name	Parameter type	Default value	Description
`every`	Integer	`1`	Number of intervals.
`period`	String	`month`	The interval with which a subscription should be charged Supported values: `day`, `week`, `month`, `year`.
`amount`	Integer	`100`	The amount to be charged at the interval specified if it differs from the order amount.
`start_time`	String		Date when the first payment must be charged. Format `YYYY-MM-DD`.
`end_time`	String		Date when subscription must be stopped. Format `YYYY-MM-DD`.

`params`

Defines the order parameters as described.

Parameter Name	Parameter Type	Default Value	Description
`merchant_id`	Integer	`1396424`	The unique identifier assigned to the merchant by Fondy.
`order_desc`	String		Description of the order or transaction.
`amount`	Integer	`100`	Transaction amount in the smallest currency unit (e.g., cents for USD).
`currency`	String		Currency code in ISO 4217 format (e.g., `USD` for U.S. Dollar).
`response_url`	String		URL to which the customer will be redirected after payment completion.
`lang`	String	`en`	Language code for the payment page (e.g., `en` for English).
`required_rectoken`	String		Indicates whether a recurring token is required. Supported values: `Y`, `N`, `y`, `n`.
`verification`	String		Specifies if the transaction is for verification purposes. Supported values: `Y`, `N`, `y`, `n`.
`verification_type`	String		Type of verification to be performed. Supported values: 'amount' (verify by amount), 'code' (verify by code).
`email`	String		Customer's email address. It must be in a valid email format.
`token`	String		Unique token for the transaction, typically 40 characters in length.
`offer`	Boolean	`false`	Indicates whether the transaction is an offer.
`custom`	Object		Custom parameters defined by the merchant. This can be used to pass additional information related to the transaction.

`messages`

Allows you to specify custom messages to use on the checkout page.

{  
  messages: {  
    {en}: {  
      {id}: {value},  
      ...  
    },  
    ...  
  },  
}

`validate`

Defines the localization settings for form validation error messages.

{  
  validate: {  
    {en}: {  
      {id}: {value},  
      ...  
    },  
    ...  
  },  
}

Embedded Custom Checkout Use Cases

The Embedded Custom Checkout solution is versatile and designed to adapt to a wide range of payment scenarios. It addresses all your business needs for receiving payments efficiently. This section highlights various use cases for Embedded Custom Checkout, detailing the configurations used and providing interactive examples for each.

Below, you find a complete list of the available use cases:

Basic Checkout Design
Basic Checkout with Light Background
Basic Checkout with Dark Background
Aditional Merchant Fields
Subscription
Subscription 2
Extended Payment Methods
Handling of Pay-Button Click Event
JavaScript Callbacks
ApplePay and GooglePay Buttons
Order Created on Back-End
Customize Bank Links Payment Method
Using Color Presets

Basic Checkout Design

This is the simplest way to use the Embedded Custom Checkout. This use case sets the checkout page to receive payments from cards and Google Pay.

The following code block displays the configurations used to set the basic checkout:

{
  "options": {
    "methods": ["card"], // Defines the available payment methods (only cards in this case)
    "cardIcons": ["mastercard", "visa", "diners-club", "american-express"], // Displays icons for supported card types (MasterCard, Visa, Diners Club, American Express)
    "fields": false, // Disables additional custom fields in the checkout form
    "title": "my_title", // Sets the title of the checkout form using the "my_title" key from the "messages" object
    "link": "https://shop.com", // URL to the merchant's website
    "fullScreen": true, // Enables a fullscreen display for the checkout interface
    "button": true, // Uses the default payment button from the Embedded Custom Checkout interface
    "locales": ["en"], // Specifies the languages available for the checkout (English only in this case)
    "email": true, // Requires the user to provide an email address during checkout
    "tooltip": true, // Enables tooltips for additional guidance during the checkout process
    "fee": true // Displays the order amount (fee) during checkout
  },
  "params": {
    "merchant_id": 1396424, // The unique ID of the merchant account
    "required_rectoken": "y", // Requires a recurring token for subscription or future payments
    "currency": "USD", // Specifies the payment currency (US Dollars)
    "amount": 500, // Sets the payment amount in cents (500 = $5.00)
    "order_desc": "my_order_desc", // Sets the order description using the "my_order_desc" key from the "messages" object
    "response_url": "http://shop.com/thankyoupage", // URL to redirect users after successful payment
    "email": "", // Placeholder for the customer's email address (left blank initially)
    "lang": "pl" // Sets the default language for the checkout interface (Polish in this case)
  },
  "messages": {
    "pl": {
      "card_number": "Numer karty", // Label for the card number input field (in Polish)
      "my_title": "Cel płatności", // Title for the payment purpose (in Polish)
      "my_order_desc": "Płatność testowa", // Order description text (in Polish)
      "pay": "Zapłać" // Text on the payment button (in Polish)
    },
    "en": {
      "card_number": "Card number", // Label for the card number input field (in English)
      "my_title": "Order description", // Title for the payment purpose (in English)
      "my_order_desc": "Test order", // Order description text (in English)
      "pay": "Pay now" // Text on the payment button (in English)
    }
  }
}