This is the repository for Swedbank Pay Developer Portal. It is run as a Jekyll website on GitHub Pages.
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.
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.
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.
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.
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.
cd
into the directory in which you cloned (your
possible fork of) this repository.docker compose up
.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.
bundle install
inside
the root folder of this repository.bundle exec jekyll serve
to start the website.http://localhost:4000
in a browser.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:
Also in Visual Studio Code, set up a ruler at 80 characters
by adding "editor.rulers": [80]
to its configuration.
Following is a small guide to good to know features and conventions for writing and contributing to the documentation.
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.
paymentId
: this is used to replace the GUID
of the payment ID in request
and response examples.transactionId
: this is used to replace the GUID
of the transaction ID in
request and response examples.paymentOrderId
:this is used to replace the GUID
of the paymentOrder ID in
request and response examples.merchantId
:this is used to replace the GUID
of the merchant ID in request
and response examples.paymentToken
: This is used to replace the payment token GUID
for request
and response examples.apiHost
: This constant is used as a replacement for the API host name in requests and
responses.apiUrl
: This constant is used as a replacement for the API URL in request and
response examples.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 }}
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.
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]
example.com
, example.net
or example.org
should be used.
test-dummy.net
and similar "funny" domain names are strongly discouraged.rel
) of the operation instead of stating the URL explicitly, in order to
avoid the encouragement of client-side URL building.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.