{"_id":"59825aa452e38e003452f84b","project":"55dd0853d2d97337001800e2","version":{"_id":"55de36ec9067202b00de0015","__v":33,"project":"55dd0853d2d97337001800e2","createdAt":"2015-08-26T22:00:12.384Z","releaseDate":"2015-08-26T22:00:12.383Z","categories":["55de36ed9067202b00de0016","55de36ed9067202b00de0017","55de36ed9067202b00de0018","55df7dcd437b3f0d004ba204","55e4e014177b6e0d00333141","55e4e01fe252ac0d00303a99","55e4e05240cda60d003bad67","55e4e070177b6e0d00333142","55e4e0753325e60d007fbee6","55e4e0803325e60d007fbee7","55e4e086177b6e0d00333143","55e4e0a1177b6e0d00333144","55e4e0aa3325e60d007fbee8","55e4e0b140cda60d003bad6b","55e4e0bae252ac0d00303a9d","55e4e0c5177b6e0d00333145","55e4e0ee3325e60d007fbeea","55e4e0fae252ac0d00303a9e","55e4e100177b6e0d00333147","55f85c8ba3271b0d00498d55","56092e1ac5cff70d007d0131","564b64a3ee12850d0095866e","564b64b5791099170071e9ea","565cd0bfd18ae50d007183d8","565f5f5d6bafd40d0030a063","565f790d6bafd40d0030a09f","56611c464851190d003f9f5d","56637d5b7988ab0d00d0522e","56637d687988ab0d00d0522f","567835df6928b40d009dd650","56e59c043c29b117008dae5b","5704013559c5190e000ab646","572be252de40590e00026934","58af1bf6ebd7370f0078ba09","5cdad81d912ece0039e9a939"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3.0"},"category":{"_id":"5704013559c5190e000ab646","version":"55de36ec9067202b00de0015","project":"55dd0853d2d97337001800e2","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-05T18:17:25.419Z","from_sync":false,"order":3,"slug":"paystand-checkout-1","title":"PayStand Checkout"},"user":"55dd080d0efd5821000d53b3","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-02T23:05:08.236Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"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.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"PayStand Checkout facilitates 3 operational modes:\",\n  \"body\": \"1. **Payment** (Direct) - [Direct Payment Demo](https://checkout.paystand.co/v4/demo/payment.html)\\n2. **Scheduled Payment** - [Scheduled Payment Demo](https://checkout.paystand.co/v4/demo/scheduled-payment.html)\\n3. **Save Card or Bank** -  [Save Card or Bank Demo](https://checkout.paystand.co/v4/demo/tokenize.html)\\n4. **Bank History Enrollment**\"\n}\n[/block]\nIn (Direct) **Payment mode**, PayStand checkout allows the user to instantly pay a defined amount of money to merchant customer.\n\nThe **Scheduled Payment mode** enables the user to initiate a pre-defined set of scheduled payments with the merchant customer.\n\nIn 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.\n\nLastly in the **Bank History Enrollment mode**, a user can log into their bank and select one of their bank accounts to enable the merchant to receive historical bank transactions for that account.\n\n\n## Checkout Environments\n\nCheckout 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.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Checkout modes\",\n  \"body\": \"1. **Live** - In live mode, all api requests will be made against the **production environment**.\\n2. **Sandbox** - In sandbox mode, all api request will be made against the **test environment**. You can use this environment to test your integrations code.\"\n}\n[/block]\n## Checkout Urls\n\nYou 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.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Billing Portal\",\n  \"body\": \"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.\\n\\nTo facilitate this type of usage PayStand provides a couple of useful features which can also be leveraged in non-portal checkout environments:\\n### Vanity Names\\nA Vanity Name is a unique, **human readable identification** that can take the place of a cryptic customer identifier such as the publishable key.\\n### Portal URL format\\nThe 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.\\n### View Portal\\nWhen 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**.\\n### Presets\\nPresets are pre-defined checkout configurations that can be used instead of, or in conjunction with a detailed checkout configuration.\\n\\nThis 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.\\n\\nPresets are configured via the merchant customer's dashboard or via the REST API.\\n\\nBesides their usage in direct Portal URls, presets can be also be used in button URLs, auto loading, or in the checkout API.\\n\\nNote: _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._\"\n}\n[/block]\n### Url formats\n\nCheckouts can be accessed by using any of the following url formats:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://checkout.paystand.{envDomain}/v4/?publishableKey={publishableKey}\\nhttps://checkout.paystand.{envDomain}/v4/?vanity={vanityName}\",\n      \"language\": \"css\",\n      \"name\": \"Checkout URL formats\"\n    },\n    {\n      \"code\": \"https://{vanityName}-portal.paystand.{envDomain}\\nhttps://{publishableKey}-portal.paystand.{envDomain}\",\n      \"language\": \"css\",\n      \"name\": \"Portal URL Format\"\n    }\n  ]\n}\n[/block]\nThe ```envDomain``` for the ```live``` environment is ```com``` and for ```sandbox``` its ```co```.\n\n\n### Configure via presets\n\nTo access a particular checkout preset (defined below) you can use the following formats:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://checkout.paystand.{envDomain}/v4/?vanity={vanityName}&checkoutType={presetKey}\",\n      \"language\": \"css\",\n      \"name\": \"Checkout URL with Preset\"\n    },\n    {\n      \"code\": \"https://{vanityName}-portal.paystand.{envDomain}/{presetKey}\",\n      \"language\": \"css\",\n      \"name\": \"Portal URL with Preset\"\n    }\n  ]\n}\n[/block]\nIf 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.\n\n### Configure via url arguments\n\nAdditional 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).\n\nIf a preset is used, url arguments will override the specific preset values, leaving the rest of the preset settings as is.\n\n## API\n\nUrls 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.\n\nTo 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.\n\n## Buttons\n\nCheckouts 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.\n\nButtons can render checkouts in two different modes:\n\n### Modals\n\nModals display a checkout that overlays the content of a webpage, focusing the user on the checkout experience.\n\n### Embeds\n\nEmbeds 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.\n\n## Autoloading\n\nCheckouts 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.\n\nCheckouts rendered via auto loading interact with the checkout api just as buttons do.\n\n## API\n\nCheckout 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.\n\n## Checkout instance\n\nWhen 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.\n\nCheckout 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.","excerpt":"","slug":"checkout-introduction","type":"basic","title":"Checkout Introduction"}

Checkout 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. [block:callout] { "type": "success", "title": "PayStand Checkout facilitates 3 operational modes:", "body": "1. **Payment** (Direct) - [Direct Payment Demo](https://checkout.paystand.co/v4/demo/payment.html)\n2. **Scheduled Payment** - [Scheduled Payment Demo](https://checkout.paystand.co/v4/demo/scheduled-payment.html)\n3. **Save Card or Bank** - [Save Card or Bank Demo](https://checkout.paystand.co/v4/demo/tokenize.html)\n4. **Bank History Enrollment**" } [/block] 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. 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. Lastly in the **Bank History Enrollment mode**, a user can log into their bank and select one of their bank accounts to enable the merchant to receive historical bank transactions for that account. ## 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. [block:callout] { "type": "success", "title": "Checkout modes", "body": "1. **Live** - In live mode, all api requests will be made against the **production environment**.\n2. **Sandbox** - In sandbox mode, all api request will be made against the **test environment**. You can use this environment to test your integrations code." } [/block] ## 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. [block:callout] { "type": "info", "title": "Billing Portal", "body": "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.\n\nTo facilitate this type of usage PayStand provides a couple of useful features which can also be leveraged in non-portal checkout environments:\n### Vanity Names\nA Vanity Name is a unique, **human readable identification** that can take the place of a cryptic customer identifier such as the publishable key.\n### Portal URL format\nThe 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.\n### View Portal\nWhen 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**.\n### Presets\nPresets are pre-defined checkout configurations that can be used instead of, or in conjunction with a detailed checkout configuration.\n\nThis 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.\n\nPresets are configured via the merchant customer's dashboard or via the REST API.\n\nBesides their usage in direct Portal URls, presets can be also be used in button URLs, auto loading, or in the checkout API.\n\nNote: _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._" } [/block] ### Url formats Checkouts can be accessed by using any of the following url formats: [block:code] { "codes": [ { "code": "https://checkout.paystand.{envDomain}/v4/?publishableKey={publishableKey}\nhttps://checkout.paystand.{envDomain}/v4/?vanity={vanityName}", "language": "css", "name": "Checkout URL formats" }, { "code": "https://{vanityName}-portal.paystand.{envDomain}\nhttps://{publishableKey}-portal.paystand.{envDomain}", "language": "css", "name": "Portal URL Format" } ] } [/block] 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: [block:code] { "codes": [ { "code": "https://checkout.paystand.{envDomain}/v4/?vanity={vanityName}&checkoutType={presetKey}", "language": "css", "name": "Checkout URL with Preset" }, { "code": "https://{vanityName}-portal.paystand.{envDomain}/{presetKey}", "language": "css", "name": "Portal URL with Preset" } ] } [/block] 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.