developer.swedbankpay.com

This is the repository for Swedbank Pay Developer Portal. It is run as a Jekyll website on GitHub Pages.

Contributing

Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct as well as Swedbank Pay Open Source Development Guidelines.

If you would like to perform development on the Developer Portal source code, you have two alternatives: to edit files directly through the GitHub website or to fork or clone the repository. These alternatives are described below.

Edit On GitHub

It's possible to edit existing pages directly on GitHub. The easiest way to go about doing that is finding the page you want to edit on developer.swedbankpay.com and clicking the GitHub icon in the upper right corner. It will take you to the corresponding Markdown file inside this repository, which you can then edit through the GitHub website.

Fork or Clone

If you want to add new pages or do larger changes, working on the repository locally in an editor and previewing the result in a web browser is better. To do that, you will have to fork or clone the repository.

If you don't have write-access to this repository, you need to fork it and then create a pull request from the fork in order to contribute.

If you have write-access to this repository (you know who you are), you should clone it and submit pull requests from branches you push directly within this repository itself.

After forking or cloning the repository, there's a few things you should set up locally before you can start coding, so please read on.

Git Hooks

After forking or cloning the repository, you need to set up the necessary Git hooks that ensure adherence to our development process.

Open a terminal in the root of the project repository and run the following:

git config core.hooksPath .githooks

This will set up a few checks to ensure your branch name and commit messages follow our standards.

Spin It Up

Once the Git hooks are set up, you have two options for how to spin up the developer portal locally; docker, or manual install. The Docker installation is recommended for its simplicity.

Docker

1. Install docker for your operating system.
2. Open up a terminal and cd into the directory in which you cloned (your possible fork of) this repository.
3. Run docker compose up.
4. After pulling the required Docker image and building the site, it should be accessible on http://localhost:4000*.

*Ignore the fact that Server address: http://0.0.0.0:4000 is written to the console; Jekyll is not aware of that it is executed within a Docker container.

Manual Install

1. Jekyll is written in Ruby, so you'll need to download and install that. If you're installing on Windows, choose setup with DevKit.
2. To install the Ruby Gems this web site requires, you first need to install Bundler.
3. Install Graphviz, this will require Java.
4. Once Ruby, Bundler, and Graphviz is in place, type bundle install inside the root folder of this repository.
5. Run bundle exec jekyll serve to start the website.
6. Open http://localhost:4000 in a browser.

Visual Studio Code Plugins

We recommend Visual Studio Code as an editor when developing on the developer portal. To ensure quality, structure and consistency between different developers and writers, we use a few Visual Studio Code plugins that you should install and configure:

• markdownlint, to lint Markdown files according to our defined set of rules.
• Markdown Preview Enhanced, to render Markdown to HTML in a preview window.
• Mermaid Markdown Syntax Highlighting, to give syntax highlighting to Mermaid diagrams in Markdown files.
• Markdown All in One, to enable a plethora of Markdown features, most importantly formatting of Markdown tables with Visual Studio Code's built-in format functionality.
• Rewrap, to make line-breaking text at 80 characters easier.
• Pretty js/json to format selected JSON snippets in code examples.
• Liquid for syntax highlighting of Liquid code.

Also in Visual Studio Code, set up a ruler at 80 characters by adding "editor.rulers": [80] to its configuration.

Good to know

Following is a small guide to good to know features and conventions for writing and contributing to the documentation.

Use constants

We have a list of expanding constants that are available on all pages. It can be found in the config file. These are found under defaults.values: and should be used where fitting.

1. paymentId: this is used to replace the GUID of the payment ID in request and response examples.
2. transactionId: this is used to replace the GUID of the transaction ID in request and response examples.
3. paymentOrderId:this is used to replace the GUID of the paymentOrder ID in request and response examples.
4. merchantId:this is used to replace the GUID of the merchant ID in request and response examples.
5. paymentToken: This is used to replace the payment token GUID for request and response examples.
6. apiHost: This constant is used as a replacement for the API host name in requests and responses.
7. apiUrl: This constant is used as a replacement for the API URL in request and response examples.
8. frontEndUrl: This constant is used as a replacement for frontend URLs in request and response examples.

Using these constants makes our documentation more resilient to change and makes it somewhat easier to read. Having only variables defined a singular place makes it possible to change environments and such in the future if a thing is wanted.

All constants are available trough the page variable. Example:

GET /psp/paymentorders/{{ page.payment_order_id }}/ HTTP/1.1
Host: {{ page.api_host }}

Use includes

In the folder _includes you'll find all ready to be used includes made in the project so far. These are made to be as reusable as possible with names being as explicit for its usage as possible.

Example showing how to use a simple include:

{% include payee-info.md %}

Some includes can also take variables, if they do this is defined at the beginning of the file using the following syntax.

{% assign transaction = include.transaction | default: "authorization" %}

This assigns "authorization" to the variable transaction by default if it isn't passed in via the include.

{% include transaction-response.md transaction="example" %}

Read more about passing arguments and how includes work here.

Mermaid

Having diagrams easy to read in Markdown as well as rendered in HTML makes maintaining it easier. Using mermaid-js to generate sequence diagrams is easy using our build system or the Mermaid Live Editor.

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

  activate SwedbankPay
  SwedbankPay->>-Merchant: POST <callbackUrl>
  activate Merchant
  note left of Merchant: Callback by SwedbankPay
  Merchant->>-SwedbankPay: GET [credit card payment]

Conventions

• Indentation is set to 4 spaces across all code examples, regardless of language. Please ensure that you format everything accordingly.
• When fictuous domain names are used in code examples, only example.com, example.net or example.org should be used. test-dummy.net and similar "funny" domain names are strongly discouraged.
• When describing operations performed towards a URL, reference the name (rel) of the operation instead of stating the URL explicitly, in order to avoid the encouragement of client-side URL building.

License

The code within this repository is available as open source under the terms of the Apache 2.0 License and the contributor's license agreement.