Introduction

PayStand Checkout is a JavaScript library which provides an easy way for PayStand merchant customers to collect payment information and initiate a payment or scheduled payment in a PCI-DSS compliant way.

👍

PayStand Checkout facilitates 3 operational modes:

1. Payment (Direct) - Direct Payment Demo
2. Scheduled Payment - Scheduled Payment Demo
3. Save Card or Bank - Save Card or Bank Demo

In (Direct) Payment mode, PayStand checkout allows the user to instantly pay a defined amount of money to merchant customer.

The Scheduled Payment mode enables the user to initiate a pre-defined set of scheduled payments with the merchant customer.

Lastly in the Save Card or Bank mode, the payment method (card or bank) will be tokenized and saved for future use by the merchant's or platform provider's system.

Checkout Environments

Checkout operates in live mode or in sandbox mode. Attributes such as vanityName and publishableKey are often environment specific and often need to be changes when switching from one environment to another.

👍

Checkout modes

1. Live - In live mode, all api requests will be made against the production environment.
2. Sandbox - In sandbox mode, all api request will be made against the test environment. You can use this environment to test your integrations code.

Checkout Urls

You can access various checkout experiences directly via url. Urls can be used directly in a browser or used in an iframe to create an embedded experience.

📘

Billing Portal

When checkout is directly used in a browser using its URL, it is called a Billing Portal or for short a Portal. The use case for this type of checkout usage is typically to integrate checkout with environments that do not allow JavaScript code execution but do support URL references such as Emails, Invoices, etc.

To facilitate this type of usage PayStand provides a couple of useful features which can also be leveraged in non-portal checkout environments:

Vanity Names

A Vanity Name is a unique, human readable identification that can take the place of a cryptic customer identifier such as the publishable key.

Portal URL format

The portal URL format is a shorter and more pleasing URL format which can be used when people see the checkout or portal URL, or when the length of the URL needs to be limited.

View Portal

When the View Portal setting is active in the checkout configuration, checkout will render additional contextual HTML elements such as a separate header to improve full page rendering.

Presets

Presets are pre-defined checkout configurations that can be used instead of, or in conjunction with a detailed checkout configuration.

This is in particularly useful when using a direct URL for portal purposes as checkout configurations through URL parameters can become complicated or impossible in hurry.

Presets are configured via the merchant customer's dashboard or via the REST API.

Besides their usage in direct Portal URls, presets can be also be used in button URLs, auto loading, or in the checkout API.

Note: Each merchant customer also has a Default Preset which can be configure through the dashboard and which will be loaded by default if no other preset has been specified.

Url formats

Checkouts can be accessed by using any of the following url formats:

https://checkout.paystand.{envDomain}/v4/?publishableKey={publishableKey}
https://checkout.paystand.{envDomain}/v4/?vanity={vanityName}

https://{vanityName}-portal.paystand.{envDomain}
https://{publishableKey}-portal.paystand.{envDomain}

The envDomain for the live environment is com and for sandbox its co.

Configure via presets

To access a particular checkout preset (defined below) you can use the following formats:

https://checkout.paystand.{envDomain}/v4/?vanity={vanityName}&checkoutType={presetKey}

https://{vanityName}-portal.paystand.{envDomain}/{presetKey}

If no preset is given, then the default preset will be used. If you have not configured a default preset yet, a default payment checkout will be used.

Configure via url arguments

Additional url arguments allow further configuration of Checkout. Any valid checkout attribute or checkout abbreviation can be used as an url argument (see the associated reference sections for a list of available attributes and abbreviations).

If a preset is used, url arguments will override the specific preset values, leaving the rest of the preset settings as is.

API

Urls are very flexible when it comes to customizing the checkout experience on your webpage but are not suitable when there is a need for custom business logic. This means that you can't listen to checkout events, react to a checkout completing, or interact with the checkout in anyway once it has been rendered.

To use the checkout API, you can use checkout buttons, autoloading, or you can use the checkout api directly for maximum control of the checkout experience.

Buttons

Checkouts can be configured per button. When a user clicks on a button, the settings on the button are used (just as arguments in the urls above) to create a unique checkout experience. All buttons interact with the checkout api allowing you to listen to checkout events, react to status changes, and update checkout settings.

Buttons can render checkouts in two different modes:

Modals

Modals display a checkout that overlays the content of a webpage, focusing the user on the checkout experience.

Embeds

Embeds display a checkout in the flow of a webpage instead of overlaying the content. This can be useful if you want the user to interact with your website at the same time that the checkout is displayed.

Autoloading

Checkouts can be auto loaded once a web page loads. This can be useful if you want to have checkout embedded on your page without the user interacting with a button first. Checkout can only auto load once instance of a checkout.

Checkouts rendered via auto loading interact with the checkout api just as buttons do.

API

Checkout has a javascript api that interacts with checkout instances in various ways. The api can listen for checkout events, listen for checkout status changes, update the mode/dimensions for checkout, reboot, and live update checkout. See the API example and API reference section for further details.

Checkout instance

When using checkout using a url directly, the checkout instance is considered to be the webpage that renders directly. When using buttons, auto loading, or the API, the checkout instance is the iframe or window that displays the checkout experience.

Checkout limits each page to only one checkout instance. If, for example, you have multiple buttons on a web page, then each button will render a checkout in the same checkout instance.