Overview

This guide provides instructions on how to configure the checkout experience for Ping Payments using the checkout_settings JSON structure. This configuration allows you to customize various aspects of the checkout interface to enhance user experience and align with your business requirements.

Checkout Settings Configuration

Structure of checkout_settings

The checkout_settings is a JSON object that is included in the metadata field of a Payment Link request. It comprises several key-value pairs that control different aspects of the checkout process.

Key Sections

Summary Settings
1. Controls the visibility and details of the summary section.
2. Options include VAT display settings, itemization, and supplier information.
Payer Information Settings
1. Manages the display of payer information.
2. Options for different customer types like individuals, companies, or both.
Payment Method Settings
1. Facilitates preselection of a payment method.
2. Useful for setting a default payment method if available.
Display Mode
1. Two modes: fullscreen and box.
2. fullscreen is recommended for iframe integrations, while box is better suited for redirect flows.

Default Values

If a specific field within checkout_settings is not specified, the system will revert to default behavior. If the entire checkout_settings JSON object is omitted, all default settings will apply.

Example of Default checkout_settings

{
    "summary_settings": {
        "visible": true,
        "visible_headline": true,
        "display_price_including_vat": true,
        "show_vat_row_for_each_item": true,
        "hide_vat_if_zero_vat": false,
        "show_total_summary": true,
        "show_total_vat_summary": true,
        "index": 2,
        "collapsed": true,
        "supplier_settings": {
            "visible": true,
            "collapsed": true
        }
    },
    "payer_information_settings": {
        "visible": true,
        "customer_types": "individuals_and_companies",
        "index": 0
    },
    "payment_method_settings": {
        "index": 1,
        "preselected_payment_method": null
    },
    "display_mode": "fullscreen"
}

Implementation Steps

Create the JSON Object
1. Construct the checkout_settings JSON object with your desired configurations.
Embed in Payment Link Metadata
1. Include the checkout_settings object in the metadata attribute of your Payment Link API request.
Send the API Request
1. With the custom settings in place, proceed to create the Payment Link through the API: https://docs.pingpayments.com/reference/createpaymentlink. This is also further explained in the next chapter of the documentation.

Best Practices

Validation: Ensure the JSON is correctly structured and formatted.

Testing: Experiment with different configurations to optimize the checkout experience.

Documentation: Keep this guide handy for reference during implementation.

Checkout Settings reference

Here follows reference for all the properties configurable for the checkout settings.

Key	Type	Description	Default value	Possible Values
`summary_settings`	object	Settings related to the summary section.	See section below	See section below
`payer_information_settings`	object	Settings for payer information display.	See section below	See section below
`payment_method_settings`	object	Configurations for payment method options.	See section below	See section below
`display_mode`	enum	The mode of display for the checkout.	`fullscreen`	`fullscreen`, `box`

Summary Settings

Key	Type	Description	Default value	Possible Values
`visible`	boolean	Controls the visibility of the summary section.	`true`	`true`, `false`
`visible_headline`	boolean	Toggles the headline visibility above the summary.	`true`	`true`, `false`
`display_price_including_vat`	boolean	Determines if prices are displayed including VAT.	`true`	`true`, `false`
`show_vat_row_for_each_item`	boolean	Shows a VAT row for each item listed.	`true`	`true`, `false`
`hide_vat_if_zero_vat`	boolean	Hides VAT row if the VAT amount is zero.	`false`	`true`, `false`
`show_total_summary`	boolean	Displays the total summary of the transaction.	`true`	`true`, `false`
`show_total_vat_summary`	boolean	Shows a summary of the total VAT.	`true`	`true`, `false`
`index`	integer	Sets the order in which the summary appears in the checkout.	2	Numeric Value (e.g., 1, 2). If tied default order is applied.
`collapsed`	boolean	Determines if the summary is collapsed by default.	`true`	`true`, `false`
`supplier_settings`	object	Contains settings related to the supplier display.	See supplier settings below	Object with keys as described

Supplier settings

Key	Type	Description	Default value	Possible Values
`visible`	boolean	Controls the visibility of the summary section.	`true`	`true`, `false`
`collapsed`	boolean	Determines if the summary is collapsed by default.	`true`	`true`, `false`

Payer Information Settings

Key	Type	Description	Default value	Possible Values
`visible`	boolean	Controls the visibility of the payer information section.	`true`	`true`, `false`
`customer_types`	enum	Defines the type of customer information required.	`individuals_and_companies`	`individuals_and_companies`, `individuals`, `companies`
`index`	integer	Sets the order in which the payer information appears.	0	Numeric Value (e.g., 1, 2). If tied default order is applied.

Payment Method Settings

Key	Type	Description	Default value	Possible Values
`preselected_payment_method`	object	Defines a preselected payment method, if available on the payment link.	`null`	See section below
`index`	integer	Sets the order in which the Payment Method section appears.	1	Numeric Value (e.g., 1, 2). If tied default order is applied.

Preselected Payment Method

Key	Type	Description	Default value	Possible Values
`provider`	enum	Specifies the payment provider.	`null`	`swish`, `payment_iq`
`method`	enum	Defines the method of payment.	`null`	`e_commerce`, `m_commerce`, `card`

Common questions regarding configuration

The checkout relies on the Payment Links object for some of the configuration and could therefore lead to confusion to what the checkout_settings JSON objects can change and what the Payment Links object can change. The following list covers all the things that is out of scope of the checkout_settings and in scope of the Payment Links object.

📘
How do I change the default language of the checkout?
This is done by locale on the Payment Links object.

📘
How do I change the order of the payment methods or the payment methods enabled in the checkout?
This is configured by the order of the payment_provider_methods on the Payment Links object. The payment provider method listed in that array is also the ones listed in the checkout, in case the checkout supports them.

📘
How do I change the pre-seeded customer information in the checkout?
This is configured by the customer object of the Payment Links object.

📘
How do I change the supplier information in the checkout?
This is configured by the supplier object of the Payment Links object.

📘
How do I change the items listed in the summary in the checkout?
This is configured by the items array of objects of the Payment Links object.