API Reference

1. Checkout Settings

Delve into customizing the checkout experience with the checkout_settings JSON configurations. Learn how to tailor the user interface to align with your specific requirements.

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

  1. Summary Settings
    1. Controls the visibility and details of the summary section.
    2. Options include VAT display settings, itemization, and supplier information.
  2. Payer Information Settings
    1. Manages the display of payer information.
    2. Options for different customer types like individuals, companies, or both.
  3. Payment Method Settings
    1. Facilitates preselection of a payment method.
    2. Useful for setting a default payment method if available.
  4. 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

  1. Create the JSON Object
    1. Construct the checkout_settings JSON object with your desired configurations.
  2. Embed in Payment Link Metadata
    1. Include the checkout_settings object in the metadata attribute of your Payment Link API request.
  3. 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.

KeyTypeDescriptionDefault valuePossible Values
summary_settingsobjectSettings related to the summary section.See section belowSee section below
payer_information_settingsobjectSettings for payer information display.See section belowSee section below
payment_method_settingsobjectConfigurations for payment method options.See section belowSee section below
display_modeenumThe mode of display for the checkout.fullscreenfullscreen, box

Summary Settings

KeyTypeDescriptionDefault valuePossible Values
visiblebooleanControls the visibility of the summary section.truetrue, false
visible_headlinebooleanToggles the headline visibility above the summary.truetrue, false
display_price_including_vatbooleanDetermines if prices are displayed including VAT.truetrue, false
show_vat_row_for_each_itembooleanShows a VAT row for each item listed.truetrue, false
hide_vat_if_zero_vatbooleanHides VAT row if the VAT amount is zero.falsetrue, false
show_total_summarybooleanDisplays the total summary of the transaction.truetrue, false
show_total_vat_summarybooleanShows a summary of the total VAT.truetrue, false
indexintegerSets the order in which the summary appears in the checkout.2Numeric Value (e.g., 1, 2). If tied default order is applied.
collapsedbooleanDetermines if the summary is collapsed by default.truetrue, false
supplier_settingsobjectContains settings related to the supplier display.See supplier settings belowObject with keys as described

Supplier settings

KeyTypeDescriptionDefault valuePossible Values
visiblebooleanControls the visibility of the summary section.truetrue, false
collapsedbooleanDetermines if the summary is collapsed by default.truetrue, false

Payer Information Settings

KeyTypeDescriptionDefault valuePossible Values
visiblebooleanControls the visibility of the payer information section.truetrue, false
customer_typesenumDefines the type of customer information required.individuals_and_companiesindividuals_and_companies, individuals, companies
indexintegerSets the order in which the payer information appears.0Numeric Value (e.g., 1, 2). If tied default order is applied.

Payment Method Settings

KeyTypeDescriptionDefault valuePossible Values
preselected_payment_methodobjectDefines a preselected payment method, if available on the payment link.nullSee section below
indexintegerSets the order in which the Payment Method section appears.1Numeric Value (e.g., 1, 2). If tied default order is applied.

Preselected Payment Method

KeyTypeDescriptionDefault valuePossible Values
providerenumSpecifies the payment provider.nullswish, payment_iq
methodenumDefines the method of payment.nulle_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.